Zelfstudie: API's voor analyseverbruikszones gebruiken

Deze zelfstudie laat zien hoe u de ACZ-beheer-API's (Analytics Consumption Zone) gebruikt in Azure Data Manager for Energy. U maakt, vermeldt, ophaalt en verwijdert ACZ-exemplaren met behulp van cURL.

Tijdens de preview is ACZ alleen beschikbaar op instanties van de developer-laag en is het gebruik van acceptatielijsten vereist. Volg de richtlijnen in De verbruikszone voor analyse inschakelen en neem contact op met uw Microsoft vertegenwoordiger.

In deze handleiding leer je hoe je:

Prerequisites

• Een Azure-abonnement. Maak er gratis een.
• Een instantie van Azure Data Manager for Energy (Developer-niveau) in uw Azure-abonnement. Maak een Azure Data Manager for Energy-exemplaar.
• ACZ ingeschakeld voor uw instantie. Zie Analytics Consumption Zone inschakelen.
• De Azure CLI geïnstalleerd en geverifieerd (az login).
• cURL (voor Bash-voorbeelden) of PowerShell 5.1+ (voor PowerShell-voorbeelden).

De details van uw Azure Data Manager for Energy-exemplaar ophalen

Verzamel deze gegevens van uw Azure Data Manager for Energy-exemplaar in de Azure-portal.

Voordat u begint

De codevoorbeelden in deze tutorial gebruiken plaatsaanduidingswaarden in de notatie {curly-braces}. Vervang deze tijdelijke aanduidingen door uw werkelijke waarden wanneer u de opdrachten uitvoert.

Voor alle API-aanroepen is verificatie vereist. De Bash- en PowerShell-voorbeelden laten zien hoe je inline tokens genereert met de Azure CLI. Zie Een verificatietoken genereren voor alternatieve verificatiemethoden.

Een ACZ-exemplaar maken

Gebruik de Create ACZ API om een nieuw ACZ-exemplaar op te zetten voor een datapartitie.

API

POST /api/acz/v1/aczs

Belangrijkste punten

• Maximaal drie ACZ-exemplaren per gegevenspartitie (preview-limiet).
• De ACZ-naam moet uniek zijn binnen de partitie.
• De door de gebruiker toegewezen beheerde identiteit moet:
  • Toegewezen aan uw Azure Data Manager voor Energieresource (zie Gebruikszone analyse inschakelen).
  • De rol 'Storage Blob Data Contributor' is toegewezen aan het Azure Data Lake Storage Gen2-opslagaccount als bestemming.
• Een Data Lake Storage Gen2-opslagaccount waarvoor een hiërarchische naamruimte is ingeschakeld, is vereist.

# 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

Vervang de plaatsaanduidingen

U moet ten minste een van de volgende opties opgeven:

• Instellen "allCatalogSync": true (buiten de configuratie).
• Geef in de configuratie een catalogKinds array op met ten minste één kindpatroon.
• Geef in de configuratie een wellboreDDMSKinds array op met ten minste één typepatroon.

Voorbeeldreactie (201 Aangemaakt)

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

Nadat u het ACZ-exemplaar hebt gemaakt, wordt de historische momentopname met de PROCESSING status gestart. Gebruik de Get ACZ-API om de status te controleren.

ACZ-exemplaren weergeven

Gebruik de API List ACZs om alle ACZ-exemplaren op te halen in een gegevenspartitie.

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

Vervang de plaatsaanduidingen

Voorbeeldantwoord (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
}

Het antwoord bevat alle ACZ-exemplaren in elke status: ACTIVE, FAILEDof ACCESS_DENIED. Dit antwoord toont twee ACZ-exemplaren: één met selectieve catalogussynchronisatie (allCatalogSync: false met specifieke soorten) en een andere met het exporteren allCatalogSync: true van alle catalogustypen.

ACZ-details ophalen

Gebruik de Get ACZ-API om details op te halen voor een specifiek ACZ-exemplaar.

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

Vervang de plaatsaanduidingen

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

Om ACZ-provisioning bij te houden, controleert u de velden status en historicalSnapshotStatus.

Een ACZ-exemplaar verwijderen

Gebruik de Delete ACZ-API om een ACZ-configuratie te verwijderen.

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

Vervang de plaatsaanduidingen

Voorbeeldantwoord (204 Geen inhoud)

Een geslaagde verwijdering retourneert HTTP 204 zonder antwoordtekst. De ACZ-status verandert in DELETING terwijl het opschonen wordt uitgevoerd.

Foutreacties

De ACZ-API's retourneren de volgende foutcodes.

Verwante inhoud

• Connect ACZ-gegevens met Microsoft Fabric
• Connect ACZ-gegevens met Azure Databricks
• Concepten van de Analytics-consumptiezone