Ativar a Zona de Consumo de Analítica

As capacidades nativas de análise no Azure Data Manager for Energy, entregues através de uma zona de consumo analítico (ACZ), tornam os dados energéticos facilmente acessíveis para análises e IA. O ADME sincroniza dados OSDU® selecionados para armazenamento propriedade do cliente em formato aberto Delta Parquet, permitindo a utilização com Microsoft Fabric, Azure Databricks, Snowflake e outras plataformas de análise compatíveis sem necessidade de construir e manter pipelines de dados personalizados.

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.

Para ativar o ACZ no seu Azure Data Manager for Energy resource, siga os passos deste artigo.

Visão geral da configuração

Configurar a ACZ tem duas partes:

  1. Ative o ACZ no seu recurso Azure Data Manager for Energy no portal Azure. Faz este passo uma vez para cada recurso.
  2. Crie uma ou mais instâncias ACZ usando as APIs ACZ. Uma instância ACZ define quais os dados que o ACZ exporta e a localização de armazenamento onde escreve. Pode criar até três instâncias ACZ em cada partição de dados.

O ACZ não exporta quaisquer dados enquanto não criares uma instância do ACZ.

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.

Dica

Planeie a sua configuração ACZ: Antes de criar uma instância ACZ, decida se precisa de:

  • Todos os dados do catálogo: Define allCatalogSync: true (fora da secção de configuração) para exportar todos os tipos de entidades do catálogo da tua partição.
  • Tipos específicos de entidades: Use a catalogKinds matriz na secção de configuração para exportar apenas os tipos selecionados (por exemplo, Poços, Furos de poço ou Campos).

Quando allCatalogSync é true, os arrays catalogKinds e wellboreDDMSKinds (pré-visualização) são ignorados para dados de catálogo. Os downloads em massa do Wellbore Domain Gestão de Dados Service (DDMS) ocorrem apenas para os tipos listados em wellboreDDMSKinds.

Para exemplos de configuração, veja Tutorial: Usar APIs ACZ.

Step Tarefa
1 Crie ou use uma conta de armazenamento Data Lake Storage Gen2 existente.
2 Crie uma identidade gerida atribuída pelo utilizador para o ACZ.
3 Ative o ACZ e atribua a identidade gerida atribuída pelo utilizador no portal do Azure.
4 Verifique se o utilizador tem acesso ao grupo de direitos.
5 Conceder permissões de armazenamento de identidade gerida atribuídas ao utilizador.

Dica

Para exportar dados de associação às permissões OSDU para filtragem ao nível das linhas na sua plataforma de analítica, consulte Exportação de associações às permissões na Zona de Consumo de Analítica (pré-visualização).

Pré-requisitos

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.

Importante

O ACZ exporta dados para a conta de armazenamento Data Lake Storage Gen2 que especificar, independentemente da sua localização. Se a conta de armazenamento estiver numa região Azure diferente da do seu recurso Azure Data Manager for Energy, os seus dados são copiados para fora da região do recurso. Para a colocação recomendada, use uma conta de armazenamento na mesma região do seu recurso Azure Data Manager for Energy. A ACZ não aplica uma restrição à mesma região. Se tiver requisitos de residência de dados, certifique-se de selecionar uma conta de armazenamento na região apropriada.

Note

Atualmente, o ACZ exige que a conta de armazenamento de destino permita o acesso à rede pública. Contas de armazenamento que restringem o acesso usando regras de IP de firewall, acesso à rede pública desativada ou endpoints privados não são suportadas. Este requisito aplica-se apenas à conta de armazenamento de destino. As APIs ACZ estão disponíveis no Azure Data Manager para instâncias de Energy que utilizam endpoints privados.

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.

Importante

A Microsoft recomenda que crie uma identidade gerida dedicada atribuída pelo utilizador para o ACZ, em vez de reutilizar identidades de outros serviços como chaves geridas pelo cliente (CMKs) ou fontes de dados externas (EDS). Uma identidade dedicada proporciona:

  • Registos de auditoria claros: Identidade separada facilita o acompanhamento de operações específicas da ACZ nos registos de auditoria.
  • Gestão independente do ciclo de vida: O controlo independente permite-lhe alternar, atualizar ou remover a identidade ACZ sem afetar outros serviços.
  • Controlo de acesso granular: A identidade ACZ obtém apenas as permissões necessárias (Contribuidor de Dados do Blob de Armazenamento) sem herdar permissões desnecessárias.
  • Resolução de problemas simplificada: Problemas com permissões ACZ não afetam CMKs, EDS ou outros serviços.

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: Ativar o ACZ e atribuir a identidade gerida atribuída pelo usuário

Ative o ACZ no seu recurso Azure Data Manager for Energy e selecione a identidade gerida atribuída pelo utilizador que criou no Passo 2.

Note

A Zona de Consumo de Analytics é uma funcionalidade opcional e faturável. As cobranças começam quando a ativares. Ver preços.

  1. Aceda à sua recurso Azure Data Manager for Energy no portal do Azure.

  2. No menu esquerdo, em Avançado, selecione Analytics Consumption Zone.

  3. Selecione a caixa de seleção para Ativar a Zona de Consumo de Análise.

  4. Ao lado de Identidade atribuída pelo utilizador, selecione Selecionar uma identidade de utilizador para abrir o formulário.

  5. Selecione a subscrição e a identidade gerida atribuída pelo utilizador que criou no Passo 2, e depois selecione Adicionar. Só pode selecionar apenas uma identidade. Se estiveres a reutilizar uma identidade existente, escolhe essa identidade em vez disso.

    Captura de ecrã da página da Zona de Consumo de Análise com Ativar Zona de Consumo de Analítica selecionada e o painel de Selecionar identidade gerida atribuída ao utilizador aberto, mostrando uma identidade selecionada e o botão Adicionar.

  6. Selecione Guardar para aplicar a configuração.

    Captura de ecrã da página da Zona de Consumo do Analytics com uma identidade atribuída pelo utilizador selecionada e o botão de Guardar destacado.

Depois de a configuração ser guardada, Ativar Zona de Consumo de Análise aparece selecionada e indisponível, e Identidade atribuída pelo utilizador mostra a identidade selecionada.

Importante

Depois de ativares o ACZ, não podes desativá-lo no portal do Azure. Para desativar o ACZ num recurso do Azure Data Manager for Energy, crie um pedido de suporte.

Importante

Ativar o ACZ não inicia a exportação de dados. Para começar a exportar, complete os passos restantes e depois crie uma instância ACZ.

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
  • service.entitlements.user@{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 Entitlements Service API para verificar a sua pertença nos três 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 service.entitlements.user group membership
curl --http1.1 --request GET \
  --url https://{base_url}/api/entitlements/v2/groups/service.entitlements.user@{data-partition-id}.dataservices.energy/members \
  --header 'Authorization: Bearer {access_token}' \
  --header 'data-partition-id: {data-partition-id}'

Substitua os marcadores

Marcador de Posição Description
{base_url} O URL do recurso do Azure Data Manager for Energy (por exemplo, myinstance.energy.azure.com).
{access_token} O seu token de acesso pessoal para o Azure Data Manager for Energy APIs. Veja Gerar um token de autenticação.
{data-partition-id} O ID da sua partição de dados (por exemplo, dp1).

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

Todas as três respostas devem incluir a sua conta de utilizador no members array. Se não estiver listado em nenhum dos grupos, contacte o administrador do Azure Data Manager for Energy para o adicionar aos três 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 e depois escolha Selecionar. Se estiver a reutilizar uma identidade existente, como a identidade que usa para chaves geridas pelo cliente (CMK) ou Serviços de Dados Externos (EDS), selecione essa identidade em vez disso.
  9. Selecione Rever e atribuir para concluir a atribuição da função.

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.

Note

Não podes editar uma definição ACZ existente, por exemplo, para adicionar ou remover categorias. Para alterar uma definição, crie um novo ACZ com a configuração de que necessita. Cada ACZ tem o seu próprio identificador e caminho de saída, por isso atualize quaisquer tabelas subsequentes, atalhos ou localizações externas para apontar para a nova ACZ.

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:*"
      ]
    }
  }'

Substitua os marcadores

Marcador de Posição Description
{base_url} O URL do recurso do Azure Data Manager for Energy (por exemplo, myinstance.energy.azure.com).
{access_token} O token de acesso para Azure Data Manager para APIs de energia. Veja Gerar um token de autenticação.
{data_partition_id} O ID da sua partição de dados (por exemplo, dp1).
{sub-id} O ID da subscrição onde reside a conta de armazenamento Data Lake Storage Gen2.
{rg} O grupo de recursos onde reside a conta de armazenamento Data Lake Storage Gen2.
{account} O nome da conta de armazenamento Data Lake Storage Gen2.

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 valor aczId. Precisa dele para gerir e consultar a instância ACZ usando APIs, e para encontrar os seus dados armazenados, conforme descrito na tabela seguinte.

A propriedade opcional basePath determina onde o ACZ escreve os dados na sua conta de armazenamento:

basePath Localização dos dados
Não especificado <aczId>/<aczId>/
analytics analytics/<aczId>/
analytics/workbench analytics/workbench/<aczId>/

O primeiro segmento da localização dos dados é o contentor. O ACZ usa o primeiro segmento de basePath como nome do contentor, ou aczId se não especificares um caminho base, e cria o contentor se este não existir. O primeiro segmento deve ser um nome válido de contentor. Para regras de nomenclatura, veja a secção Nomeação e referência de contentores, blobs e metadados. Quaisquer segmentos adicionais basePath são criados como pastas nesse contentor. O primeiro segmento deve seguir as regras de nomeação dos contentores: 3 a 63 caracteres, usando letras minúsculas, números e hífens.

Dica

Se criares um ACZ a partir da interface do Swagger ou de um pedido de exemplo, substitui o valor de marcador de posição basePath. Por exemplo, o valor predefinido do Swagger string cria um contentor chamado string.

Depois de criar uma instância ACZ, o ACZ cria um instantâneo histórico dos dados que selecionou. Para verificar o progresso, chame a API Get ACZ e verifique os campos status e historicalSnapshotStatus. Quando historicalSnapshotStatus é COMPLETED, a exportação inicial está concluída e o ACZ continua a sincronizar as novas alterações. Para obter mais detalhes, veja Tutorial: Usar APIs ACZ.