Självstudie: Använd API:er för Analytics Consumption Zone

Den här självstudien visar hur du använder hanterings-API:erna för Analytics Consumption Zone (ACZ) 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 Azure Data Manager for Energy (Developer eller Standard-nivå) instans i din Azure-prenumeration. Skapa en Azure Data Manager för Energy-instans.
• ACZ aktiverat för din instans. Se Aktivera konsumtionszon för analys.
• Azure CLI installerat och autentiserat (az login).
• cURL (för Bash-exempel) eller PowerShell 5.1+ (för PowerShell-exempel).

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

Samla in den här informationen från din Azure Data Manager for Energy-instans i Azure-portalen.

Innan du börjar

Kodexemplen i den här handledningen använder platshållarvärden i formatet {curly-braces}. Ersätt dessa platshållare med dina faktiska värden när du kör kommandona.

Alla API-anrop kräver autentisering. Exemplen för Bash och PowerShell visar hur token genereras direkt i kommandot med Azure CLI. Alternativa autentiseringsmetoder finns i Generera en autentiseringstoken.

Skapa en ACZ-instans

Använd Skapa ACZ API för att konfigurera en ny ACZ-instans för en datapartition.

API

POST /api/acz/v1/aczs

Viktiga punkter

• Du kan ha upp till tre ACZ-instanser per datapartition.
• 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 (se Aktivera analysförbrukningszon).
  • Tilldelades rollen Storage Blob Data Contributor på mållagringskontot för Azure Data Lake Storage Gen2.
• Ett Data Lake Storage Gen2 lagringskonto med ett hierarkiskt namnområde aktiverat krävs.

# Get auth app ID for your Azure Data Manager for Energy instance
AUTH_APP_ID=$(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 $AUTH_APP_ID --query accessToken -o tsv)

# Create ACZ instance
curl --request POST \
  --url https://{base-url}/api/acz/v1/aczs \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'data-partition-id: {data-partition-id}' \
  --data '{
    "name": "{acz-name}",
    "aczType": "{acz-type}",
    "targetFormat": "DELTA_PARQUET",
    "allCatalogSync": false,
    "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 Azure Data Manager for Energy 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"
    allCatalogSync = $false
    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 instance
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

Ersätt platshållarna

Du måste ange minst ett av följande alternativ:

• Ange "allCatalogSync": true (utanför konfigurationen).
• Ange catalogKinds matrisen i konfigurationen med minst ett typmönster.
• Ange wellboreDDMSKinds matrisen i konfigurationen med minst ett typmönster.

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"
  },
  "allCatalogSync": false,
  "configuration": {
    "catalogKinds": [
      "osdu:wks:master-data--Well:*",
      "osdu:wks:reference-data--UnitOfMeasure:*"
    ],
    "wellboreDDMSKinds": [
      "osdu:wks:work-product-component--WellLog:*"
    ]
  },
  "historicalSnapshotStatus": "PROCESSING",
  "maintenance": [],
  "createdTs": "2026-03-31T10:00:00Z",
  "updatedTs": "2026-03-31T10:00:00Z",
  "createdBy": "user@contoso.com",
  "catalogSchemaVersion": 2
}

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

Lista ACZ-instanser

Använd API:et List ACZs för att hämta alla ACZ-instanser i en datapartition.

API

GET /api/acz/v1/aczs

# Get auth app ID for your Azure Data Manager for Energy instance
AUTH_APP_ID=$(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 $AUTH_APP_ID --query accessToken -o tsv)

# List ACZ instances
curl --request GET \
  --url https://{base-url}/api/acz/v1/aczs \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Accept: application/json' \
  --header 'data-partition-id: {data-partition-id}'

# Get auth app ID for your Azure Data Manager for Energy 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 ACZ instances
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}"
}

Ersätt platshållarna

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"
      },
      "allCatalogSync": false,
      "configuration": {
        "catalogKinds": [
          "osdu:wks:master-data--Well:*"
        ]
      },
      "historicalSnapshotStatus": "PROCESSING",
      "maintenance": [],
      "createdTs": "2026-03-31T10:00:00Z",
      "updatedTs": "2026-03-31T10:00:00Z",
      "createdBy": "user@contoso.com",
      "catalogSchemaVersion": 2
    },
    {
      "aczId": "acz-xyz789ghi012",
      "name": "all-catalog-sync-example",
      "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"
      },
      "allCatalogSync": true,
      "configuration": {
        "wellboreDDMSKinds": [
          "osdu:wks:work-product-component--WellLog:*"
        ]
      },
      "historicalSnapshotStatus": "COMPLETED",
      "maintenance": [
        {
          "activity": "OPTIMIZE_Z_ORDER",
          "status": "SUCCEEDED",
          "lastAttemptTs": "2026-04-01T03:00:00Z",
          "lastSuccessfulTs": "2026-04-01T03:00:12Z"
        },
        {
          "activity": "VACUUM",
          "status": "SUCCEEDED",
          "lastAttemptTs": "2026-04-01T03:00:12Z",
          "lastSuccessfulTs": "2026-04-01T03:00:13Z"
        }
      ],
      "createdTs": "2026-03-31T09:00:00Z",
      "updatedTs": "2026-03-31T09:45:00Z",
      "createdBy": "user@contoso.com",
      "catalogSchemaVersion": 2
    }
  ],
  "count": 2
}

Svaret listar alla ACZ-instanser oavsett status: ACTIVE, FAILED eller ACCESS_DENIED. Det här svaret visar två ACZ-instanser: en med selektiv katalogsynkronisering (allCatalogSync: false med specifika typer) och en annan som använder allCatalogSync: true för att exportera alla katalogtyper.

Hämta ACZ-information

Använd Get ACZ API (Hämta ACZ API) för att få information om en specifik ACZ-instans.

API

GET /api/acz/v1/aczs/{acz-id}

# Get auth app ID for your Azure Data Manager for Energy instance
AUTH_APP_ID=$(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 $AUTH_APP_ID --query accessToken -o tsv)

# Get ACZ details
curl --request GET \
  --url https://{base-url}/api/acz/v1/aczs/{acz-id} \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Accept: application/json' \
  --header 'data-partition-id: {data-partition-id}'

# Get auth app ID for your Azure Data Manager for Energy 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 platshållarna

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"
  },
  "allCatalogSync": false,
  "configuration": {
    "catalogKinds": [
      "osdu:wks:master-data--Well:*",
      "osdu:wks:reference-data--UnitOfMeasure:*"
    ],
    "wellboreDDMSKinds": [
      "osdu:wks:work-product-component--WellLog:*"
    ]
  },
  "historicalSnapshotStatus": "COMPLETED",
  "maintenance": [
    {
      "activity": "OPTIMIZE_Z_ORDER",
      "status": "SUCCEEDED",
      "lastAttemptTs": "2026-04-01T03:00:00Z",
      "lastSuccessfulTs": "2026-04-01T03:00:12Z"
    },
    {
      "activity": "VACUUM",
      "status": "SUCCEEDED",
      "lastAttemptTs": "2026-04-01T03:00:12Z",
      "lastSuccessfulTs": "2026-04-01T03:00:13Z"
    }
  ],
  "createdTs": "2026-03-31T10:00:00Z",
  "updatedTs": "2026-03-31T10:30:00Z",
  "createdBy": "user@contoso.com",
  "catalogSchemaVersion": 2
}

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

Svaret inkluderar också:

• catalogSchemaVersion: Schemaversionen av osducatalog tabellen. Nya ACZ-instanser använder version 2, som lägger till modifyUser och modifyTime kolumnerna. För detaljer, se Analytics Consumption Zone-koncept.
• maintenance: Status för Delta-tabellens underhållsaktiviteter som ACZ kör (OPTIMIZE_Z_ORDER och VACUUM), inklusive sista försökstid och sista lyckade körtid. Arrayen är tom fram till den första underhållskörningen.

Ta bort en ACZ-instans

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

API

DELETE /api/acz/v1/aczs/{acz-id}

# Get auth app ID for your Azure Data Manager for Energy instance
AUTH_APP_ID=$(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 $AUTH_APP_ID --query accessToken -o tsv)

# Delete ACZ instance
curl --request DELETE \
  --url https://{base-url}/api/acz/v1/aczs/{acz-id} \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Accept: application/json' \
  --header 'data-partition-id: {data-partition-id}'

# Get auth app ID for your Azure Data Manager for Energy 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 instance
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}"
}

Ersätt platshållarna

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
• Export av rättigheter i Analytics Consumption Zone (förhandsvisning)