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.

Important

Strefa Analytics Consumption jest obecnie dostępna w wersji zapoznawczej. Aby uzyskać postanowienia prawne dotyczące funkcji Azure dostępnych w wersji beta, wersji zapoznawczej lub w inny sposób, które nie zostały jeszcze wydane w wersji ogólnodostępnej, zobacz Dodatkowe warunki użytkowania dla wersji zapoznawczych Microsoft Azure.

W wersji zapoznawczej usługa ACZ jest dostępna tylko w wystąpieniach w warstwie Developer i wymaga stosowania list dozwolonych. Postępuj zgodnie ze wskazówkami zawartymi w artykule Włącz strefę użycia usługi Analytics, i skontaktuj się z przedstawicielem firmy Microsoft.

W tym poradniku nauczysz się, jak:

  • Utwórz instancję ACZ.
  • Wyświetl listę wszystkich wystąpień ACZ w partycji danych.
  • Uzyskaj szczegóły określonego wystąpienia usługi ACZ.
  • Usuń instancję ACZ.

Wymagania wstępne

Wskazówka

Interaktywnie przeglądaj interfejs API: Możesz wyświetlić pełną specyfikację interfejsu API ACZ i testować punkty końcowe w interfejsie Swagger UI pod adresem https://{instance-name}.energy.azure.com/api/acz/v1/docs. Zastąp {instance-name} nazwą Twojego wystąpienia Azure Data Manager for Energy.

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

  • Maksymalnie trzy wystąpienia ACZ na każdą partycję danych (limit w wersji zapoznawczej).
  • 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}"]
    }
  }'

Zastąp symbole zastępcze

Placeholder Description
{subscription-id} Identyfikator subskrypcji, w której znajduje się wystąpienie usługi Azure Data Manager for Energy.
{resource-group} Grupa zasobów zawierająca wystąpienie usługi Azure Data Manager for Energy.
{adme-instance-name} Nazwa wystąpienia usługi Azure Data Manager for Energy.
{base-url} Adres URL wystąpienia Twojego Azure Data Manager for Energy (na przykład myinstance.energy.azure.com).
{data-partition-id} Identyfikator partycji danych (na przykład opendes).
{acz-name} Nazwa wyświetlana instancji ACZ (1–100 znaków, na przykład my-acz-wells-and-logs).
{acz-type} Opcjonalnie: LATEST_VERSION (ustawienie domyślne) eksportuje tylko najnowszą wersję i ALL_VERSIONS eksportuje wszystkie wersje.
{storage-resource-id} Azure identyfikator zasobu docelowego konta magazynu Data Lake Storage Gen2 (na przykład /subscriptions/xxx.../storageAccounts/mystorageacct).
{base-path} Opcjonalnie: ścieżka podstawowa w ramach konta magazynu dla danych wyjściowych ACZ (na przykład acz-output).
allCatalogSync Opcjonalne (ustawienie domyślne: false). Gdy jest ustawiona wartość true, eksportuje wszystkie rodzaje wykazu z partycji. Określony poza sekcją configuration . Gdy w konfiguracji ignorowane są true, catalogKinds i wellboreDDMSKinds dla danych katalogu.
{catalog-kinds} Opcjonalnie: ciągi typu katalogu OSDU® do synchronizacji (na przykład ["osdu:wks:master-data--Well:*"]). Ignorowane, jeśli allCatalogSync ma wartość true.
{wellbore-ddms-kinds} Opcjonalnie: ciągi znaków rodzaju Wellbore Domain Zarządzanie danymi Service (DDMS) do synchronizacji (na przykład ["osdu:wks:work-product-component--WellLog:*"]). Pobieranie plików odbywa się tylko w przypadku rodzajów wymienionych tutaj.

Wskazówka

Eksportuj wszystkie dane wykazu: Ustaw "allCatalogSync": true opcję (poza sekcją configuration ), aby wyeksportować wszystkie rodzaje wykazu z partycji danych. Po włączeniu tablice catalogKinds i wellboreDDMSKinds w konfiguracji są ignorowane w przypadku danych katalogu. Zbiorcze pobieranie plików Wellbore DDMS jest nadal dostępne tylko dla typów wymienionych w wellboreDDMSKinds.

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 w konfiguracji tablicę wellboreDDMSKinds z co najmniej jednym wzorcem typu.

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

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

Zastąp symbole zastępcze

Placeholder Description
{subscription-id} Identyfikator subskrypcji, w której znajduje się wystąpienie usługi Azure Data Manager for Energy.
{resource-group} Grupa zasobów, w której znajduje się wystąpienie usługi Azure Data Manager for Energy.
{adme-instance-name} Nazwa wystąpienia usługi Azure Data Manager for Energy.
{base-url} Adres URL instancji Azure Data Manager for Energy (na przykład myinstance.energy.azure.com).
{data-partition-id} Identyfikator partycji danych (na przykład opendes).

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

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

Zastąp symbole zastępcze

Placeholder Description
{subscription-id} Identyfikator subskrypcji, w której znajduje się wystąpienie Azure Data Manager for Energy.
{resource-group} Grupa zasobów zawierająca wystąpienie Azure Data Manager for Energy.
{adme-instance-name} Nazwa instancji usługi Azure Data Manager for Energy.
{base-url} Adres URL Twojego wystąpienia usługi Azure Data Manager for Energy (na przykład myinstance.energy.azure.com).
{data-partition-id} Identyfikator partycji danych (na przykład opendes).
{acz-id} Identyfikator ACZ z odpowiedzi na operację tworzenia lub wyświetlania listy (na przykład acz-abc123def456).

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

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

Usuń instancję ACZ

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

API

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

Warning

Nie można cofnąć tej akcji usuwania. Usuwa całą konfigurację ACZ i zatrzymuje synchronizację. Dane już na docelowym koncie magazynu Data Lake Storage Gen2 pozostają nienaruszone.

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

Zastąp symbole zastępcze

Placeholder Description
{subscription-id} Identyfikator subskrypcji, w której znajduje się wystąpienie usługi Azure Data Manager for Energy.
{resource-group} Grupa zasobów, która zawiera instancję Azure Data Manager for Energy.
{adme-instance-name} Nazwa wystąpienia usługi Azure Data Manager for Energy.
{base-url} Adres URL Twojego wystąpienia Azure Data Manager for Energy (na przykład myinstance.energy.azure.com).
{data-partition-id} Identyfikator partycji danych (na przykład opendes).
{acz-id} Identyfikator ACZ z odpowiedzi na operację Create lub List (na przykład acz-abc123def456).

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.

Kod statusu HTTP Description
400 Nieprawidłowe żądanie. Sprawdź treść żądania pod kątem błędów walidacji.
401 Brak autoryzacji. Brak tokenu elementu nośnego lub jest on nieprawidłowy.
403 Zakazany. Użytkownik nie należy do wymaganej grupy uprawnień.
404 Nie znaleziono. Określony identyfikator ACZ nie istnieje.
422 Sprawdzanie poprawności nie powiodło się. Treść żądania zawiera wartości, które nie są prawidłowe.
500 Wewnętrzny błąd serwera. Skontaktuj się z pomocą techniczną, jeśli ten błąd będzie się powtarzać.

Treści powiązane

  • Last updated on