Tutorial: Utilizar APIs da Zona de Consumo do Analytics

Este tutorial mostra como utilizar as APIs de gestão da Zona de Consumo de Análise (ACZ) no Azure Data Manager for Energy. Cria, lista, recupera e elimina instâncias ACZ usando cURL.

Durante a pré-visualização, o ACZ está disponível apenas em instâncias de nível Developer e requer o uso de listas de autorizações. Siga as orientações em Ativar Zona de Consumo de Análises e contacte o seu representante da Microsoft.

Neste tutorial, aprenderás como:

Pré-requisitos

• Uma assinatura do Azure. Crie um gratuitamente.
• Uma instância Azure Data Manager for Energy (nível Developer) na sua subscrição do Azure. Crie um Azure Data Manager para uma instância de Energia.
• ACZ ativado para a tua instância. Consulte Ativar a zona de consumo de analítica.
• A CLI do Azure instalada e autenticada (az login).
• cURL (para exemplos de Bash) ou PowerShell 5.1+ (para exemplos de PowerShell).

Obtenha os detalhes da sua instância Azure Data Manager for Energy

Recolha estes dados na sua instância Azure Data Manager for Energy no portal Azure.

Antes de começar

Os exemplos de código neste tutorial usam valores provisórios no {curly-braces} formato. Substitui esses marcadores de posição pelos teus valores reais quando executares os comandos.

Todas as chamadas de API requerem autenticação. Os exemplos de Bash e PowerShell mostram geração de tokens inline usando a CLI do Azure. Para métodos alternativos de autenticação, veja Gerar um token de autenticação.

Criar uma instância ACZ

Use a API Create ACZ para configurar uma nova instância ACZ para uma partição de dados.

API

POST /api/acz/v1/aczs

Pontos principais

• No máximo, três instâncias ACZ por partição de dados (limite da versão preliminar).
• O nome ACZ deve ser único dentro da partição.
• A identidade gerida atribuída pelo utilizador deve ser:
  • Atribuído ao recurso Azure Data Manager for Energy (veja Ativar a Zona de Consumo de Análise).
  • Foi concedida a função Storage Blob Data Contributor na conta de armazenamento de destino do Azure Data Lake Storage Gen2.
• É necessária uma conta de armazenamento Data Lake Storage Gen2 com um namespace hierárquico ativado.

# 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

Substitua os marcadores

Deve fornecer pelo menos uma das seguintes opções:

• Definir "allCatalogSync": true (fora da configuração).
• Forneça na configuração o array catalogKinds com pelo menos um padrão de tipo.
• Forneça um array wellboreDDMSKinds na configuração com pelo menos um padrão de tipo.

Exemplo de resposta (201 Criado)

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

Depois de criar a instância ACZ, é iniciado o instantâneo histórico com o estado PROCESSING. Usa a API do Get ACZ para verificar o estado.

Lista de instâncias ACZ

Use a API List ACZs para obter todas as instâncias ACZ numa partição de dados.

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

Substitua os marcadores

Resposta de exemplo (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
}

A resposta lista todas as instâncias ACZ em qualquer estado: ACTIVE, FAILED, ou ACCESS_DENIED. Esta resposta mostra duas instâncias ACZ: uma usando sincronização seletiva de catálogo (allCatalogSync: false com tipos específicos) e outra usada allCatalogSync: true para exportar todos os tipos de catálogo.

Obtenha os detalhes da ACZ

Use a API Get ACZ para obter detalhes de uma instância ACZ específica.

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

Substitua os marcadores

Resposta de exemplo (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"
}

Para acompanhar o provisionamento do ACZ, verifique os campos status e historicalSnapshotStatus.

Eliminar uma instância ACZ

Use a API Delete ACZ para remover uma configuração ACZ.

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

Substitua os marcadores

Resposta de exemplo (204 Sem Conteúdo)

Uma eliminação bem-sucedida devolve HTTP 204 sem corpo de resposta. O estado ACZ altera-se para DELETING enquanto decorre a limpeza.

Respostas de erro

As APIs ACZ devolvem os seguintes códigos de erro.

Conteúdo relacionado

• Ligue dados ACZ a Microsoft Fabric
• Ligue dados ACZ a Azure Databricks
• Conceitos da Área de Consumo de Analítica