本教學展示了如何在 Azure Data Manager for Energy 中使用分析消耗區(ACZ)管理 API。 你可以透過使用 cURL 來建立、列出、檢索和刪除 ACZ 實例。
在這個教學中,你會學到如何:
- 建立一個 ACZ 實例。
- 列出資料分割區中的所有 ACZ 實例。
- 取得特定ACZ實例的詳細資訊。
- 刪除一個 ACZ 實例。
先決條件
- Azure 訂用帳戶。 免費創建一個。
- 在你的 Azure 訂閱中有一個 Azure Data Manager for Energy(開發者或標準層)實例。 建立一個 Azure Data Manager for Energy 實例。
- 已為你的執行個體啟用 ACZ。 請參閱 啟用分析使用區域。
- Azure CLI 已安裝並認證(
az login)。 - cURL(用於 Bash 範例)或 PowerShell 5.1+(用於 PowerShell 範例)。
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 |
內部伺服器錯誤。 如果錯誤持續,請聯絡客服。 |