Abilita la zona di consumo Analytics

Questo articolo illustra come abilitare la funzionalità ACZ (Analytics Consumption Zone) nella risorsa di Azure Data Manager per l'energia. L'abilitazione è un processo di configurazione monouso che configura il Azure Data Manager per la risorsa Energia, l'identità gestita assegnata dall'utente e l'account di archiviazione. Dopo l'attivazione, è possibile creare più istanze ACZ per sincronizzare diversi set di dati di Azure Data Manager for Energy nel proprio account Azure Data Lake Storage Gen2.

Durante l'anteprima, ACZ è disponibile solo nelle istanze del livello sviluppatore e richiede l'uso di elenchi di elementi consentiti. Per abilitare ACZ nella risorsa di Azure Data Manager per l'energia, seguire i passaggi descritti in questo articolo e contattare il rappresentante Microsoft.

Panoramica dell'installazione

La configurazione configura un'identità gestita che consente a ACZ di accedere Azure Data Manager per i dati energetici e scrivere in Data Lake Storage Gen2.

Completare le attività di configurazione monouso seguenti per abilitare ACZ nel Azure Data Manager per la risorsa Energia. Dopo l'abilitazione, è possibile creare più istanze di ACZ usando le API.

Prerequisiti

• Una sottoscrizione di Azure attiva. Creare gratuitamente una sottoscrizione.
• Un Azure Data Manager per l'istanza di Energia (livello sviluppatore) con almeno una partizione di dati. Creare un'istanza di Azure Data Manager per l'energia.
• Il interfaccia della riga di comando di Azure installato nel computer o l'accesso a Azure Cloud Shell.

Passaggio 1: Creare o usare un account di archiviazione Data Lake Storage Gen2 esistente

ACZ richiede un account di archiviazione Azure Data Lake Storage Gen2 con spazio dei nomi gerarchico abilitato per archiviare i dati sincronizzati. Se non ne hai già uno, crealo.

1. Nel portale Azure selezionare Crea una risorsa>Account di archiviazione.
2. Nella scheda Informazioni di base selezionare la sottoscrizione e il gruppo di risorse.
3. Immettere un nome dell'account di archiviazione e selezionare l'area preferita.
4. Nella scheda Avanzate selezionare Abilita spazio dei nomi gerarchico.
5. Seleziona Rivedi e crea e quindi seleziona Crea.

Se hai requisiti di residenza dei dati, sei responsabile della selezione di un account di archiviazione di destinazione nell'area geografica appropriata. ACZ esporta i dati nell'account di archiviazione Data Lake Storage Gen2 specificato, indipendentemente dalla posizione.

Passaggio 2: Creare un'identità gestita assegnata dall'utente per ACZ

ACZ usa un'identità gestita assegnata dall'utente per scrivere dati in Data Lake Storage Gen2, quindi è necessario creare un'identità dedicata per ACZ.

Per creare un'identità gestita assegnata dall'utente:

1. Nel portale Azure cercare Managed Identities e selezionarlo.
2. Seleziona + Crea.
3. Selezionare la sottoscrizione, il gruppo di risorse e l'area e specificare un nome per l'identità.
4. Seleziona Rivedi e crea e quindi seleziona Crea.

Passaggio 3: Assegnare l'identità gestita assegnata dall'utente all'Azure Data Manager per la risorsa Energia

Assegnare l’identità gestita assegnata dall’utente creata nel Passaggio 2 alla risorsa Azure Data Manager for Energy.

Seguire questi tre passaggi secondari per collegare in modo sicuro l'identità gestita.

Passaggio 3.1: Ottenere la configurazione corrente

Recupera la configurazione completa della tua istanza di 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

Sostituire i segnaposto

Il comando visualizza la configurazione JSON completa senza troncamento. Esaminare attentamente il contenuto del adme-config.json file. È necessario copiare valori specifici da esso per il passaggio 3.2.

Passaggio 3.2: Aggiornare la configurazione con l'identità gestita

Aggiornare la configurazione aggiungendo l'identità gestita mantenendo tutte le proprietà esistenti.

# 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

Sostituire i segnaposto

Passaggio 3.3: Verificare l'allegato dell'identità gestita

Verificare che l'identità gestita sia stata collegata correttamente all'istanza di Azure Data Manager per l'energia.

# 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

Sostituire i segnaposto

Se si eseguono tutti i passaggi secondari nella stessa sessione del terminale, le variabili sono già impostate nel passaggio 3.1 e nel passaggio 3.2.

Output di esempio

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

L'output deve includere l'ID della risorsa dell'identità gestita. Se sono associate altre identità (CMEK, EDS), vengono visualizzate anche nell'elenco.

Passaggio 4: Verificare che l'utente disponga dell'accesso al gruppo di diritti

Per chiamare le API ACZ, è necessario che l'utente sia membro dei gruppi di diritti seguenti:

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

Questo passaggio verifica che l'utente che chiama le API ACZ abbia accesso, non l'identità gestita assegnata dall'utente. L'identità gestita assegnata dall'utente creata nel passaggio 2 viene usata solo da ACZ per scrivere i dati nell'archiviazione. Non è necessaria l'appartenenza al gruppo entitlement.

Se non sei già membro di questi gruppi di autorizzazione, chiedi a un amministratore di Azure Data Manager for Energy di aggiungere il tuo account utente. Per istruzioni dettagliate, vedere Gestire gli utenti in Azure Data Manager for Energy.

Per verificare di avere accesso, usare l'API del servizio Entitlements per verificare l'appartenenza a entrambi i gruppi.

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

Sostituire i segnaposto

Risposta di esempio

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

Entrambe le risposte devono includere il tuo account utente nell'array members. Se non figuri in nessuno dei due gruppi, contatta l'amministratore di Azure Data Manager for Energy per farti aggiungere a entrambi i gruppi richiesti.

Passaggio 5: Concedere le autorizzazioni di identità gestita assegnate dall'utente nel contenitore Data Lake Storage Gen2

Concedere all'identità gestita assegnata dall'utente l'accesso in scrittura all'account di archiviazione Data Lake Storage Gen2. L'identità ACZ deve disporre delle autorizzazioni Storage Blob Data Contributor per scrivere i file Delta Parquet.

1. Vai al tuo account di archiviazione Data Lake Storage Gen2 nel portale di Azure.
2. Selezionare Controllo di accesso (IAM) dal menu a sinistra.
3. Selezionare + Aggiungi>Aggiungi assegnazione di ruolo.
4. Nella scheda Ruolo, cerca Collaboratore ai dati BLOB di archiviazione, selezionalo e quindi seleziona Avanti.
5. Nella scheda Membri , per Assegna accesso a, selezionare Identità gestita.
6. Scegliere + Seleziona membri.
7. Nell'elenco a discesa Identità gestita selezionare Identità gestita assegnata dall'utente.
8. Selezionare l'identità gestita assegnata dall'utente creata nel passaggio 2 (o l'identità CMEK/EDS esistente) e quindi scegliere Seleziona.
9. Selezionare Rivedi e assegna per completare l'assegnazione di ruolo.

Passaggio 6: Condividere con Microsoft l'identità gestita assegnata dall'utente e i dettagli dell'istanza di Azure Data Manager for Energy (requisito dell'anteprima)

Durante l'anteprima, l'accesso ACZ richiede l'uso di elenchi consentiti. Microsoft deve abilitare la funzionalità ACZ nel Azure Data Manager per l'istanza di Energy e configurarla con l'identità gestita assegnata dall'utente. Condividere i dettagli seguenti con il contatto Microsoft per completare l'abilitazione di ACZ.

Fornire le informazioni seguenti al rappresentante Microsoft.

Dopo che Microsoft ha aggiunto l'identità gestita assegnata dall'utente all'elenco degli elementi consentiti, ACZ viene abilitato nella risorsa Azure Data Manager for Energy.

Creare un'istanza di ACZ

Dopo aver completato i passaggi di abilitazione, è possibile creare una o più istanze di ACZ per sincronizzare i dati di Azure Data Manager per l'energia in Data Lake Storage Gen2. È possibile configurare ogni istanza di ACZ per sincronizzare tipi di dati diversi.

Chiamare l'API ACZ Create

Usare l'API ACZ Create per creare un'istanza di ACZ. Per una procedura dettagliata completa, vedere Esercitazione: Usare le API 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

Sostituire i segnaposto

Una risposta con esito positivo restituisce lo stato 201 HTTP con i dettagli 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"
}

Prendere nota del aczId valore (formato: acz-<identifier>). È necessario questo identificatore ACZ per:

• Gestire ed eseguire query sull'istanza di ACZ usando le API.
• Individua i dati nell'archivio Data Lake Storage Gen2 in <container>/<aczId>/ o <container>/<basePath>/<aczId>/ se è stato specificato un percorso di base.

Contenuti correlati

• Esercitazione: Usare le API ACZ
• Collegare i dati ACZ a Microsoft Fabric
• Connessione dei dati ACZ ad Azure Databricks
• Concetti della zona di consumo di Analisi