Samouczek: Jak używać interfejsów API strefy użycia Analytics

W tym samouczku pokazano, jak używać interfejsów API zarządzania strefą zużycia danych analitycznych (ACZ) w usłudze Azure Data Manager for Energy. Tworzysz, wyświetlasz listę, pobierasz i usuwasz instancje ACZ za pomocą narzędzia cURL.

W tym poradniku nauczysz się, jak:

Wymagania wstępne

• Subskrypcja platformy Azure. Utwórz je bezpłatnie.
• Instancja Azure Data Manager for Energy (Developer lub Standard Tier) w Twojej subskrypcji Azure. Utwórz wystąpienie usługi Azure Data Manager dla usługi Energy.
• Włączono ACZ dla Twojej instancji. Zobacz Włączanie strefy korzystania z analityki.
• Zainstalowano i uwierzytelniono usługę Azure CLI (az login).
• cURL (dla przykładów w Bashu) lub PowerShell 5.1+ (dla przykładów w programie PowerShell).

Pobierz szczegóły wystąpienia Azure Data Manager for Energy

Zbierz te szczegóły z instancji Azure Data Manager for Energy w portalu Azure.

Zanim rozpoczniesz

Przykłady kodu w tym samouczku korzystają z wartości zastępczych w formacie {curly-braces}. Zastąp te symbole zastępcze rzeczywistymi wartościami podczas uruchamiania poleceń.

Wszystkie wywołania interfejsu API wymagają uwierzytelniania. Przykłady powłoki Bash i programu PowerShell pokazują wbudowane generowanie tokenów przy użyciu Azure CLI. Aby zapoznać się z alternatywnymi metodami uwierzytelniania, zobacz Generowanie tokenu uwierzytelniania.

Utwórz instancję ACZ

Użyj interfejsu API Create ACZ, aby utworzyć nowe wystąpienie ACZ dla partycji danych.

API

POST /api/acz/v1/aczs

Kwestie kluczowe

• Możesz mieć do trzech instancji ACZ na partycję danych.
• Nazwa ACZ musi być unikalna w obrębie partycji.
• Tożsamość zarządzana przypisana przez użytkownika musi być:
  • Przypisane do zasobu Azure Data Manager for Energy (zobacz Włącz strefę zużycia analizy).
  • Przypisano rolę Współautor danych obiektów blob usługi Storage na docelowym koncie magazynu danych Azure Data Lake Storage Gen2.
• Wymagane jest konto magazynu Data Lake Storage Gen2 z włączoną hierarchiczną przestrzenią nazw.

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

# Get auth app ID for your Azure Data Manager for Energy 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"
    allCatalogSync = $false
    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 instance
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

Zastąp symbole zastępcze

Musisz podać co najmniej jedną z następujących opcji:

• Ustaw "allCatalogSync": true (konfigurację zewnętrzną).
• Podaj catalogKinds tablicę w konfiguracji z co najmniej jednym wzorcem rodzaju.
• Podaj wellboreDDMSKinds tablicę w konfiguracji z co najmniej jednym wzorcem rodzaju.

Przykładowa odpowiedź (201 Utworzono)

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

Po utworzeniu instancji ACZ rozpoczyna się tworzenie migawki historycznej w stanie PROCESSING. Użyj interfejsu API get ACZ, aby sprawdzić stan.

Wyświetlanie listy wystąpień usługi ACZ

Użyj interfejsu API List ACZs, aby pobrać wszystkie instancje ACZ w partycji danych.

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}'

# Get auth app ID for your Azure Data Manager for Energy 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 ACZ instances
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}"
}

Zastąp symbole zastępcze

Przykładowa odpowiedź (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
}

Odpowiedź zawiera listę wszystkich wystąpień ACZ w dowolnym stanie: ACTIVE, FAILEDlub ACCESS_DENIED. Ta odpowiedź przedstawia dwie instancje ACZ: jedną wykorzystującą selektywną synchronizację katalogu (allCatalogSync: false z określonymi typami) oraz drugą używającą allCatalogSync: true do eksportu wszystkich typów katalogu.

Pobierz szczegóły ACZ

Użyj interfejsu API Get ACZ, aby uzyskać szczegóły określonej instancji 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}'

# Get auth app ID for your Azure Data Manager for Energy 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}"
}

Zastąp symbole zastępcze

Przykładowa odpowiedź (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
}

Aby śledzić udostępnianie ACZ, sprawdź pola status i historicalSnapshotStatus.

Odpowiedź zawiera również:

• catalogSchemaVersion: Wersja schematu tabeli osducatalog . Nowe instancje ACZ używają wersji 2, która dodaje kolumny modifyUser i modifyTime (and). Szczegóły można znaleźć w Koncepcjach Strefy Konsumpcji Analityki.
• maintenance: Status działań konserwacyjnych tabeli Delta, które wykonuje ACZ (OPTIMIZE_Z_ORDER oraz VACUUM), w tym czas ostatniej próby i ostatni czas udanego uruchomienia. Macierz jest pusta aż do pierwszego uruchomienia konserwacji.

Usuń instancję ACZ

Użyj interfejsu API Delete ACZ, aby usunąć konfigurację ACZ.

API

DELETE /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)

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

# Get auth app ID for your Azure Data Manager for Energy 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 instance
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}"
}

Zastąp symbole zastępcze

Przykładowa odpowiedź (204 Brak zawartości)

Pomyślne usunięcie zwraca kod HTTP 204 bez treści odpowiedzi. Stan ACZ zmienia się na DELETING, gdy trwa czyszczenie.

Odpowiedzi na błędy

Interfejsy API ACZ zwracają następujące kody błędów.

Treści powiązane

• Pojęcia strefy korzystania z analiz
• Włącz strefę korzystania z analityki
• Połącz dane ACZ do Microsoft Fabric
• Połącz dane ACZ do Azure Databricks
• Połącz dane ACZ ze Snowflake
• Eksport uprawnień w Analytics Consumption Zone (podgląd)