Tutorial: Verwenden der Analytics-Consumption-Zone-APIs

In diesem Lernprogramm wird gezeigt, wie Sie die ACZ-Verwaltungs-APIs (Analytics Consumption Zone) in Azure Data Manager for Energy verwenden. Sie erstellen, listen, abrufen und löschen ACZ-Instanzen mithilfe von cURL.

Während der Vorschau ist ACZ nur für Entwicklerebeneninstanzen verfügbar und erfordert die Verwendung von Zulassungslisten. Befolgen Sie die Anleitungen in der Zone "Analysenutzung aktivieren", und wenden Sie sich an Ihren Microsoft Vertreter.

In diesem Tutorial erfahren Sie, wie:

Voraussetzungen

• Ein Azure-Abonnement. Erstellen Sie ein kostenloses Konto.
• Eine Azure Data Manager for Energy-Instanz (Entwicklerstufe) in Ihrem Azure-Abonnement. Erstellen Sie einen Azure Data Manager für Energieinstanzen.
• ACZ wurde für Ihre Instanz aktiviert. Siehe "Analysenutzungszone aktivieren".
• Azure CLI installiert und authentifiziert (az login).
• cURL (für Bash-Beispiele) oder PowerShell 5.1+ (für PowerShell-Beispiele).

Rufen Sie die Details Ihrer Azure Data Manager for Energy-Instanz ab

Sammeln Sie diese Details aus Ihrem Azure Data Manager für Energieinstanz im Azure-Portal.

Bevor Sie anfangen

In den Codebeispielen in diesem Lernprogramm werden Platzhalterwerte im {curly-braces} Format verwendet. Ersetzen Sie diese Platzhalter durch Ihre tatsächlichen Werte, wenn Sie die Befehle ausführen.

Alle API-Aufrufe erfordern eine Authentifizierung. Die Bash- und PowerShell-Beispiele zeigen die Inlinetokengenerierung mithilfe der Azure CLI. Alternative Authentifizierungsmethoden finden Sie unter Generieren eines Authentifizierungstokens.

Erstellen einer ACZ-Instanz

Verwenden Sie die Create ACZ-API, um eine neue ACZ-Instanz für eine Datenpartition einzurichten.

API

POST /api/acz/v1/aczs

Wichtige Punkte

• Maximal drei ACZ-Instanzen pro Datenpartition (Vorschaulimit).
• Der ACZ-Name muss innerhalb der Partition eindeutig sein.
• Die vom Benutzer zugewiesene verwaltete Identität muss folgendes sein:
  • Ihrer Azure Data Manager for Energy-Ressource zugewiesen (siehe Analyseverbrauchszone aktivieren).
  • Die Rolle „Mitwirkender an Storage-Blobdaten“ wurde für das Zielspeicherkonto von Azure Data Lake Storage Gen2 gewährt.
• Ein Data Lake Storage Gen2 Speicherkonto mit aktiviertem hierarchischen Namespace ist erforderlich.

# 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

Ersetzen Sie die Platzhalter

Sie müssen mindestens eine der folgenden Optionen angeben:

• Festlegen "allCatalogSync": true (außerhalb der Konfiguration).
• Stellen Sie ein catalogKinds-Array in der Konfiguration mit mindestens einem Typmuster bereit.
• Stellen Sie ein wellboreDDMSKinds-Array in der Konfiguration mit mindestens einem Typmuster bereit.

Beispielantwort (201 Erstellt)

{
  "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",
  "createdTs": "2026-03-31T10:00:00Z",
  "updatedTs": "2026-03-31T10:00:00Z",
  "createdBy": "user@contoso.com"
}

Nachdem Sie die ACZ-Instanz erstellt haben, beginnt sie mit der historischen Momentaufnahme mit dem PROCESSING-Zustand. Verwenden Sie die Get ACZ-API, um den Status zu überprüfen.

ACZ-Instanzen auflisten

Verwenden Sie die LIST ACZs-API, um alle ACZ-Instanzen in einer Datenpartition abzurufen.

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}"
}

Ersetzen Sie die Platzhalter

Beispielantwort (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",
      "createdTs": "2026-03-31T10:00:00Z",
      "updatedTs": "2026-03-31T10:00:00Z",
      "createdBy": "user@contoso.com"
    },
    {
      "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",
      "createdTs": "2026-03-31T09:00:00Z",
      "updatedTs": "2026-03-31T09:45:00Z",
      "createdBy": "user@contoso.com"
    }
  ],
  "count": 2
}

Die Antwort listet alle ACZ-Instanzen in einem beliebigen Status auf: ACTIVE, , , FAILEDoder ACCESS_DENIED. Diese Antwort zeigt zwei ACZ-Instanzen: eine mit selektiver Katalogsynchronisierung (allCatalogSync: false mit bestimmten Arten) und eine andere, allCatalogSync: true die zum Exportieren aller Katalogtypen verwendet wird.

ACZ-Details abrufen

Verwenden Sie die Get ACZ-API, um Details zu einer bestimmten ACZ-Instanz abzurufen.

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}"
}

Ersetzen Sie die Platzhalter

Beispielantwort (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",
  "createdTs": "2026-03-31T10:00:00Z",
  "updatedTs": "2026-03-31T10:30:00Z",
  "createdBy": "user@contoso.com"
}

Um die ACZ-Bereitstellung zu verfolgen, überprüfen Sie die Felder status und historicalSnapshotStatus.

Löschen einer ACZ-Instanz

Verwenden Sie die Delete ACZ-API, um eine ACZ-Konfiguration zu entfernen.

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}"
}

Ersetzen Sie die Platzhalter

Beispielantwort (204 Kein Inhalt)

Ein erfolgreicher Löschvorgang gibt HTTP 204 ohne Antworttext zurück. Der ACZ-Status ändert sich zu DELETING, während die Bereinigung ausgeführt wird.

Fehlerantworten

Die ACZ-APIs geben die folgenden Fehlercodes zurück.

Verwandte Inhalte

• ACZ-Daten mit Microsoft Fabric verbinden
• Verbinden von ACZ-Daten mit Azure Databricks
• Konzepte der Analytics-Nutzungszone