Habilitar la zona de consumo de análisis

En este artículo se explica cómo habilitar la funcionalidad de zona de consumo de análisis (ACZ) en el recurso de Azure Data Manager para energía. La habilitación es un proceso de configuración único que configura el Azure Data Manager para el recurso de energía, la identidad administrada asignada por el usuario y la cuenta de almacenamiento. Después de la habilitación, puede crear varias instancias de ACZ para sincronizar diferentes Azure Data Manager para conjuntos de datos de Energía con la cuenta de Azure Data Lake Storage Gen2.

Durante la versión preliminar, ACZ solo está disponible en instancias de nivel de desarrollador y requiere el uso de listas de permitidos. Para habilitar ACZ en el recurso de Azure Data Manager for Energy, siga los pasos descritos en este artículo y póngase en contacto con su representante de Microsoft.

Información general sobre la configuración

La configuración configura una identidad administrada que permite a ACZ acceder a Azure Data Manager para datos de energía y escribir en Data Lake Storage Gen2.

Finalice las siguientes tareas de configuración única para habilitar ACZ en el recurso de Azure Data Manager for Energy. Después de la habilitación, puede crear varias instancias de ACZ mediante las API.

Prerequisites

• Una suscripción de Azure activa. Cree una suscripción gratuita.
• Una instancia de Azure Data Manager for Energy (nivel Developer) con al menos una partición de datos. Cree una instancia de Azure Data Manager for Energy.
• El CLI de Azure instalado en el equipo o el acceso a Azure Cloud Shell.

Paso 1: Crear o usar una cuenta de almacenamiento de Data Lake Storage Gen2 existente

ACZ requiere una cuenta de almacenamiento de Azure Data Lake Storage Gen2 con espacio de nombres jerárquico habilitado para almacenar los datos sincronizados. Si aún no tiene una, créela.

1. En el portal Azure, seleccione Crear un recurso>Cuenta de almacenamiento.
2. En la pestaña Aspectos básicos , seleccione la suscripción y el grupo de recursos.
3. Escriba un nombre de cuenta de almacenamiento y seleccione su región preferida.
4. En la pestaña Opciones avanzadas , seleccione Habilitar espacio de nombres jerárquico.
5. Seleccione Revisar y crear y, a continuación, seleccione Crear.

Usted es responsable de seleccionar una cuenta de almacenamiento de destino en la zona geográfica si tiene requisitos de residencia de los datos. ACZ exporta datos a la cuenta de almacenamiento de Data Lake Storage Gen2 que especifique, independientemente de la ubicación.

Paso 2: Creación de una identidad administrada asignada por el usuario para ACZ

ACZ usa una identidad administrada asignada por el usuario para escribir datos en Data Lake Storage Gen2, por lo que debe crear una identidad dedicada para ACZ.

Para crear una identidad administrada asignada por el usuario:

1. En el portal Azure, busque Managed Identities y selecciónelo.
2. Seleccione + Create.
3. Seleccione la suscripción, el grupo de recursos y la región y proporcione un nombre para la identidad.
4. Seleccione Revisar y crear y, a continuación, seleccione Crear.

Paso 3: Asignación de la identidad administrada asignada por el usuario al recurso de Azure Data Manager for Energy

Asigne la identidad administrada asignada por el usuario que creó en el paso 2 al recurso de Azure Data Manager for Energy.

Siga estos tres subpasos para adjuntar la identidad administrada de forma segura.

Paso 3.1: Obtener la configuración actual

Recupere la configuración completa de Azure Data Manager para la instancia de 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

Reemplazar los marcadores de posición

El comando muestra la configuración JSON completa sin truncamiento. Revise cuidadosamente el contenido del adme-config.json archivo. Debe copiar valores específicos de él para el paso 3.2.

Paso 3.2: Actualización de la configuración con identidad administrada

Actualice la configuración agregando la identidad administrada a la vez que conserva todas las propiedades 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

Reemplazar los marcadores de posición

Paso 3.3: Comprobación de los datos adjuntos de identidad administrada

Confirme que la identidad administrada se adjuntó correctamente a la instancia de 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

Reemplazar los marcadores de posición

Si ejecuta todos los subpasos en la misma sesión de terminal, las variables ya se establecen en el paso 3.1 y en el paso 3.2.

Salida de ejemplo

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

La salida debe incluir el identificador de recurso de la identidad administrada. Si tiene otras identidades (CMEK, EDS) adjuntas, también aparecen en la lista.

Paso 4: Comprobar que el usuario tiene acceso al grupo de derechos

Para llamar a las API de ACZ, usted (el usuario) debe ser miembro de los siguientes grupos de derechos:

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

Este paso comprueba que usted (el usuario que llama a las API de ACZ) tiene acceso, no la identidad administrada asignada por el usuario. La identidad administrada asignada por el usuario creada en el paso 2 solo la usa ACZ para escribir datos en el almacenamiento. No necesita pertenencia a grupos de derechos.

Si aún no pertenece a estos grupos de permisos, pida a un administrador de Azure Data Manager for Energy que agregue su cuenta de usuario. Para obtener instrucciones detalladas, consulte Administración de usuarios en Azure Data Manager for Energy.

Para comprobar que tiene acceso, use la API del servicio Derechos para comprobar la pertenencia a ambos 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}"
}

Reemplazar los marcadores de posición

Respuesta de ejemplo

{
  "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 respuestas deben incluir su cuenta de usuario en el array members. Si no aparece en ninguno de los grupos, póngase en contacto con el administrador de Azure Data Manager for Energy para agregarlo a ambos grupos necesarios.

Paso 5: Concesión de permisos de identidad administrada asignada por el usuario en el contenedor de Data Lake Storage Gen2

Conceda a la identidad administrada asignada por el usuario acceso de escritura a la cuenta de almacenamiento de Data Lake Storage Gen2. La identidad de ACZ necesita permisos de colaborador de datos de blobs de almacenamiento para escribir archivos Delta Parquet.

1. Vaya a la cuenta de almacenamiento de Data Lake Storage Gen2 en el portal de Azure.
2. Seleccione Control de acceso (IAM) en el menú izquierdo.
3. Seleccione + Añadir>Añadir asignación de rol.
4. En la pestaña Rol , busque Colaborador de datos de Storage Blob, selecciónelo y, a continuación, seleccione Siguiente.
5. En la pestaña Miembros, para Asignar acceso a, seleccione Identidad administrada.
6. Elija + Seleccionar miembros.
7. En la lista desplegable Identidad administrada , seleccione Identidad administrada asignada por el usuario.
8. Seleccione la identidad administrada asignada por el usuario que creó en el paso 2 (o la identidad de CMEK/EDS existente) y, a continuación, elija Seleccionar.
9. Seleccione Revisar y asignar para finalizar la asignación de roles.

Paso 6: Comparta con Microsoft la identidad administrada asignada por el usuario y los detalles de la instancia de Azure Data Manager for Energy (requisito de la versión preliminar)

Durante la versión preliminar, el acceso a ACZ requiere el uso de listas de permitidos. Microsoft debe habilitar la funcionalidad ACZ en la instancia de Azure Data Manager for Energy y configurarla con la identidad administrada asignada por el usuario. Comparta los detalles siguientes con su contacto de Microsoft para finalizar la habilitación de ACZ.

Proporcione la siguiente información a su representante de Microsoft.

Después de que Microsoft agregue su identidad administrada asignada por el usuario a la lista de autorizados, ACZ queda habilitado en su recurso de Azure Data Manager for Energy.

Creación de una instancia de ACZ

Después de finalizar los pasos de habilitación, puede crear una o varias instancias de ACZ para sincronizar los datos de Azure Data Manager for Energy con Data Lake Storage Gen2. Puede configurar cada instancia de ACZ para sincronizar diferentes tipos de datos.

Llama a la API Create de ACZ

Use la API de creación de ACZ para crear una instancia de ACZ. Para ver un tutorial completo, consulte Tutorial: Uso de las API de 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

Reemplazar los marcadores de posición

Una respuesta correcta devuelve el estado 201 HTTP con los detalles de 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 el aczId valor (formato: acz-<identifier>). Necesita este identificador de ACZ para:

• Administre y consulte la instancia de ACZ mediante las API.
• Localice sus datos en el almacenamiento Data Lake Storage Gen2 en <container>/<aczId>/ o <container>/<basePath>/<aczId>/ si especificó una ruta de acceso base.

Contenido relacionado

• Tutorial: Uso de las API de ACZ
• Conexión de datos de ACZ a Microsoft Fabric
• Conexión de datos de ACZ a Azure Databricks
• Conceptos de la zona de consumo de Analytics