チュートリアル: Analytics Consumption Zone API を使用する

このチュートリアルでは、Azure Data Manager for Energy で Analytics Consumption Zone (ACZ) 管理 API を使用する方法について説明します。 CURL を使用して、ACZ インスタンスを作成、一覧表示、取得、および削除します。

Important

分析消費ゾーンは現在プレビュー段階です。 ベータ版、プレビュー版、または一般公開されていないAzure機能に適用される法的条件については、「Microsoft Azure プレビューの補足使用条件」を参照してください。

プレビュー期間中、ACZ は開発者層インスタンスでのみ使用でき、許可リストを使用する必要があります。 分析消費ゾーンの有効化に関するページのガイダンスに従って、Microsoft担当者にお問い合わせください。

このチュートリアルでは、以下の内容を学習します。

  • ACZ インスタンスを作成します。
  • データ パーティション内のすべての ACZ インスタンスを一覧表示します。
  • 特定の ACZ インスタンスの詳細を取得します。
  • ACZ インスタンスを削除します。

前提条件

Tip

API を対話形式で調べる:https://{instance-name}.energy.azure.com/api/acz/v1/docsの Swagger UI を使用して、完全な ACZ API 仕様とテスト エンドポイントを表示できます。 {instance-name} を、Azure Data Manager for Energy インスタンス名に置き換えます。

Azure Data Manager for Energy インスタンスの詳細を取得する

Azure ポータルで、Azure Data Manager for Energy インスタンスからこれらの詳細を収集します。

始める前の準備

このチュートリアルのコード例では、 {curly-braces} 形式のプレースホルダー値を使用します。 これらのプレースホルダーは、コマンドの実行時に実際の値に置き換えます。

すべての API 呼び出しには認証が必要です。 Bash と PowerShell の例では、Azure CLIを使用したインライン トークンの生成が示されています。 別の認証方法については、「 認証トークンの生成」を参照してください。

ACZ インスタンスを作成する

Create ACZ API を使用して、データ パーティションの新しい ACZ インスタンスを設定します。

API

POST /api/acz/v1/aczs

重要なポイント

  • データ パーティションあたり最大 3 つの ACZ インスタンス (プレビュー制限)。
  • ACZ 名は、パーティション内で一意である必要があります。
  • ユーザー割り当てマネージド ID は次のようにする必要があります。
    • Azure Data Manager for Energy リソースに割り当てられます (「分析消費ゾーンを有効にする」を参照)。
    • 宛先の Azure Data Lake Storage Gen2 ストレージ アカウントに対して、Storage Blob Data Contributor ロールが付与されます。
  • 階層型名前空間が有効になっているData Lake Storage Gen2ストレージ アカウントが必要です。
# Get auth app ID for your Azure Data Manager for Energy instance
AUTH_APP_ID=$(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 $AUTH_APP_ID --query accessToken -o tsv)

# Create ACZ instance
curl --request POST \
  --url https://{base-url}/api/acz/v1/aczs \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'data-partition-id: {data-partition-id}' \
  --data '{
    "name": "{acz-name}",
    "aczType": "{acz-type}",
    "targetFormat": "DELTA_PARQUET",
    "allCatalogSync": false,
    "sink": {
      "storageType": "microsoft.storage/storageaccounts",
      "storageId": "{storage-resource-id}",
      "basePath": "{base-path}"
    },
    "configuration": {
      "catalogKinds": ["{catalog-kinds}"],
      "wellboreDDMSKinds": ["{wellbore-ddms-kinds}"]
    }
  }'

プレースホルダーを置き換える

プレースホルダー Description
{subscription-id} Azure Data Manager for Energy インスタンスが存在するサブスクリプション ID。
{resource-group} Azure Data Manager for Energy インスタンスを含むリソース グループ。
{adme-instance-name} お使いの Azure Data Manager for Energy のインスタンス名。
{base-url} Azure Data Manager for Energy インスタンスの URL (たとえば、myinstance.energy.azure.com)。
{data-partition-id} データ パーティション ID (たとえば、 opendes)。
{acz-name} ACZ インスタンスの表示名 (1 ~ 100 文字、例: my-acz-wells-and-logs)。
{acz-type} 省略可能: LATEST_VERSION (既定) は最新バージョンのみをエクスポートし、 ALL_VERSIONS はすべてのバージョンをエクスポートします。
{storage-resource-id} 宛先の Data Lake Storage Gen2 ストレージ アカウントの Azure リソース ID (たとえば、/subscriptions/xxx.../storageAccounts/mystorageacct)。
{base-path} 省略可能: ACZ データ出力のストレージ アカウント内のベース パス (たとえば、 acz-output)。
allCatalogSync 省略可能 (既定値: false)。 trueに設定すると、パーティションからすべてのカタログの種類がエクスポートされます。 セクションのconfigurationで指定されています。 trueすると、カタログ データの構成でのcatalogKindsとwellboreDDMSKindsは無視されます。
{catalog-kinds} 任意: 同期する OSDU® カタログの種類の文字列 (例: ["osdu:wks:master-data--Well:*"])。 allCatalogSyncがtrue場合は無視されます。
{wellbore-ddms-kinds} 任意: Wellbore Domain データ管理 Service (DDMS) の文字列を同期する (例: ["osdu:wks:work-product-component--WellLog:*"])。 ファイルのダウンロードは、ここに記載されている種類に対してのみ行われます。

Tip

すべてのカタログ データをエクスポートします。 データ パーティションからすべてのカタログの種類をエクスポートするには、 "allCatalogSync": true ( configuration セクションの外部) を設定します。 有効にすると、構成内の catalogKinds 配列と wellboreDDMSKinds 配列はカタログ データに対して無視されます。 Wellbore DDMS 一括ファイルのダウンロードは、 wellboreDDMSKindsに記載されている種類に対してのみ引き続き発生します。

次のオプションのうち少なくとも 1 つを指定する必要があります。

  • "allCatalogSync": true (外部構成) を設定します。
  • 設定で、少なくとも 1 つの kind パターンを含む配列 catalogKinds を指定します。
  • 構成で、少なくとも1つのkindパターンを含むwellboreDDMSKinds配列を指定してください。

レスポンスの例 (201 Created)

{
  "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"
  },
  "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-03-31T10:00:00Z",
  "updatedTs": "2026-03-31T10:00:00Z",
  "createdBy": "user@contoso.com"
}

ACZ インスタンスを作成すると、 PROCESSING 状態で履歴スナップショットが開始されます。 Get ACZ API を使用して状態を確認します。

ACZ インスタンスを一覧表示する

List ACZs API を使用して、データ パーティション内のすべての ACZ インスタンスを取得します。

API

GET /api/acz/v1/aczs

# Get auth app ID for your Azure Data Manager for Energy instance
AUTH_APP_ID=$(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 $AUTH_APP_ID --query accessToken -o tsv)

# List ACZ instances
curl --request GET \
  --url https://{base-url}/api/acz/v1/aczs \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Accept: application/json' \
  --header 'data-partition-id: {data-partition-id}'

プレースホルダーを置き換える

プレースホルダー Description
{subscription-id} Azure Data Manager for Energy インスタンスが存在するサブスクリプション ID。
{resource-group} Azure Data Manager for Energy インスタンスを含むリソース グループ。
{adme-instance-name} お使いの Azure Data Manager for Energy のインスタンス名。
{base-url} Azure Data Manager for Energy インスタンスの URL (たとえば、myinstance.energy.azure.com)。
{data-partition-id} データ パーティション ID (たとえば、 opendes)。

サンプル応答 (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"
      },
      "allCatalogSync": false,
      "configuration": {
        "catalogKinds": [
          "osdu:wks:master-data--Well:*"
        ]
      },
      "historicalSnapshotStatus": "PROCESSING",
      "createdTs": "2026-03-31T10:00:00Z",
      "updatedTs": "2026-03-31T10:00:00Z",
      "createdBy": "user@contoso.com"
    },
    {
      "aczId": "acz-xyz789ghi012",
      "name": "all-catalog-sync-example",
      "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"
      },
      "allCatalogSync": true,
      "configuration": {
        "wellboreDDMSKinds": [
          "osdu:wks:work-product-component--WellLog:*"
        ]
      },
      "historicalSnapshotStatus": "COMPLETED",
      "createdTs": "2026-03-31T09:00:00Z",
      "updatedTs": "2026-03-31T09:45:00Z",
      "createdBy": "user@contoso.com"
    }
  ],
  "count": 2
}

応答には、 ACTIVE、 FAILED、または ACCESS_DENIEDなど、任意の状態のすべての ACZ インスタンスが一覧表示されます。 この応答は、2 つの ACZ インスタンスを示しています。1 つは選択的カタログ同期 (特定の種類のallCatalogSync: false ) を使用し、もう 1 つは allCatalogSync: true を使用してすべてのカタログの種類をエクスポートします。

ACZ の詳細を取得する

Get ACZ API を使用して、特定の ACZ インスタンスの詳細を取得します。

API

GET /api/acz/v1/aczs/{acz-id}

# Get auth app ID for your Azure Data Manager for Energy instance
AUTH_APP_ID=$(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 $AUTH_APP_ID --query accessToken -o tsv)

# Get ACZ details
curl --request GET \
  --url https://{base-url}/api/acz/v1/aczs/{acz-id} \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Accept: application/json' \
  --header 'data-partition-id: {data-partition-id}'

プレースホルダーを置き換える

プレースホルダー Description
{subscription-id} Azure Data Manager for Energy インスタンスが存在するサブスクリプション ID。
{resource-group} Azure Data Manager for Energy インスタンスを含むリソース グループ。
{adme-instance-name} お客様の Azure Data Manager for Energy のインスタンス名。
{base-url} Azure Data Manager for Energy インスタンスの URL (たとえば、myinstance.energy.azure.com)。
{data-partition-id} データ パーティション ID (たとえば、 opendes)。
{acz-id} Create または List 応答からの ACZ 識別子 (たとえば、 acz-abc123def456)。

サンプル応答 (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"
  },
  "allCatalogSync": false,
  "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"
}

ACZ プロビジョニングを追跡するには、 status フィールドと historicalSnapshotStatus フィールドを確認します。

ACZ インスタンスを削除する

ACZ の削除 API を使用して、ACZ 構成を削除します。

API

DELETE /api/acz/v1/aczs/{acz-id}

Warnung

この削除操作を元に戻すことはできません。 すべての ACZ 構成が削除され、同期が停止されます。宛先Data Lake Storage Gen2ストレージ アカウントに既に存在するデータはそのまま残ります。

# Get auth app ID for your Azure Data Manager for Energy instance
AUTH_APP_ID=$(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 $AUTH_APP_ID --query accessToken -o tsv)

# Delete ACZ instance
curl --request DELETE \
  --url https://{base-url}/api/acz/v1/aczs/{acz-id} \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Accept: application/json' \
  --header 'data-partition-id: {data-partition-id}'

プレースホルダーを置き換える

プレースホルダー Description
{subscription-id} Azure Data Manager for Energy インスタンスが存在するサブスクリプション ID。
{resource-group} Azure Data Manager for Energy インスタンスを含むリソース グループ。
{adme-instance-name} お使いの Azure Data Manager for Energy のインスタンス名。
{base-url} Azure Data Manager for Energy インスタンスの URL (たとえば、myinstance.energy.azure.com)。
{data-partition-id} データ パーティション ID (たとえば、 opendes)。
{acz-id} Create または List 応答からの ACZ 識別子 (たとえば、 acz-abc123def456)。

サンプル応答 (204 コンテンツなし)

削除が成功すると、応答本文のない HTTP 204 が返されます。 クリーンアップの実行中に、ACZ の状態が DELETING に変わります。

エラー応答

ACZ API は、次のエラー コードを返します。

HTTP 状態 Description
400 要求が正しくありません。 要求本文で検証エラーを確認します。
401 権限がありません。 ベアラー トークンが見つからないか、無効です。
403 禁止されています。 ユーザーは、必要なエンタイトルメント グループに属していません。
404 見つかりません。 指定された ACZ ID が存在しません。
422 検証に失敗しました。 要求本文に無効な値があります。
500 内部サーバー エラー。 このエラーが解決しない場合は、サポートにお問い合わせください。

関連するコンテンツ

  • Last updated on