Habilitar la zona de consumo de análisis

Las capacidades nativas de análisis en Azure Data Manager for Energy, proporcionadas a través de una zona de consumo analítico (ACZ), hacen que los datos energéticos sean fácilmente accesibles para análisis e IA. ADME sincroniza los datos OSDU® seleccionados en el almacenamiento propiedad del cliente en formato Delta Parquet abierto, lo que permite su uso con Microsoft Fabric, Azure Databricks, Snowflake y otras plataformas de análisis compatibles sin necesidad de crear ni mantener canalizaciones de datos personalizadas.

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.

Para habilitar ACZ en tu recurso de Azure Data Manager for Energy, sigue los pasos de este artículo.

Información general sobre la configuración

Configurar ACZ tiene dos partes:

  1. Activa ACZ en tu recurso Azure Data Manager for Energy en el portal de Azure. Haz este paso una vez para cada recurso.
  2. Crea una o más instancias de ACZ utilizando las APIs de ACZ. Una instancia de ACZ define qué datos exporta ACZ y la ubicación de almacenamiento en la que escribe los datos. Puedes crear hasta tres instancias ACZ en cada partición de datos.

ACZ no exporta ningún dato hasta que creas una instancia de ACZ.

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.

Sugerencia

Planee la configuración de ACZ: Antes de crear una instancia de ACZ, decida si necesita:

  • Todos los datos del catálogo: establezca allCatalogSync: true (fuera de la sección de configuración) para exportar todos los tipos de entidad de catálogo desde la partición.
  • Tipos de entidad específicos: use la catalogKinds matriz de la sección de configuración para exportar solo los tipos seleccionados (por ejemplo, Wells, Wellbores o Fields).

Cuando allCatalogSync es true, los arrays catalogKinds y wellboreDDMSKinds (previsualización) se ignoran para los datos de catálogo. Las descargas masivas de archivos del servicio Wellbore Domain Administración de datos Service (DDMS) solo están disponibles para las clases enumeradas en wellboreDDMSKinds.

Para obtener ejemplos de configuración, consulte Tutorial: Uso de las API de ACZ.

Paso tarea
1 Cree o use una cuenta de almacenamiento de Data Lake Storage Gen2 existente.
2 Cree una identidad administrada asignada por el usuario para ACZ.
3 Activa ACZ y asigna la identidad gestionada asignada por el usuario en el portal de Azure.
4 Compruebe que el usuario tenga acceso al grupo de autorizaciones.
5 Conceda permisos de almacenamiento de identidades administradas asignadas por el usuario.

Sugerencia

Para exportar datos de pertenencia a derechos de OSDU con el fin de aplicar filtros a nivel de fila en su plataforma de análisis, consulte Exportación de derechos en la Zona de consumo de análisis (versión preliminar).

Prerequisites

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.

Importante

ACZ exporta los datos a la cuenta de almacenamiento Data Lake Storage Gen2 que especifiques, independientemente de su ubicación. Si la cuenta de almacenamiento está en una región de Azure diferente a la de tu Azure Data Manager for Energy Resource, tus datos se copian fuera de la región del recurso. Para la ubicación recomendada, utiliza una cuenta de almacenamiento en la misma región que tu recurso de Azure Data Manager for Energy. ACZ no aplica una restricción de la misma región. Si tienes requisitos de residencia de datos, asegúrate de seleccionar una cuenta de almacenamiento en la región correspondiente.

Note

Actualmente, ACZ requiere que la cuenta de almacenamiento de destino permita el acceso público a la red. No se admiten cuentas de almacenamiento que restringen el acceso usando reglas IP de firewall, acceso público desactivado o endpoints privados. Este requisito solo se aplica a la cuenta de almacenamiento de destino. Las APIs de ACZ están disponibles en Azure Data Manager para instancias de Energy que utilizan endpoints privados.

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.

Importante

Microsoft recomienda crear una identidad gestionada asignada por el usuario dedicada para ACZ en lugar de reutilizar identidades de otros servicios como claves gestionadas por el cliente (CMKs) o fuentes de datos externas (EDS). Una identidad dedicada proporciona:

  • Registros de auditoría claros: una identidad independiente facilita el seguimiento de las operaciones específicas de ACZ en los registros de auditoría.
  • Administración del ciclo de vida independiente: el control independiente le permite rotar, actualizar o quitar la identidad de ACZ sin afectar a otros servicios.
  • Control de acceso granular: la identidad de ACZ obtiene solo los permisos que necesita (colaborador de datos de Storage Blob) sin heredar permisos innecesarios.
  • Solución de problemas simplificada: Los problemas con permisos ACZ no afectan a CMKs, EDS u otros servicios.

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: Activar ACZ y asignar la identidad gestionada asignada por el usuario

Habilite ACZ en su recurso de Azure Data Manager for Energy y seleccione la identidad administrada asignada al usuario que creó en el paso 2.

Note

La Zona de Consumo de Analítica es una función opcional y facturable. Los cargos comienzan cuando lo activas. Consulta precios.

  1. Vaya al recurso de Azure Data Manager for Energy en Azure Portal.

  2. En el menú izquierdo, en Avanzado, selecciona Analytics Consumption Zone.

  3. Seleccione la casilla para activar la Zona de Consumo de Analítica.

  4. Junto a Identidad asignada por el usuario, selecciona Seleccionar una identidad de usuario para abrir el formulario.

  5. Selecciona la suscripción y la identidad gestionada asignada por el usuario que creaste en el Paso 2, y luego selecciona Añadir. Solo puede seleccionar una identidad. Si estás reutilizando una identidad existente, selecciona esa identidad en su lugar.

    Captura de pantalla de la página de Analytics Consumption Zone con Activar Analytics Consumption Zone seleccionada y el panel de Seleccionar identidad gestionada asignada por el usuario abierto, mostrando una identidad seleccionada y el botón Añadir.

  6. Seleccione Guardar para aplicar la configuración.

    Captura de pantalla de la página de la Zona de Consumo de Analítica con una identidad asignada por el usuario seleccionada y el botón de guardar resaltado.

Tras guardar la configuración, Habilitar Analytics Consumption Zone aparece seleccionada y no disponible, y Identidad asignada por el usuario muestra la identidad seleccionada.

Importante

Después de activar ACZ, no puedes desactivarlo en el portal de Azure. Para desactivar ACZ en un recurso de Azure Data Manager for Energy, crea una solicitud de soporte.

Importante

Activar ACZ no inicia la exportación de datos. Para empezar a exportar, completa los pasos restantes y luego crea una instancia ACZ.

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
  • service.entitlements.user@{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, utilice la API del servicio de derechos para verificar su pertenencia a los tres 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}'

Reemplazar los marcadores de posición

Marcador de posición Description
{base_url} La dirección URL del recurso de Azure Data Manager for Energy (por ejemplo, myinstance.energy.azure.com).
{access_token} Tu token de acceso personal de las APIs de Azure Data Manager for Energy. Consulte Generación de un token de autenticación.
{data-partition-id} Su ID de partición de datos (por ejemplo, dp1).

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

Las tres respuestas deberían incluir tu cuenta de usuario en el members array. Si no estás listado en ninguno de los grupos, contacta con tu administrador de Azure Data Manager for Energy para que te añada a los tres grupos obligatorios.

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 al usuario que creó en el paso 2 y, a continuación, elija Seleccionar. Si estás reutilizando una identidad existente, como la identidad que usas para claves gestionadas por el cliente (CMK) o Servicios de Datos Externos (EDS), selecciona esa identidad en su lugar.
  9. Seleccione Revisar y asignar para finalizar la asignación de roles.

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.

Note

No es posible editar una definición de ACZ existente, por ejemplo, para añadir o eliminar tipos. Para cambiar una definición, crea una nueva ACZ con la configuración que necesitas. Cada ACZ tiene su propio identificador y ruta de salida, por lo que debe actualizar las tablas, los accesos directos o las ubicaciones externas posteriores para que apunten al nuevo ACZ.

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

Reemplazar los marcadores de posición

Marcador de posición Description
{base_url} La dirección URL del recurso de Azure Data Manager for Energy (por ejemplo, myinstance.energy.azure.com).
{access_token} El token de acceso de Azure Data Manager para las API de energía. Consulte Generación de un token de autenticación.
{data_partition_id} Su ID de partición de datos (por ejemplo, dp1).
{sub-id} Identificador de suscripción donde reside la cuenta de almacenamiento de Data Lake Storage Gen2.
{rg} Grupo de recursos donde reside la cuenta de almacenamiento de Data Lake Storage Gen2.
{account} Nombre de la cuenta de almacenamiento de Data Lake Storage Gen2.

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 valor aczId. Lo necesitas para gestionar y consultar la instancia de ACZ usando APIs, y para encontrar tus datos almacenados como se describe en la siguiente tabla.

La propiedad opcional basePath determina dónde ACZ escribe datos en tu cuenta de almacenamiento:

basePath Ubicación de datos
No especificado <aczId>/<aczId>/
analytics analytics/<aczId>/
analytics/workbench analytics/workbench/<aczId>/

El primer segmento de la ubicación de datos es el contenedor. ACZ usa el primer segmento de basePath como nombre del contenedor, o el aczId si no especificas una ruta base, y crea el contenedor si no existe. El primer segmento debe ser un nombre válido de contenedor. Para las reglas de nombre, véase Nombrar y referenciar contenedores, blobs y metadatos. Cualquier segmento adicional basePath se crea como carpeta en ese contenedor. El primer segmento debe seguir las reglas de nombres de contenedores: de 3 a 63 caracteres, usando letras minúsculas, números y guiones.

Sugerencia

Si creas una ACZ desde la interfaz de Swagger o una solicitud de ejemplo, sustituye el valor del marcador de posición basePath. Por ejemplo, el valor string por defecto de Swagger crea un contenedor llamado string.

Después de crear una instancia ACZ, ACZ toma una instantánea histórica de los datos que seleccionaste. Para comprobar el progreso, llama a la API Get ACZ y revisa los campos status y historicalSnapshotStatus. Cuando historicalSnapshotStatus es COMPLETED, la exportación inicial está finalizada y ACZ continúa sincronizando los nuevos cambios. Para más detalles, consulta el Tutorial: Usar APIs de ACZ.