Öğretici: Analitik Tüketim Alanı API'lerini Kullanma

Bu öğreticide, Azure Data Manager for Energy'de Analiz Tüketim Bölgesi (ACZ) yönetim API'lerinin nasıl kullanılacağı gösterilmektedir. cURL kullanarak ACZ örneklerini oluşturur, listeler, alır ve silersiniz.

Bu eğitimde şunları öğreniyorsunuz:

  • Bir ACZ örneği oluşturun.
  • Bir veri bölümündeki tüm ACZ örneklerini listeleyin.
  • Belirli bir ACZ örneğinin ayrıntılarını alın.
  • ACZ örneğini silme.

Prerequisites

Tip

API'yi etkileşimli olarak keşfedin: konumundaki Swagger kullanıcı arabirimini https://{instance-name}.energy.azure.com/api/acz/v1/docskullanarak tam ACZ API belirtimini ve test uç noktalarını görüntüleyebilirsiniz. {instance-name} yerine Azure Data Manager for Energy örneği adını yazın.

Enerji örneği ayrıntıları için Azure Data Manager'ınızı alma

Bu ayrıntıları Azure portalındaenerji için Azure Veri Yöneticisi örneğinizden toplayın.

Başlamadan önce

Bu öğreticideki kod örnekleri, yer tutucu değerlerini {curly-braces} biçimde kullanır. Komutları çalıştırdığınızda bu yer tutucuları gerçek değerlerinizle değiştirin.

Tüm API çağrıları kimlik doğrulaması gerektirir. Bash ve PowerShell örnekleri, Azure CLI kullanarak satır içi belirteç oluşturmayı gösterir. Alternatif kimlik doğrulama yöntemleri için bkz. Kimlik doğrulama belirteci oluşturma.

ACZ örneği oluşturma

Bir veri bölümü için yeni bir ACZ örneği ayarlamak için ACZ API'sini oluşturun.

API

POST /api/acz/v1/aczs

Önemli noktalar

  • Her veri bölümü için en fazla üç ACZ instance'ı olabilir.
  • ACZ adı, bölüm içinde benzersiz olmalıdır.
  • Kullanıcı tarafından atanan yönetilen kimlik şu şekilde olmalıdır:
    • Azure Data Manager for Energy kaynağınıza atanır (bkz. Analitik Tüketim Bölgesini Etkinleştirme).
    • Hedef Azure Data Lake Storage 2. Nesil depolama hesabına Depolama Blobu Veri Katkıda Bulunanı rolü atandı.
  • Hiyerarşik ad alanı etkinleştirilmiş bir Data Lake Storage 2. Nesil depolama hesabı gereklidir.
# 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}"]
    }
  }'

Yer tutucuları değiştirin

Yer tutucu Description
{subscription-id} Enerji için Azure Data Manager örneğinizin yer aldığı abonelik kimliği.
{resource-group} Enerji için Azure Veri Yöneticisi örneğinizi içeren kaynak grubu.
{adme-instance-name} Azure Data Manager for Energy örneğinizin adı.
{base-url} Azure Data Manager for Energy örneğinizin URL’si (örneğin, myinstance.energy.azure.com).
{data-partition-id} Veri bölüm kimliğiniz (örneğin, opendes).
{acz-name} ACZ örneğinin görünen adı (örneğin my-acz-wells-and-logs, 1-100 karakter).
{acz-type} İsteğe bağlı: LATEST_VERSION (varsayılan) yalnızca en son sürümü dışarı aktarır ve ALL_VERSIONS tüm sürümleri dışarı aktarır.
{storage-resource-id} Hedef Data Lake Storage 2. Nesil depolama hesabının Azure kaynak kimliği (örneğin, /subscriptions/xxx.../storageAccounts/mystorageacct).
{base-path} İsteğe bağlı: ACZ çıkışı için depolama konumu (örneğin, acz-output veya acz-output/workbench). İlk bölüm konteyner adıdır; ACZ ise konteyner yoksa onu oluşturur. İlk segment geçerli bir konteyner adı olmalıdır. Adlandırma kuralları için Kapsayıcıları, blobları ve meta verileri adlandırma ve başvurma konusuna bakın. Kalan segmentler klasörlerdir. ACZ verileri <basePath>/<aczId>/ konumuna yazar. basePath öğesini atlarsanız, ACZ aczId adına bir kapsayıcı oluşturur ve verileri <aczId>/<aczId>/ konumuna yazar. Swagger arayüzü kullanıyorsanız, yer tutucu değeri stringdeğiştirin; aksi takdirde ACZ adında stringbir konteyner oluşturur.
allCatalogSync İsteğe bağlı (varsayılan: false). olarak trueayarlandığında, tüm katalog türlerini bölümden dışarı aktarır. Bölümün dışında belirtilirconfiguration. Yapılandırmada true, catalogKinds ve wellboreDDMSKinds, katalog verileri için yoksayıldığında.
{catalog-kinds} İsteğe bağlı: Senkronize edilecek OSDU® katalog tür dizeleri (örneğin, ["osdu:wks:master-data--Well:*"]). Eğer allCatalogSync ise true yoksayılır.
{wellbore-ddms-kinds} İsteğe bağlı (önizleme): Eşitlenecek Wellbore Domain Veri Yönetimi Service (DDMS) tür dizeleri (örneğin, ["osdu:wks:work-product-component--WellLog:*"]). Dosya indirme işlemleri yalnızca burada listelenen türlerde gerçekleşir.

Tip

Tüm katalog verilerini dışa aktarın: Veri bölümünüzdeki tüm katalog türlerini dışa aktarmak için "allCatalogSync": true öğesini (configuration bölümünün dışında) ayarlayın. Etkinleştirildiğinde, katalog verileri için yapılandırmadaki catalogKinds ve wellboreDDMSKinds dizileri dikkate alınmaz. Wellbore DDMS toplu dosya indirmeleri hala yalnızca içinde listelenen türlerde wellboreDDMSKindsgerçekleşir.

Aşağıdaki seçeneklerden en az birini sağlamanız gerekir:

  • Ayarla "allCatalogSync": true (dış yapılandırma).
  • Yapılandırmada en az bir tür deseni içeren bir catalogKinds dizi sağlayın.
  • Yapılandırmada en az bir tür deseni içeren bir wellboreDDMSKinds dizi sağlayın.

Örnek yanıt (201 Oluşturuldu)

{
  "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 örneğini oluşturduktan sonra, PROCESSING durumuyla geçmiş anlık görüntüsünü başlatır. Durumu denetlemek için GET ACZ API'sini kullanın.

ACZ örneklerini listeleme

Bir veri bölümündeki tüm ACZ örneklerini almak için ACZ'leri Listeleme API'sini kullanın.

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

Yer tutucuları değiştirin

Yer tutucu Description
{subscription-id} Enerji için Azure Data Manager örneğinizin yer aldığı abonelik kimliği.
{resource-group} Enerji için Azure Veri Yöneticisi örneğinizi içeren kaynak grubu.
{adme-instance-name} Azure Data Manager for Energy örneğinizin adı.
{base-url} Azure Data Manager for Energy örneğinizin URL’si (örneğin, myinstance.energy.azure.com).
{data-partition-id} Veri bölüm kimliğiniz (örneğin, opendes).

Örnek yanıt (200 Tamam)

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

Yanıt, herhangi bir durumdaki tüm ACZ örneklerini listeler: ACTIVE, FAILEDveya ACCESS_DENIED. Bu yanıt iki ACZ örneği gösterir: biri seçici katalog eşitlemesi için (allCatalogSync: false ile belirli türler için), diğeri ise tüm katalog türlerini dışa aktarmak için allCatalogSync: true kullanan bir örnektir.

ACZ ayrıntılarını alma

Belirli bir ACZ örneğinin ayrıntılarını almak için Get ACZ API'sini kullanın.

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

Yer tutucuları değiştirin

Yer tutucu Description
{subscription-id} Enerji için Azure Data Manager örneğinizin yer aldığı abonelik kimliği.
{resource-group} Enerji için Azure Veri Yöneticisi örneğinizi içeren kaynak grubu.
{adme-instance-name} Azure Data Manager for Energy örneğinizin adı.
{base-url} Azure Data Manager for Energy örneğinizin URL’si (örneğin, myinstance.energy.azure.com).
{data-partition-id} Veri bölüm kimliğiniz (örneğin, opendes).
{acz-id} Oluşturma veya Listeleme yanıtından ACZ tanımlayıcısı (örneğin, acz-abc123def456).

Örnek yanıt (200 Tamam)

{
  "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 provizyonunu izlemek için status ve historicalSnapshotStatus alanlarını denetleyin.

Yanıt ayrıca şunları içeriyor:

  • catalogSchemaVersion: osducatalog tablosunun şema sürümü. Yeni ACZ örnekleri, modifyUser ve modifyTime sütunlarını ekleyen 2. sürümü kullanır. Ayrıntılar için Analytics Consumption Zone concepts bölümüne bakın.
  • maintenance: ACZ'nin çalıştırdığı Delta tablosu bakım faaliyetlerinin durumu (OPTIMIZE_Z_ORDER ve VACUUM), son deneme süresi ve son başarılı çalışma süresi dahil. Dizi ilk bakım çalışmasına kadar boş kalır.

ACZ örneğini silme

ACZ yapılandırmasını kaldırmak için ACZ API'sini sil'i kullanın.

API

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

Warning

Bu silme eylemi geri alınamaz. Tüm ACZ yapılandırmasını kaldırır ve eşitlemeyi durdurur. Hedef Data Lake Storage 2. Nesil depolama hesabında zaten bulunan veriler bozulmadan kalır.

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

Yer tutucuları değiştirin

Yer tutucu Description
{subscription-id} Enerji için Azure Data Manager örneğinizin yer aldığı abonelik kimliği.
{resource-group} Enerji için Azure Veri Yöneticisi örneğinizi içeren kaynak grubu.
{adme-instance-name} Azure Data Manager for Energy örneğinizin adı.
{base-url} Azure Data Manager for Energy örneğinizin URL’si (örneğin, myinstance.energy.azure.com).
{data-partition-id} Veri bölüm kimliğiniz (örneğin, opendes).
{acz-id} Oluşturma veya Listeleme yanıtından ACZ tanımlayıcısı (örneğin, acz-abc123def456).

Örnek yanıt (204 İçerik Yok)

Başarılı bir silme işlemi, yanıt gövdesi olmadan HTTP 204 durum kodunu döndürür. Temizleme çalışırken ACZ durumu DELETING olarak değişir.

Hata yanıtları

ACZ API'leri aşağıdaki hata kodlarını döndürür.

HTTP durumu Description
400 Hatalı istek. Doğrulama hataları için istek gövdesini denetleyin.
401 Yetkisiz. Taşıyıcı belirteci eksik veya geçerli değil.
403 Yasaktır. Kullanıcı gerekli yetkilendirme grubuna ait değil.
404 Bulunamadı. Belirtilen ACZ kimliği mevcut değil.
422 Doğrulama başarısız oldu. İstek gövdesinde geçerli olmayan değerler var.
500 İç sunucu hatası. Bu hata devam ederse desteğe başvurun.

İlgili içerik

  • Son güncelleştirme: