Habilitar zona de consumo de análise

Este artigo explica como habilitar a funcionalidade ACZ (Zona de Consumo de Análise) no recurso Azure Data Manager for Energy. A habilitação é um processo de instalação único que configura seu recurso Azure Data Manager para Energia, identidade gerenciada atribuída pelo usuário e conta de armazenamento. Após a habilitação, você pode criar várias instâncias do ACZ para sincronizar diferentes conjuntos de dados do Azure Data Manager for Energy com sua conta do Azure Data Lake Storage Gen2.

Durante a prévia, a ACZ está disponível apenas em instâncias da camada Developer e requer o uso de listas de permissões. Para habilitar a ACZ no recurso Azure Data Manager for Energy, siga as etapas deste artigo e entre em contato com seu representante do Microsoft.

Visão geral da configuração

A configuração estabelece uma identidade gerenciada que permite à ACZ acessar os dados do Azure Data Manager for Energy e gravá-los no Data Lake Storage Gen2.

Conclua as seguintes tarefas de instalação única para habilitar a ACZ no recurso Azure Data Manager for Energy. Após a habilitação, você pode criar várias instâncias ACZ usando as APIs.

Pré-requisitos

• Uma assinatura de Azure ativa. Crie uma assinatura gratuitamente.
• Uma instância do Azure Data Manager para Energia (camada de desenvolvedor) com pelo menos uma partição de dados. Crie uma instância do Azure Data Manager para Energia.
• O CLI do Azure instalado em seu computador ou acesso ao Azure Cloud Shell.

Etapa 1: criar ou usar 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 habilitado para armazenar os dados sincronizados. Se você ainda não tiver um, crie-o.

1. No portal Azure, selecione Criar um recurso>Storage account.
2. Na guia Noções básicas , selecione sua assinatura e grupo de recursos.
3. Insira um nome de conta de armazenamento e selecione sua região preferida.
4. No separador Avançadas , selecione Ativar espaço de nomes hierárquico.
5. Selecione Examinar + criar e, em seguida, selecione Criar.

Você será responsável por selecionar uma conta de armazenamento de destino na área geográfica se tiver requisitos de residência de dados. A ACZ exporta dados para a conta de armazenamento Data Lake Storage Gen2 especificada, independentemente do local.

Etapa 2: Criar uma identidade gerenciada atribuída pelo usuário para a ACZ

A ACZ usa uma identidade gerenciada atribuída pelo usuário para gravar dados em Data Lake Storage Gen2, portanto, você precisa criar uma identidade dedicada para a ACZ.

Para criar uma identidade gerenciada atribuída pelo usuário:

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

Etapa 3: Atribuir a identidade gerenciada atribuída pelo usuário ao recurso Azure Data Manager for Energy

Atribua a identidade gerenciada atribuída pelo usuário que você criou na Etapa 2 ao recurso Azure Data Manager for Energy.

Siga estas três subetapas para anexar com segurança a identidade gerenciada.

Etapa 3.1: Obter a configuração atual

Recupere sua configuração de instância completa 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 espaços reservados

O comando exibe a configuração JSON completa sem truncamento. Examine o conteúdo do adme-config.json arquivo com cuidado. Você precisa copiar valores específicos dele para a Etapa 3.2.

Etapa 3.2: atualizar a configuração com a identidade gerenciada

Atualize a configuração adicionando sua identidade gerenciada preservando 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 espaços reservados

Etapa 3.3: Verificar o anexo de identidade gerenciada

Confirme se a identidade gerenciada foi anexada com êxito à instância do 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 espaços reservados

Se você executar todos os substeps na mesma sessão de terminal, as variáveis já serão definidas na Etapa 3.1 e na Etapa 3.2.

Saída de exemplo

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

A saída deve incluir a ID de recurso da identidade gerenciada. Se você tiver outras identidades (CMEK, EDS) anexadas, elas também aparecerão na lista.

Etapa 4: Verificar se o usuário tem acesso ao grupo de direitos

Para chamar APIs ACZ, você (o usuário) 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 usuário que chama APIs ACZ) tem acesso, não a identidade gerenciada atribuída pelo usuário. A identidade gerenciada atribuída pelo usuário criada na Etapa 2 é usada apenas pela ACZ para gravar dados no armazenamento. Ela não precisa de associação ao grupo de direitos.

Se você ainda não for membro desses grupos de direitos, faça com que um administrador do Azure Data Manager for Energy adicione sua conta de usuário. Para obter instruções detalhadas, consulte Gerenciar usuários no Azure Data Manager for Energy.

Para verificar se você tem acesso, use a API do Serviço de Direitos para verificar sua associação em 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 espaços reservados

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 sua conta de usuário na members matriz. Se você não estiver listado em nenhum dos grupos, entre em contato com o administrador do Azure Data Manager for Energy para adicioná-lo a ambos os grupos necessários.

Etapa 5: Conceder permissões de identidade gerenciada atribuídas pelo usuário no contêiner de Data Lake Storage Gen2

Conceda à identidade gerenciada atribuída pelo usuário acesso de gravação à conta de armazenamento do Data Lake Storage Gen2. A identidade ACZ precisa das permissões do Colaborador de dados de blob de armazenamento para gravar arquivos Parquet Delta.

1. Acesse sua conta de armazenamento Data Lake Storage Gen2 no portal do Azure.
2. Selecione Controle de acesso (IAM) no menu à esquerda.
3. Selecione +Adicionar>Adicionar atribuição de função.
4. Na guia Função, pesquise por Storage Blob Data Contributor, selecione-o e selecione Avançar.
5. Na guia Membros , para atribuir acesso, selecione Identidade gerenciada.
6. Escolha + Selecionar membros.
7. Na lista suspensa Identidade gerenciada, selecione Identidade gerenciada atribuída pelo usuário.
8. Selecione a identidade gerenciada atribuída pelo usuário que você criou na Etapa 2 (ou na identidade existente do CMEK/EDS) e escolha Selecionar.
9. Selecione Examinar + atribuir para concluir a atribuição de função.

Etapa 6: Compartilhar com a Microsoft a identidade gerenciada atribuída ao usuário e os detalhes da instância do Azure Data Manager for Energy (requisito da versão prévia)

Durante a versão prévia, é necessário usar listas de permissões para acessar o ACZ. Microsoft deve habilitar a funcionalidade ACZ em sua instância do Azure Data Manager for Energy e configurá-la com sua identidade gerenciada atribuída pelo usuário. Compartilhe os detalhes a seguir com seu contato Microsoft para concluir a habilitação do ACZ.

Forneça as informações a seguir ao representante do Microsoft.

Depois que Microsoft adiciona sua identidade gerenciada atribuída pelo usuário à lista de permissões, a ACZ é habilitada no recurso Azure Data Manager for Energy.

Criar uma instância do ACZ

Depois de concluir as etapas de habilitação, você pode criar uma ou mais instâncias ACZ para sincronizar seus dados do Azure Data Manager for Energy para Data Lake Storage Gen2. Você pode configurar cada instância do ACZ para sincronizar diferentes tipos de dados.

Chamar a API de criação de ACZ

Use a API de Criação de ACZ para criar uma instância de ACZ. Para obter um passo a passo completo, consulte Tutorial: Usar 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 espaços reservados

Uma resposta bem-sucedida retorna o status HTTP 201 com os detalhes da 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>). Você precisa desse identificador ACZ para:

• Gerencie e consulte a instância do ACZ usando APIs.
• Localize os dados no armazenamento Data Lake Storage Gen2 em <container>/<aczId>/ ou <container>/<basePath>/<aczId>/, se tiver especificado um caminho base.

Conteúdo relacionado

• Tutorial: Como usar APIs ACZ
• Conectar dados ACZ para Microsoft Fabric
• Conectar dados ACZ para Azure Databricks
• Conceitos da zona de consumo de análise