Självstudiekurs: Använd API:er för förbrukningszon för analys (ACZ)

Den här självstudien visar hur du använder ACZ-hanterings-API:er i Azure Data Manager for Energy. Du skapar, listar, hämtar och tar bort ACZ-instanser med hjälp av cURL.

I den här tutorialen lär du dig följande:

Förutsättningar

• Ett Azure-abonnemang. Skapa en kostnadsfritt.
• En instans av Azure Data Manager for Energy (developer tier) i din Azure-prenumeration. Skapa en Azure Data Manager för Energy-instans.
• ACZ aktiverat för din instans. Se Så här aktiverar du Analysförbrukningszonen (ACZ).
• Ett Azure Data Lake Storage (ADLS) Gen2-lagringskonto med hierarkiskt namnområde aktiverat, där användartilldelad hanterad identitet tillåts för ACZ-åtgärder har Storage Blob Data Contributor roll.
• Ditt användarkonto måste tillhöra users@{data-partition-id}.dataservices.energy berättigandegruppen för att anropa ACZ-API:er. Se Så här hanterar du användare.
• cURL installerat på datorn (för bash-exempel) eller PowerShell 5.1+ (för PowerShell-exempel).
• Azure CLI installerat och autentiserat.
• En åtkomsttoken för autentisering. Se Så här genererar du autentiseringstoken.

Hämta information om din Azure Data Manager for Energy-instans

Samla in den här informationen från din Azure Data Manager för Energy-instans i Azure-portalen:

Generera en access_token för autentisering genom att följa anvisningarna i Generera autentiseringstoken.

Skapa en ACZ

Använd Create ACZ API (Skapa ACZ API) för att konfigurera en ny analysförbrukningszon för en datapartition.

API: POST /api/acz/v1/aczs

Viktiga punkter:

• Högst tre ACZs per datapartition (gräns i förhandsversion).
• ACZ-namnet måste vara unikt i partitionen.
• Den användartilldelade hanterade identiteten måste vara:
  • Tilldelad till din Azure Data Manager för energiresurs
  • Tilldelades rollen Storage Blob Data Contributor på ADLS Gen2-lagringskontot på målsidan
• Användaren måste tillhöra berättigandegruppen users@{data-partition-id}.dataservices.energy .

curl --request POST \
  --url https://{base-url}/api/acz/v1/aczs \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --header 'data-partition-id: {data-partition-id}' \
  --data '{
    "name": "{acz-name}",
    "aczType": "{acz-type}",
    "targetFormat": "DELTA_PARQUET",
    "sink": {
      "storageType": "microsoft.storage/storageaccounts",
      "storageId": "{storage-resource-id}",
      "basePath": "{base-path}"
    },
    "configuration": {
      "catalogKinds": {catalog-kinds},
      "wellboreDDMSKinds": {wellbore-ddms-kinds}
    }
  }'

# Get auth app ID for your ADME instance
$authAppId = az resource show --ids /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.OpenEnergyPlatform/energyServices/{adme-instance-name} --query properties.authAppId -o tsv

# Get access token
$token = az account get-access-token --resource $authAppId --query accessToken -o tsv

# Build request body
$body = @{
    name = "{acz-name}"
    aczType = "{acz-type}"
    targetFormat = "DELTA_PARQUET"
    sink = @{
        storageType = "microsoft.storage/storageaccounts"
        storageId = "{storage-resource-id}"
        basePath = "{base-path}"
    }
    configuration = @{
        catalogKinds = @("{catalog-kinds}")
        wellboreDDMSKinds = @("{wellbore-ddms-kinds}")
    }
} | ConvertTo-Json -Depth 10

# Create ACZ
Invoke-RestMethod -Uri "https://{base-url}/api/acz/v1/aczs" -Method Post -Headers @{
    "Authorization" = "Bearer $token"
    "Content-Type" = "application/json"
    "data-partition-id" = "{data-partition-id}"
} -Body $body

Parametrar för begäran

Parametrar för begärandetext

Exempelsvar (201 Skapad)

{
  "aczId": "acz-abc123def456",
  "name": "my-acz-wells-and-logs",
  "status": "ACTIVE",
  "aczType": "LATEST_VERSION",
  "targetFormat": "DELTA_PARQUET",
  "sink": {
    "storageType": "microsoft.storage/storageaccounts",
    "storageId": "/subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{account}",
    "basePath": "acz-output"
  },
  "configuration": {
    "catalogKinds": [
      "osdu:wks:master-data--Well:*",
      "osdu:wks:reference-data--UnitOfMeasure:*"
    ],
    "wellboreDDMSKinds": [
      "osdu:wks:work-product-component--WellLog:*"
    ]
  },
  "historicalSnapshotStatus": "PROCESSING",
  "createdTs": "2026-03-31T10:00:00Z",
  "updatedTs": "2026-03-31T10:00:00Z",
  "createdBy": "user@contoso.com"
}

När du har skapat ACZ påbörjar den den historiska ögonblicksbilden med PROCESSING-tillstånd. Använd API:et Hämta ACZ för att kontrollera statusen.

Lista ACZ:er

Använd API:et List ACZs för att hämta alla analysförbrukningszoner i en datapartition.

API: GET /api/acz/v1/aczs

curl --request GET \
  --url https://{base_url}/api/acz/v1/aczs \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Accept: application/json' \
  --header 'data-partition-id: {data_partition_id}'

# Get auth app ID for your ADME instance
$authAppId = az resource show --ids /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.OpenEnergyPlatform/energyServices/{adme-instance-name} --query properties.authAppId -o tsv

# Get access token
$token = az account get-access-token --resource $authAppId --query accessToken -o tsv

# List ACZs
Invoke-RestMethod -Uri "https://{base_url}/api/acz/v1/aczs" -Method Get -Headers @{
    "Authorization" = "Bearer $token"
    "Accept" = "application/json"
    "data-partition-id" = "{data_partition_id}"
}

Exempelsvar (200 OK)

{
  "items": [
    {
      "aczId": "acz-abc123def456",
      "name": "my-acz-wells-and-logs",
      "status": "ACTIVE",
      "aczType": "LATEST_VERSION",
      "targetFormat": "DELTA_PARQUET",
      "sink": {
        "storageType": "microsoft.storage/storageaccounts",
        "storageId": "/subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{account}",
        "basePath": "acz-output"
      },
      "configuration": {
        "catalogKinds": [
          "osdu:wks:master-data--Well:*",
          "osdu:wks:reference-data--UnitOfMeasure:*"
        ],
        "wellboreDDMSKinds": [
          "osdu:wks:work-product-component--WellLog:*"
        ]
      },
      "historicalSnapshotStatus": "COMPLETED",
      "createdTs": "2026-03-31T10:00:00Z",
      "updatedTs": "2026-03-31T10:30:00Z",
      "createdBy": "user@contoso.com"
    }
  ],
  "count": 1
}

Svaret listar alla ACZ:er oavsett status: ACTIVE, FAILED eller ACCESS_DENIED.

Hämta ACZ-information

Använd Api:et Hämta ACZ för att få information om en specifik ACZ.

API: GET /api/acz/v1/aczs/{acz_id}

curl --request GET \
  --url https://{base_url}/api/acz/v1/aczs/{acz_id} \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Accept: application/json' \
  --header 'data-partition-id: {data_partition_id}'

# Get auth app ID for your ADME instance
$authAppId = az resource show --ids /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.OpenEnergyPlatform/energyServices/{adme-instance-name} --query properties.authAppId -o tsv

# Get access token
$token = az account get-access-token --resource $authAppId --query accessToken -o tsv

# Get ACZ details
Invoke-RestMethod -Uri "https://{base_url}/api/acz/v1/aczs/{acz_id}" -Method Get -Headers @{
    "Authorization" = "Bearer $token"
    "Accept" = "application/json"
    "data-partition-id" = "{data_partition_id}"
}

Ersätt {acz_id} med ACZ-identifieraren från svaret Skapa eller Lista.

Exempelsvar (200 OK)

{
  "aczId": "acz-abc123def456",
  "name": "my-acz-wells-and-logs",
  "status": "ACTIVE",
  "aczType": "LATEST_VERSION",
  "targetFormat": "DELTA_PARQUET",
  "sink": {
    "storageType": "microsoft.storage/storageaccounts",
    "storageId": "/subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{account}",
    "basePath": "acz-output"
  },
  "configuration": {
    "catalogKinds": [
      "osdu:wks:master-data--Well:*",
      "osdu:wks:reference-data--UnitOfMeasure:*"
    ],
    "wellboreDDMSKinds": [
      "osdu:wks:work-product-component--WellLog:*"
    ]
  },
  "historicalSnapshotStatus": "COMPLETED",
  "createdTs": "2026-03-31T10:00:00Z",
  "updatedTs": "2026-03-31T10:30:00Z",
  "createdBy": "user@contoso.com"
}

Spåra etablering av ACZ genom att kontrollera fälten status och historicalSnapshotStatus.

Ta bort en ACZ

Använd Ta bort ACZ-API:et för att ta bort en ACZ-konfiguration.

API: DELETE /api/acz/v1/aczs/{acz_id}

curl --request DELETE \
  --url https://{base_url}/api/acz/v1/aczs/{acz_id} \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Accept: application/json' \
  --header 'data-partition-id: {data_partition_id}'

# Get auth app ID for your ADME instance
$authAppId = az resource show --ids /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.OpenEnergyPlatform/energyServices/{adme-instance-name} --query properties.authAppId -o tsv

# Get access token
$token = az account get-access-token --resource $authAppId --query accessToken -o tsv

# Delete ACZ
Invoke-RestMethod -Uri "https://{base_url}/api/acz/v1/aczs/{acz_id}" -Method Delete -Headers @{
    "Authorization" = "Bearer $token"
    "Accept" = "application/json"
    "data-partition-id" = "{data_partition_id}"
}

Exempelsvar (204 Inget innehåll)

En lyckad borttagning returnerar HTTP 204 utan svarstext. ACZ-status ändras till DELETING medan rensningen pågår.

Felsvar

ACZ-API:erna returnerar följande felkoder:

Relaterat innehåll

• Anslut ACZ-data till Microsoft Fabric
• Anslut ACZ-data till Azure Databricks
• Begrepp för analyskonsumtionszoner