教學課程:使用 Analytics Consumption Zone API

本教學展示了如何在 Azure Data Manager for Energy 中使用分析消耗區(ACZ)管理 API。 你可以透過使用 cURL 來建立、列出、檢索和刪除 ACZ 實例。

在這個教學中,你會學到如何:

  • 建立一個 ACZ 實例。
  • 列出資料分割區中的所有 ACZ 實例。
  • 取得特定ACZ實例的詳細資訊。
  • 刪除一個 ACZ 實例。

先決條件

Tip

互動式探索 API: 你可以透過 Swagger 介面 https://{instance-name}.energy.azure.com/api/acz/v1/docs查看完整的 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

重點

  • 每個資料分割區最多可以有三個 ACZ 實例。
  • ACZ 名稱必須在分割區內唯一。
  • 使用者指派的管理身份必須是:
    • 已指派給您的 Azure Data Manager for Energy 資源 (請參閱啟用 Analytics Consumption Zone)。
    • 已授與目的地 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 執行個體所在位置的訂用帳戶識別碼。
{resource-group} 包含你 Azure Energy Data Manager 實例的資源群組。
{adme-instance-name} 您的 Azure Data Manager for Energy 執行個體名稱。
{base-url} 你的 Azure 能源資料管理員 實例 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 資源識別碼(例如 /subscriptions/xxx.../storageAccounts/mystorageacct)。
{base-path} 可選:用於 ACZ 輸出的儲存位置(例如 acz-output ,或 acz-output/workbench)。 第一個區段是容器名稱;如果容器不存在,ACZ 會建立該容器。 第一個區段必須是有效的容器名稱。 關於命名規則,請參見「 命名與引用容器、blobs 與元資料」。 剩餘的區段則是資料夾。 ACZ 將資料寫入 <basePath>/<aczId>/。 若省略 basePath,ACZ 會建立一個以 aczId 命名的容器,並將資料寫入 <aczId>/<aczId>/。 如果你使用 Swagger 介面,請替換佔位值 string;否則,ACZ 會建立一個名為 string的容器。
allCatalogSync 可選(預設: false)。 當 設定為 true時,會從分割區匯出所有目錄類型。 指定於區段configuration 當組態中的true和catalogKindswellboreDDMSKinds在處理目錄資料時遭到忽略。
{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 中列出的種類發生。

您必須提供以下至少一項選項:

  • 設定 "allCatalogSync": true(設定之外)。
  • 在設定中提供 catalogKinds 陣列,其中至少包含一個種類模式。
  • 在設定中提供 wellboreDDMSKinds 陣列,其中至少包含一個種類模式。

範例回應(201 個已建立)

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

建立 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 執行個體所在位置的訂用帳戶識別碼。
{resource-group} 包含你 Azure Energy Data Manager 實例的資源群組。
{adme-instance-name} 您的 Azure Data Manager for Energy 執行個體名稱。
{base-url} 你的 Azure 能源資料管理員 實例 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",
      "maintenance": [],
      "createdTs": "2026-03-31T10:00:00Z",
      "updatedTs": "2026-03-31T10:00:00Z",
      "createdBy": "user@contoso.com",
      "catalogSchemaVersion": 2
    },
    {
      "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",
      "maintenance": [
        {
          "activity": "OPTIMIZE_Z_ORDER",
          "status": "SUCCEEDED",
          "lastAttemptTs": "2026-04-01T03:00:00Z",
          "lastSuccessfulTs": "2026-04-01T03:00:12Z"
        },
        {
          "activity": "VACUUM",
          "status": "SUCCEEDED",
          "lastAttemptTs": "2026-04-01T03:00:12Z",
          "lastSuccessfulTs": "2026-04-01T03:00:13Z"
        }
      ],
      "createdTs": "2026-03-31T09:00:00Z",
      "updatedTs": "2026-03-31T09:45:00Z",
      "createdBy": "user@contoso.com",
      "catalogSchemaVersion": 2
    }
  ],
  "count": 2
}

回應列出所有處於任意狀態的 ACZ 實例: ACTIVE、、 FAILED或 ACCESS_DENIED。 這個回應顯示了兩個 ACZ 實例:一個使用選擇性目錄同步(allCatalogSync: false 針對特定類型),另一個則用 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 執行個體所在位置的訂用帳戶識別碼。
{resource-group} 包含你 Azure Energy Data Manager 實例的資源群組。
{adme-instance-name} 您的 Azure Data Manager for Energy 執行個體名稱。
{base-url} 你的 Azure 能源資料管理員 實例 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",
  "maintenance": [
    {
      "activity": "OPTIMIZE_Z_ORDER",
      "status": "SUCCEEDED",
      "lastAttemptTs": "2026-04-01T03:00:00Z",
      "lastSuccessfulTs": "2026-04-01T03:00:12Z"
    },
    {
      "activity": "VACUUM",
      "status": "SUCCEEDED",
      "lastAttemptTs": "2026-04-01T03:00:12Z",
      "lastSuccessfulTs": "2026-04-01T03:00:13Z"
    }
  ],
  "createdTs": "2026-03-31T10:00:00Z",
  "updatedTs": "2026-03-31T10:30:00Z",
  "createdBy": "user@contoso.com",
  "catalogSchemaVersion": 2
}

要追蹤 ACZ 配置,請檢查 status and historicalSnapshotStatus 欄位。

回應內容還包括:

  • catalogSchemaVersion:osducatalog 資料表的 schema 版本。 新的 ACZ 實例使用第 2 版,新增了 modifyUser 和 modifyTime 欄位。 詳情請參閱 分析消費區概念。
  • maintenance: ACZ 執行的 Delta 表格維護活動狀態(OPTIMIZE_Z_ORDER 及 VACUUM),包括最後嘗試時間及最後成功執行時間。 陣列在第一次維護前是空的。

刪除 ACZ 實例

使用 Delete ACZ API 移除 ACZ 設定。

API

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

Warning

這個刪除動作無法撤銷。 它會移除所有 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 執行個體所在位置的訂用帳戶識別碼。
{resource-group} 包含你 Azure Energy Data Manager 實例的資源群組。
{adme-instance-name} 您的 Azure Data Manager for Energy 執行個體名稱。
{base-url} 你的 Azure 能源資料管理員 實例 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 內部伺服器錯誤。 如果錯誤持續,請聯絡客服。