Ativar a Zona de Consumo de Analítica

Este artigo explica como ativar a funcionalidade Analytics Consumption Zone (ACZ) no seu Azure Data Manager para recursos energéticos. A habilitação é um processo de configuração única que configura o seu Azure Data Manager para recurso de energia, identidade gerida atribuída pelo utilizador e conta de armazenamento. Após a habilitação, pode criar múltiplas instâncias ACZ para sincronizar diferentes conjuntos de dados do Azure Data Manager for Energy para a sua conta Azure Data Lake Storage Gen2.

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. Para ativar o ACZ no seu Azure Data Manager for Energy Resource, siga os passos deste artigo e contacte o seu representante da Microsoft.

Visão geral da configuração

A configuração configura uma identidade gerida que permite ao ACZ aceder ao Azure Data Manager para dados de energia e escrever no Data Lake Storage Gen2.

Conclua as seguintes tarefas de configuração pontuais para ativar o ACZ no seu Azure Data Manager for Energy resource. Após a habilitação, pode criar múltiplas instâncias ACZ usando as APIs.

Pré-requisitos

• Uma assinatura ativa do Azure. Crie uma subscrição gratuita.
• Uma instância do Azure Data Manager for Energy (escalão Developer) com, pelo menos, uma partição de dados. Crie um Azure Data Manager para uma instância de Energia.
• O CLI do Azure instalado na tua máquina, ou o acesso ao Azure Cloud Shell.

Passo 1: Crie ou use uma conta de armazenamento Data Lake Storage Gen2 existente

O ACZ requer uma conta de armazenamento Azure Data Lake Storage Gen2 com namespace hierárquico ativado para armazenar os dados sincronizados. Se ainda não tiveres um, cria-o.

1. No portal Azure, selecione Criar um recurso>Conta de Armazenamento.
2. No separador Básicos , selecione a sua subscrição e grupo de recursos.
3. Introduza o nome da conta de armazenamento e selecione a sua região preferida.
4. No separador Avançado , selecione Ativar espaço de nomes hierárquico.
5. Selecione Rever + criar e, em seguida, selecione Criar.

És responsável por selecionar uma conta de armazenamento dentro do destino geográfico se tiveres requisitos de residência de dados. A ACZ exporta dados para a conta de armazenamento Data Lake Storage Gen2 que especificar, independentemente da localização.

Passo 2: Criar uma identidade gerida atribuída pelo utilizador para a ACZ

O ACZ usa uma identidade gerida atribuída pelo utilizador para escrever dados no Data Lake Storage Gen2, por isso precisa de criar uma identidade dedicada para o ACZ.

Para criar uma identidade gerida atribuída pelo utilizador:

1. No portal Azure, procure por Managed Identities e selecione-o.
2. Selecione + Criar.
3. Selecione a sua subscrição, grupo de recursos e região, e forneça um nome para a identidade.
4. Selecione Rever + criar e, em seguida, selecione Criar.

Passo 3: Atribua a identidade gerida atribuída pelo utilizador ao seu recurso Azure Data Manager for Energy

Atribua a identidade gerida atribuída pelo utilizador que criou no Passo 2 ao recurso Azure Data Manager for Energy.

Siga estes três subpassos para anexar de forma segura a identidade gerida.

Passo 3.1: Obter a configuração atual

Obtenha a configuração completa da sua instância do Azure Data Manager for Energy.

# Set your Azure Data Manager for Energy instance details
SUBSCRIPTION_ID="{subscription-id}"
RESOURCE_GROUP="{resource-group}"
ADME_INSTANCE_NAME="{adme-instance-name}"

# Get Azure Resource Manager token
TOKEN=$(az account get-access-token --resource "https://management.azure.com/" --query accessToken -o tsv | tr -d '\r')

# Get current Azure Data Manager for Energy instance configuration
curl --http1.1 --request GET \
  --url "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.OpenEnergyPlatform/energyServices/$ADME_INSTANCE_NAME?api-version=2025-12-15" \
  --header "Authorization: Bearer $TOKEN" \
  > adme-config.json

# View the configuration
cat adme-config.json | jq .

# Set your Azure Data Manager for Energy instance details
$subscriptionId = "{subscription-id}"
$resourceGroup = "{resource-group}"
$admeInstanceName = "{adme-instance-name}"

# Get Azure Resource Manager token
$token = az account get-access-token --resource "https://management.azure.com/" --query accessToken -o tsv

# Get current Azure Data Manager for Energy instance configuration
$uri = "https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.OpenEnergyPlatform/energyServices/$admeInstanceName`?api-version=2025-12-15"

Invoke-RestMethod -Uri $uri -Method Get `
  -Headers @{ "Authorization" = "Bearer $token" } `
  | ConvertTo-Json -Depth 10 `
  | Out-File adme-config.json

# View the configuration (displays full JSON without truncation)
Get-Content adme-config.json

Substitua os marcadores

O comando mostra a configuração JSON completa sem truncamento. Revise cuidadosamente o conteúdo do adme-config.json ficheiro. Tens de copiar valores específicos a partir daí para o Passo 3.2.

Passo 3.2: Atualizar a configuração com identidade gerida

Atualize a configuração adicionando a sua identidade gerida enquanto preserva todas as propriedades existentes.

# Set your Azure Data Manager for Energy instance details
SUBSCRIPTION_ID="{subscription-id}"
RESOURCE_GROUP="{resource-group}"
ADME_INSTANCE_NAME="{adme-instance-name}"
MI_RESOURCE_ID="{managed-identity-resource-id}"

# Get Azure Resource Manager token
TOKEN=$(az account get-access-token --resource "https://management.azure.com/" --query accessToken -o tsv | tr -d '\r')

# Update Azure Data Manager for Energy instance with managed identity
# IMPORTANT: Replace {paste-entire-properties-block-from-GET} with the complete "properties" object from adme-config.json
# IMPORTANT: Replace {paste-all-existing-identities-from-GET} with all entries from identity.userAssignedIdentities, then add new MI
# IMPORTANT: Replace {paste-tags-from-GET} with the complete "tags" object from adme-config.json (or {} if no tags exist)
curl --http1.1 --request PUT \
  --url "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.OpenEnergyPlatform/energyServices/$ADME_INSTANCE_NAME?api-version=2025-12-15" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "location": "{use-location-from-GET}",
    "properties": {paste-entire-properties-block-from-GET},
    "identity": {
      "type": "UserAssigned",
      "userAssignedIdentities": {
        {paste-all-existing-identities-from-GET},
        "'"$MI_RESOURCE_ID"'": {}
      }
    },
    "tags": {paste-tags-from-GET}
  }'

# Set your Azure Data Manager for Energy instance details
$subscriptionId = "{subscription-id}"
$resourceGroup = "{resource-group}"
$admeInstanceName = "{adme-instance-name}"
$miResourceId = "{managed-identity-resource-id}"

# Get Azure Resource Manager token
$token = az account get-access-token --resource "https://management.azure.com/" --query accessToken -o tsv

# Update Azure Data Manager for Energy instance with managed identity
# IMPORTANT: Replace {paste-entire-properties-block-from-GET} with the complete "properties" object from adme-config.json
# IMPORTANT: Replace {paste-all-existing-identities-from-GET} with all entries from identity.userAssignedIdentities, then add new MI
# IMPORTANT: Replace {paste-tags-from-GET} with the complete "tags" object from adme-config.json (or {} if no tags exist)
$uri = "https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.OpenEnergyPlatform/energyServices/$admeInstanceName`?api-version=2025-12-15"

$body = @"
{
  "location": "{use-location-from-GET}",
  "properties": {paste-entire-properties-block-from-GET},
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      {paste-all-existing-identities-from-GET},
      "$miResourceId": {}
    }
  },
  "tags": {paste-tags-from-GET}
}
"@

Invoke-RestMethod -Uri $uri -Method Put `
  -Headers @{ "Authorization" = "Bearer $token"; "Content-Type" = "application/json" } `
  -Body $body

Substitua os marcadores

Passo 3.3: Verificar a ligação de identidade gerida

Confirme que a identidade gerida foi associada com sucesso à sua instância Azure Data Manager for Energy.

# Set your Azure Data Manager for Energy instance details (if not already set from previous steps)
SUBSCRIPTION_ID="{subscription-id}"
RESOURCE_GROUP="{resource-group}"
ADME_INSTANCE_NAME="{adme-instance-name}"

# Get Azure Resource Manager token
TOKEN=$(az account get-access-token --resource "https://management.azure.com/" --query accessToken -o tsv | tr -d '\r')

# Get current managed identities
curl --http1.1 --request GET \
  --url "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.OpenEnergyPlatform/energyServices/$ADME_INSTANCE_NAME?api-version=2025-12-15" \
  --header "Authorization: Bearer $TOKEN" \
  | jq '.identity.userAssignedIdentities | keys'

# Set your Azure Data Manager for Energy instance details (if not already set from previous steps)
$subscriptionId = "{subscription-id}"
$resourceGroup = "{resource-group}"
$admeInstanceName = "{adme-instance-name}"

# Get Azure Resource Manager token
$token = az account get-access-token --resource "https://management.azure.com/" --query accessToken -o tsv

# Set URI
$uri = "https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.OpenEnergyPlatform/energyServices/$admeInstanceName`?api-version=2025-12-15"

# Get current managed identities
$config = Invoke-RestMethod -Uri $uri -Method Get `
  -Headers @{ "Authorization" = "Bearer $token" }

$config.identity.userAssignedIdentities.PSObject.Properties.Name

Substitua os marcadores

Se executares todos os subpassos na mesma sessão de terminal, as variáveis já estão definidas a partir do Passo 3.1 e do Passo 3.2.

Saída da amostra

[
  "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/my-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-acz-identity"
]

A saída deve incluir o ID de recurso da sua identidade gerida. Se tiver outras identidades (CMEK, EDS) associadas, elas também aparecem na lista.

Passo 4: Verificar se o utilizador tem acesso ao grupo de direitos

Para chamar APIs ACZ, você (o utilizador) deve ser membro dos seguintes grupos de direitos:

• users@{data-partition-id}.dataservices.energy
• users.datalake.ops@{data-partition-id}.dataservices.energy

Esta etapa verifica se você (o utilizador que chama as APIs ACZ) tem acesso, e não a identidade gerida atribuída pelo utilizador. A identidade gerida atribuída pelo utilizador criada no Step 2 é usada apenas pela ACZ para escrever dados no armazenamento. Não precisa de filiação a um grupo de direitos.

Se ainda não é membro destes grupos de direitos, peça a um administrador do Azure Data Manager for Energy para adicionar a sua conta de utilizador. Para instruções detalhadas, consulte Gerir utilizadores no Azure Data Manager for Energy.

Para verificar que tem acesso, utilize a API do Serviço de Direitos para verificar a sua adesão a ambos os grupos.

# Check users group membership
curl --http1.1 --request GET \
  --url https://{base_url}/api/entitlements/v2/groups/users@{data-partition-id}.dataservices.energy/members \
  --header 'Authorization: Bearer {access_token}' \
  --header 'data-partition-id: {data-partition-id}'

# Check users.datalake.ops group membership
curl --http1.1 --request GET \
  --url https://{base_url}/api/entitlements/v2/groups/users.datalake.ops@{data-partition-id}.dataservices.energy/members \
  --header 'Authorization: Bearer {access_token}' \
  --header 'data-partition-id: {data-partition-id}'

# Check users group membership
Invoke-RestMethod -Uri "https://{base_url}/api/entitlements/v2/groups/users@{data-partition-id}.dataservices.energy/members" -Method Get -Headers @{
    "Authorization" = "Bearer {access_token}"
    "data-partition-id" = "{data-partition-id}"
}

# Check users.datalake.ops group membership
Invoke-RestMethod -Uri "https://{base_url}/api/entitlements/v2/groups/users.datalake.ops@{data-partition-id}.dataservices.energy/members" -Method Get -Headers @{
    "Authorization" = "Bearer {access_token}"
    "data-partition-id" = "{data-partition-id}"
}

Substitua os marcadores

Resposta de exemplo

{
  "desId": "users@dp1.dataservices.energy",
  "name": "users@dp1.dataservices.energy",
  "description": "Datalake users",
  "email": "users@dp1.dataservices.energy",
  "members": [
    {
      "email": "user@example.com",
      "role": "MEMBER"
    },
    {
      "email": "admin@example.com",
      "role": "OWNER"
    }
  ]
}

Ambas as respostas devem incluir a sua conta de utilizador na matriz members. Se não estiver listado em nenhum dos grupos, contacte o seu administrador de Dados do Azure para Energia para o adicionar a ambos os grupos obrigatórios.

Passo 5: Conceder permissões de identidade gerida atribuídas pelo utilizador no contentor Data Lake Storage Gen2

Conceda à identidade gerida atribuída ao utilizador acesso de escrita à conta de armazenamento do Data Lake Storage Gen2. A identidade ACZ necessita de permissões do Storage Blob Data Contributor para escrever ficheiros Delta Parquet.

1. Aceda à sua conta de armazenamento Data Lake Storage Gen2 no portal Azure.
2. Selecione Controlo de acesso (IAM) no menu da esquerda.
3. Selecione + Adicionar>Adicionar atribuição de função.
4. No separador Role , procure por Storage Blob Data Contributor, selecione-o e depois selecione Próximo.
5. Na guia Membros , para Atribuir acesso a, selecione Identidade gerenciada.
6. Escolha + Selecionar membros.
7. Na lista pendente identidade gerida, selecione identidade gerida atribuída pelo utilizador.
8. Selecione a identidade gerida atribuída pelo utilizador que criou no Passo 2 (ou a sua identidade CMEK/EDS existente) e depois escolha Selecionar.
9. Selecione Rever e atribuir para concluir a atribuição da função.

Passo 6: Partilhe a identidade gerida atribuída pelo utilizador e os detalhes das instâncias do Azure Data Manager for Energy com a Microsoft (requisito de pré-visualização)

Durante a versão preliminar, o acesso ao ACZ requer a utilização de listas de permissões. A Microsoft deve ativar a funcionalidade ACZ na sua instância Azure Data Manager for Energy e configurá-la com a sua identidade gerida atribuída pelo utilizador. Partilhe os seguintes detalhes com o seu contacto da Microsoft para concluir a ativação ACZ.

Forneça as seguintes informações ao seu representante da Microsoft.

Depois de a Microsoft adicionar a sua identidade gerida atribuída pelo utilizador à lista de permissões, o ACZ é ativado no seu recurso do Azure Data Manager for Energy.

Criar uma instância ACZ

Depois de concluir os passos de habilitação, pode criar uma ou mais instâncias ACZ para sincronizar o seu Azure Data Manager para dados de energia com o Data Lake Storage Gen2. Podes configurar cada instância ACZ para sincronizar diferentes tipos de dados.

Invoque a API de Criação do ACZ

Use a API ACZ Create para criar uma instância ACZ. Para um guia completo, veja o Tutorial: Use APIs ACZ.

curl --http1.1 --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": "my-first-acz",
    "allCatalogSync": false,
    "sink": {
      "storageId": "/subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{account}"
    },
    "configuration": {
      "catalogKinds": [
        "osdu:wks:master-data--Well:*",
        "osdu:wks:reference-data--UnitOfMeasure:*"
      ],
      "wellboreDDMSKinds": [
        "osdu:wks:work-product-component--WellLog:*"
      ]
    }
  }'

# Build request body
$body = @{
    name = "my-first-acz"
    allCatalogSync = $false
    sink = @{
        storageId = "/subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{account}"
    }
    configuration = @{
        catalogKinds = @(
            "osdu:wks:master-data--Well:*",
            "osdu:wks:reference-data--UnitOfMeasure:*"
        )
        wellboreDDMSKinds = @(
            "osdu:wks:work-product-component--WellLog:*"
        )
    }
} | ConvertTo-Json -Depth 10

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

Substitua os marcadores

Uma resposta bem-sucedida devolve o código de estado HTTP 201 com os detalhes do ACZ:

{
  "aczId": "acz-8a0aa7433085",
  "name": "my-first-acz",
  "status": "ACTIVE",
  "targetFormat": "DELTA_PARQUET",
  "aczType": "LATEST_VERSION",
  "sink": {
    "storageType": "microsoft.storage/storageaccounts",
    "storageId": "/subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{account}",
    "basePath": ""
  },
  "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-05-01T12:00:00.000000",
  "updatedTs": "2026-05-01T12:00:00.000000",
  "createdBy": "your-user-object-id"
}

Anote o aczId valor (formato: acz-<identifier>). Precisa deste identificador ACZ para:

• Gerir e consultar a instância ACZ usando APIs.
• Localize os seus dados no armazenamento Data Lake Storage Gen2 em <container>/<aczId>/ ou <container>/<basePath>/<aczId>/ se especificou um caminho base.

Conteúdo relacionado

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