Tutoriel : Utiliser les API de la zone de consommation analytique (ACZ)

Ce tutoriel montre comment utiliser les API de gestion ACZ dans Azure Data Manager for Energy. Vous créez, listez, récupérez et supprimez des instances ACZ à l’aide de cURL.

Important

Analytics Consumption Zone est actuellement en version préliminaire. Consultez les Conditions d’utilisation supplémentaires pour les préversions Microsoft Azure pour les conditions légales qui s’appliquent aux fonctionnalités Azure en version bêta, en préversion ou qui ne sont pas encore publiées en disponibilité générale.

Note

Dans le cadre de la préversion, ACZ est disponible uniquement sur les instances de niveau Developer et nécessite une autorisation préalable. Suivez les instructions de How to enable the Analytics Consumption Zone (ACZ) et contactez votre représentant Microsoft.

Dans ce tutoriel, vous allez apprendre à :

Créer une zone de consommation Analytics
Lister toutes les ACZ dans une partition de données
Obtenir les détails sur une ACZ particulière
Supprimer un ACZ

Prerequisites

Un abonnement Azure. Créez-en un gratuitement.
Instance de Azure Data Manager for Energy (niveau développeur) dans votre abonnement Azure. Créez une instance Azure Data Manager for Energy.
ACZ activé pour votre instance. Découvrez comment activer la zone de consommation Analytics (ACZ).
Un compte de stockage Azure Data Lake Storage (ADLS) Gen2 avec un espace de noms hiérarchique activé, pour lequel l’identité managée affectée par l’utilisateur autorisée pour les opérations ACZ dispose du rôle Contributeur aux données Blob du stockage.
Votre compte d’utilisateur doit appartenir au users@{data-partition-id}.dataservices.energy groupe de droits d’utilisation pour appeler les API ACZ. Découvrez comment gérer les utilisateurs.
cURL installé sur votre ordinateur (pour les exemples Bash) ou PowerShell 5.1+ (pour les exemples PowerShell).
Azure CLI installé et authentifié.
Jeton d’accès pour l’authentification. Découvrez comment générer un jeton d’authentification.

Tip

Explorer l’API de manière interactive
Vous pouvez afficher la spécification complète de l’API ACZ et les points de terminaison de test à l’aide de l’interface utilisateur Swagger à l’adresse https://{instance-name}.energy.azure.com/api/acz/v1/docs. Remplacez {instance-name} par le nom de votre Azure Data Manager pour l’instance Energy.

Obtenez les détails de votre Azure Data Manager pour l’instance Energy

Rassemblez ces détails à partir de votre instance Azure Data Manager for Energy dans le portail Azure :

Paramètre	Description	Example
`base_url`	URL de votre instance Azure Data Manager for Energy.	`https://<instance>.energy.azure.com`
`data_partition_id`	Nom de la partition de données.	`opendes`
`storage_resource_id`	ID de ressource Azure du compte de stockage ADLS Gen2.	`/subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{account}`

Générez un access_token pour l’authentification en suivant les instructions figurant dans Comment générer un jeton d’authentification.

Créer une application ACZ

Utilisez l’API Create ACZ pour configurer une nouvelle zone de consommation Analytics pour une partition de données.

API : POST /api/acz/v1/aczs

Points clés :

Trois ACZ maximum par partition de données (limite de la version préliminaire).
Le nom ACZ doit être unique dans la partition.
L’identité managée attribuée par l’utilisateur doit être :
- Affecté à votre ressource Azure Data Manager for Energy
- Rôle Storage Blob Data Contributor accordé pour le compte de stockage ADLS Gen2 de destination
Votre utilisateur doit appartenir au groupe de droits d’utilisation users@{data-partition-id}.dataservices.energy .

Bash
Powershell

curl --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": "{acz-name}",
    "aczType": "{acz-type}",
    "targetFormat": "DELTA_PARQUET",
    "sink": {
      "storageType": "microsoft.storage/storageaccounts",
      "storageId": "{storage-resource-id}",
      "basePath": "{base-path}"
    },
    "configuration": {
      "catalogKinds": {catalog-kinds},
      "wellboreDDMSKinds": {wellbore-ddms-kinds}
    }
  }'

# Get auth app ID for your ADME instance
$authAppId = az resource show --ids /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.OpenEnergyPlatform/energyServices/{adme-instance-name} --query properties.authAppId -o tsv

# Get access token
$token = az account get-access-token --resource $authAppId --query accessToken -o tsv

# Build request body
$body = @{
    name = "{acz-name}"
    aczType = "{acz-type}"
    targetFormat = "DELTA_PARQUET"
    sink = @{
        storageType = "microsoft.storage/storageaccounts"
        storageId = "{storage-resource-id}"
        basePath = "{base-path}"
    }
    configuration = @{
        catalogKinds = @("{catalog-kinds}")
        wellboreDDMSKinds = @("{wellbore-ddms-kinds}")
    }
} | ConvertTo-Json -Depth 10

# Create ACZ
Invoke-RestMethod -Uri "https://{base-url}/api/acz/v1/aczs" -Method Post -Headers @{
    "Authorization" = "Bearer $token"
    "Content-Type" = "application/json"
    "data-partition-id" = "{data-partition-id}"
} -Body $body

Paramètres de la demande

Paramètre	Lieu	Description
`{base-url}`	URL	URL de votre instance data Manager for Energy Azure (par exemple, `myinstance.energy.azure.com`)
`{access-token}`	En-tête (autorisation)	Azure Data Manager pour le jeton d’accès à l’énergie. Découvrez comment générer un jeton d’authentification
`{data-partition-id}`	Header	VOTRE ID de partition de données (par exemple, `opendes`)

Paramètres du corps de la requête

Paramètre	Type	Obligatoire	Description
`{acz-name}`	string	Oui	Nom d’affichage pour l’ACZ (1 à 100 caractères, par exemple, `my-acz-wells-and-logs`).
`{acz-type}`	string	Non	`LATEST_VERSION` (valeur par défaut) exporte uniquement la dernière version. `ALL_VERSIONS` exporte toutes les versions.
`{storage-resource-id}`	string	Oui	Azure ID de ressource du compte de stockage ADLS Gen2 de destination (par exemple, `/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/my-rg/providers/Microsoft.Storage/storageAccounts/mystorageacct`).
`{base-path}`	string	Non	Chemin d’accès de base dans le compte de stockage pour la sortie des données ACZ (par exemple, `acz-output`).
`{catalog-kinds}`	chaîne de caractères[]	Non	Chaînes « kind » du catalogue OSDU® à synchroniser (par exemple, `["osdu:wks:master-data--Well:", "osdu:wks:reference-data--UnitOfMeasure:"]`).
`{wellbore-ddms-kinds}`	chaîne de caractères[]	Non	Chaînes de type du Wellbore Domain Gestion des données Service (DDMS) à synchroniser (par exemple, `["osdu:wks:work-product-component--WellLog:*"]`).

Note

Vous devez fournir au moins l’un de {catalog-kinds} ou {wellbore-ddms-kinds} dans la configuration.

Exemple de réponse (201 Créé)

{
  "aczId": "acz-abc123def456",
  "name": "my-acz-wells-and-logs",
  "status": "ACTIVE",
  "aczType": "LATEST_VERSION",
  "targetFormat": "DELTA_PARQUET",
  "sink": {
    "storageType": "microsoft.storage/storageaccounts",
    "storageId": "/subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{account}",
    "basePath": "acz-output"
  },
  "configuration": {
    "catalogKinds": [
      "osdu:wks:master-data--Well:*",
      "osdu:wks:reference-data--UnitOfMeasure:*"
    ],
    "wellboreDDMSKinds": [
      "osdu:wks:work-product-component--WellLog:*"
    ]
  },
  "historicalSnapshotStatus": "PROCESSING",
  "createdTs": "2026-03-31T10:00:00Z",
  "updatedTs": "2026-03-31T10:00:00Z",
  "createdBy": "user@contoso.com"
}

Une fois que vous avez créé l’ACZ, l’instantané historique commence avec l’état PROCESSING. Utilisez l’API Get ACZ pour vérifier l’état.

Lister les ACZs

Utilisez l’API List ACZs pour obtenir toutes les zones de consommation d’analyse dans une partition de données.

API : GET /api/acz/v1/aczs

Bash
Powershell

curl --request GET \
  --url https://{base_url}/api/acz/v1/aczs \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Accept: application/json' \
  --header 'data-partition-id: {data_partition_id}'

# Get auth app ID for your ADME instance
$authAppId = az resource show --ids /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.OpenEnergyPlatform/energyServices/{adme-instance-name} --query properties.authAppId -o tsv

# Get access token
$token = az account get-access-token --resource $authAppId --query accessToken -o tsv

# List ACZs
Invoke-RestMethod -Uri "https://{base_url}/api/acz/v1/aczs" -Method Get -Headers @{
    "Authorization" = "Bearer $token"
    "Accept" = "application/json"
    "data-partition-id" = "{data_partition_id}"
}

Exemple de réponse (200 OK)

{
  "items": [
    {
      "aczId": "acz-abc123def456",
      "name": "my-acz-wells-and-logs",
      "status": "ACTIVE",
      "aczType": "LATEST_VERSION",
      "targetFormat": "DELTA_PARQUET",
      "sink": {
        "storageType": "microsoft.storage/storageaccounts",
        "storageId": "/subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{account}",
        "basePath": "acz-output"
      },
      "configuration": {
        "catalogKinds": [
          "osdu:wks:master-data--Well:*",
          "osdu:wks:reference-data--UnitOfMeasure:*"
        ],
        "wellboreDDMSKinds": [
          "osdu:wks:work-product-component--WellLog:*"
        ]
      },
      "historicalSnapshotStatus": "COMPLETED",
      "createdTs": "2026-03-31T10:00:00Z",
      "updatedTs": "2026-03-31T10:30:00Z",
      "createdBy": "user@contoso.com"
    }
  ],
  "count": 1
}

La réponse répertorie toutes les ACZ, quel que soit leur état : ACTIVE, FAILED, ou ACCESS_DENIED.

Obtenir les détails d’ACZ

Utilisez l’API Get ACZ pour obtenir des détails sur un ACZ spécifique.

API : GET /api/acz/v1/aczs/{acz_id}

Bash
Powershell

curl --request GET \
  --url https://{base_url}/api/acz/v1/aczs/{acz_id} \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Accept: application/json' \
  --header 'data-partition-id: {data_partition_id}'

# Get auth app ID for your ADME instance
$authAppId = az resource show --ids /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.OpenEnergyPlatform/energyServices/{adme-instance-name} --query properties.authAppId -o tsv

# Get access token
$token = az account get-access-token --resource $authAppId --query accessToken -o tsv

# Get ACZ details
Invoke-RestMethod -Uri "https://{base_url}/api/acz/v1/aczs/{acz_id}" -Method Get -Headers @{
    "Authorization" = "Bearer $token"
    "Accept" = "application/json"
    "data-partition-id" = "{data_partition_id}"
}

Remplacez {acz_id} par l’identificateur ACZ de la réponse Créer ou Liste.

Exemple de réponse (200 OK)

{
  "aczId": "acz-abc123def456",
  "name": "my-acz-wells-and-logs",
  "status": "ACTIVE",
  "aczType": "LATEST_VERSION",
  "targetFormat": "DELTA_PARQUET",
  "sink": {
    "storageType": "microsoft.storage/storageaccounts",
    "storageId": "/subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{account}",
    "basePath": "acz-output"
  },
  "configuration": {
    "catalogKinds": [
      "osdu:wks:master-data--Well:*",
      "osdu:wks:reference-data--UnitOfMeasure:*"
    ],
    "wellboreDDMSKinds": [
      "osdu:wks:work-product-component--WellLog:*"
    ]
  },
  "historicalSnapshotStatus": "COMPLETED",
  "createdTs": "2026-03-31T10:00:00Z",
  "updatedTs": "2026-03-31T10:30:00Z",
  "createdBy": "user@contoso.com"
}

Pour suivre l’approvisionnement ACZ, vérifiez les champs status et historicalSnapshotStatus.

Supprimer un ACZ

Utilisez l’API Delete ACZ pour supprimer une configuration ACZ.

API : DELETE /api/acz/v1/aczs/{acz_id}

Avertissement

Cette action de suppression ne peut pas être annulée. Elle supprime toute configuration ACZ et arrête la synchronisation. Les données déjà contenues dans le compte de stockage ADLS de destination restent intactes.

Bash
Powershell

curl --request DELETE \
  --url https://{base_url}/api/acz/v1/aczs/{acz_id} \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Accept: application/json' \
  --header 'data-partition-id: {data_partition_id}'

# Get auth app ID for your ADME instance
$authAppId = az resource show --ids /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.OpenEnergyPlatform/energyServices/{adme-instance-name} --query properties.authAppId -o tsv

# Get access token
$token = az account get-access-token --resource $authAppId --query accessToken -o tsv

# Delete ACZ
Invoke-RestMethod -Uri "https://{base_url}/api/acz/v1/aczs/{acz_id}" -Method Delete -Headers @{
    "Authorization" = "Bearer $token"
    "Accept" = "application/json"
    "data-partition-id" = "{data_partition_id}"
}

Exemple de réponse (204 Aucun contenu)

Une suppression réussie retourne HTTP 204 sans corps de réponse. L’état ACZ passe à DELETING pendant le nettoyage.

Réponses d’erreur

Les API ACZ retournent ces codes d’erreur :

État HTTP	Description
`400`	Demande incorrecte Vérifiez le corps de la demande pour connaître les erreurs de validation.
`401`	Non autorisé. Le jeton Bearer est manquant ou invalide.
`403`	Interdit. L’utilisateur n’appartient pas au groupe de droits requis.
`404`	Introuvable. L’ID ACZ spécifié n’existe pas.
`422`	Échec de la validation. Le corps de la requête a des valeurs qui ne sont pas valides.
`500`	Erreur interne du serveur. Contactez le support technique si cette erreur persiste.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-05-20

Tutoriel : Utiliser les API de la zone de consommation analytique (ACZ)

Prerequisites

Obtenez les détails de votre Azure Data Manager pour l’instance Energy

Créer une application ACZ

Paramètres de la demande

Paramètres du corps de la requête

Exemple de réponse (201 Créé)

Lister les ACZs

Exemple de réponse (200 OK)

Obtenir les détails d’ACZ

Exemple de réponse (200 OK)

Supprimer un ACZ

Exemple de réponse (204 Aucun contenu)

Réponses d’erreur

Contenu connexe

Commentaires

Ressources supplémentaires