Veri dışarı aktarımlarını yönetmek için IoT Central REST API kullanma

Makale
07/25/2023

IoT Central REST API, IoT Central uygulamalarıyla tümleşen istemci uygulamaları geliştirmenize olanak tanır. IoT Central uygulamanızda veri dışarı aktarmaları oluşturmak ve yönetmek için REST API'yi kullanabilirsiniz.

Her IoT Central REST API çağrısı bir yetkilendirme üst bilgisi gerektirir. Daha fazla bilgi edinmek için bkz. IoT Central REST API çağrılarının kimliğini doğrulama ve yetkilendirme.

IoT Central REST API başvuru belgeleri için bkz. Azure IoT Central REST API başvurusu.

İpucu

Postman'i kullanarak bu makalede açıklanan REST API çağrılarını deneyebilirsiniz. IoT Central Postman koleksiyonunu indirin ve Postman'a aktarın. Koleksiyonda, uygulama alt etki alanınız ve yönetici belirteciniz gibi değişkenleri ayarlamanız gerekir.

IoT Central kullanıcı arabirimini kullanarak veri dışarı aktarmayı yönetmeyi öğrenmek için bkz . IoT verilerini Blob Depolama'ya aktarma.

Veri dışarı aktarma

Telemetri, özellik değişiklikleri, cihaz bağlantı olayları, cihaz yaşam döngüsü olayları ve cihaz şablonu yaşam döngüsü olaylarını Azure Event Hubs, Azure Service Bus, Azure Blob Depolama ve web kancası uç noktaları gibi hedeflere akışla aktarmak için IoT Central veri dışarı aktarma özelliğini kullanabilirsiniz.

Her veri dışarı aktarma tanımı bir veya daha fazla hedefe veri gönderebilir. Dışarı aktarma tanımını oluşturmadan önce hedef tanımları oluşturun.

Hedef oluşturma veya güncelleştirme

Hedef tanımı oluşturmak veya güncelleştirmek için aşağıdaki isteği kullanın:

PUT https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

destinationId hedef için benzersiz bir kimliktir.

Aşağıdaki örnekte blob depolama hedefi oluşturan bir istek gövdesi gösterilmektedir:

{
  "displayName": "Blob Storage Destination",
  "type": "blobstorage@v1",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
  "containerName": "central-data"
}

İstek gövdesinde bazı gerekli alanlar vardır:

displayName: Hedefin görünen adı.
type: Hedef nesnenin türü. Bunlardan biri: blobstorage@v1, dataexplorer@v1, eventhubs@v1, servicebusqueue@v1, , servicebustopic@v1. webhook@v1
connectionString: Hedef kaynağa erişmek için bağlantı dizesi.
containerName: Blob depolama hedefi için verilerin yazılması gereken kapsayıcının adı.

Bu isteğin yanıtı aşağıdaki örneğe benzer:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Kimliğine göre hedef alma

Uygulamanızdan bir hedefin ayrıntılarını almak için aşağıdaki isteği kullanın:

GET https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Bu isteğin yanıtı aşağıdaki örneğe benzer:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Hedefleri listeleme

Uygulamanızdan hedeflerin listesini almak için aşağıdaki isteği kullanın:

GET https://{your app subdomain}/api/dataExport/destinations?api-version=2022-10-31-preview

Bu isteğin yanıtı aşağıdaki örneğe benzer:

{
    "value": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
            "displayName": "Blob Storage Destination",
            "type": "blobstorage@v1",
            "authorization": {
                "type": "connectionString",
                "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
                "containerName": "central-data"
            },
            "status": "waiting"
        },
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9",
            "displayName": "Webhook destination",
            "type": "webhook@v1",
            "url": "https://eofnjsh68jdytan.m.pipedream.net",
            "headerCustomizations": {},
            "status": "error"
        }
    ]
}

Hedefe düzeltme eki uygulama

PATCH https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Dışarı aktarma için artımlı güncelleştirme gerçekleştirmek için bu çağrıyı kullanabilirsiniz. Örnek istek gövdesi, hedefi güncelleştiren aşağıdaki örneğe connectionString benzer:

{
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net"
}

Bu isteğin yanıtı aşağıdaki örneğe benzer:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Hedefi silme

Hedefi silmek için aşağıdaki isteği kullanın:

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Dışarı aktarma tanımı oluşturma veya güncelleştirme

Veri dışarı aktarma tanımı oluşturmak veya güncelleştirmek için aşağıdaki isteği kullanın:

PUT https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

Aşağıdaki örnekte, cihaz telemetrisi için dışarı aktarma tanımı oluşturan bir istek gövdesi gösterilmektedir:

{
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150"
        }
    ]
}

İstek gövdesinde bazı gerekli alanlar vardır:

displayName: Dışarı aktarmanın görünen adı.
enabled: Dışarı aktarma işleminin veri göndermesini başlatmak/durdurmak için geçiş yapar.
source: Dışarı aktaracak verilerin türü.
destinations: Dışarı aktarma işleminin veri göndermesi gereken hedeflerin listesi. Hedef kimlikler uygulamada zaten mevcut olmalıdır.

Dışarı aktarma işlemine daha fazla ayrıntı eklemek için kullanabileceğiniz bazı isteğe bağlı alanlar vardır.

enrichments: Gönderilen her iletiye eklenecek ek bilgi parçaları. Veriler, anahtar/değer çiftleri kümesi olarak temsil edilir; burada anahtar, çıkış iletisinde görünecek zenginleştirmenin adıdır ve değer gönderilecek verileri tanımlar.
filter: Kaynaktan hangi olayların dışarı aktarılması gerektiğini tanımlayan sorgu.

Bu isteğin yanıtı aşağıdaki örneğe benzer:

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "starting"
}

Zenginleştirmeler

Dışarı aktarmaya ekleyebileceğiniz üç zenginleştirme türü vardır: özel dizeler, sistem özellikleri ve özel özellikler:

Aşağıdaki örnekte, giden iletiye özel bir dize eklemek için düğümün nasıl kullanılacağı enrichments gösterilmektedir:

"enrichments": {
  "My custom string": {
    "value": "My value"
  },
  //...
}

Aşağıdaki örnekte, giden iletiye sistem özelliği eklemek için düğümün nasıl kullanılacağı enrichments gösterilmektedir:

"enrichments": {
  "Device template": {
    "path": "$templateDisplayName"
  },
  //...
}

Aşağıdaki sistem özelliklerini ekleyebilirsiniz:

Özellik	Açıklama
`$enabled`	Cihaz etkin mi?
`$displayName`	Cihaz adı.
`$templateDisplayName`	Cihaz şablonu adı.
`$organizations`	Cihazın ait olduğu kuruluşlar.
`$provisioned`	Cihaz sağlandı mı?
`$simulated`	Cihaz simülasyonu yapılmış mı?

Aşağıdaki örnekte, giden iletiye özel bir özellik eklemek için düğümün nasıl kullanılacağı enrichments gösterilmektedir. Özel özellikler, cihazın ilişkili olduğu cihaz şablonunda tanımlanan özelliklerdir:

"enrichments": {
  "Device model": {
    "target": "dtmi:azure:DeviceManagement:DeviceInformation;1",
    "path": "model"
  },
  //...
}

Filtreler

Dışarı aktarılan iletileri telemetri veya özellik değerlerine göre filtreleyebilirsiniz.

Aşağıdaki örnekte, alanın yalnızca ivmeölçer-X telemetri değerinin filter 0'dan büyük olduğu iletileri dışarı aktarmak için nasıl kullanılacağı gösterilmektedir:

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 WHERE accelerometerX > 0",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

Aşağıdaki örnekte, yalnızca telemetri değerinin filter özelliğinden targetTemperature büyük olduğu temperature iletileri dışarı aktarmak için alanının nasıl kullanılacağı gösterilmektedir:

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 AS A, dtmi:contoso:Thermostat;1 WHERE A.temperature > targetTemperature",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

Kimliğine göre dışarı aktarma alma

Uygulamanızdan dışarı aktarma tanımının ayrıntılarını almak için aşağıdaki isteği kullanın:

GET https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

Bu isteğin yanıtı aşağıdaki örneğe benzer:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage Destination",
    "type": "blobstorage@v1",
    "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
    "containerName": "central-data",
    "status": "waiting"
}

Dışarı aktarma tanımlarını listeleme

Uygulamanızdan dışarı aktarma tanımlarının listesini almak için aşağıdaki isteği kullanın:

GET https://{your app subdomain}/api/dataExport/exports?api-version=2022-10-31-preview

Bu isteğin yanıtı aşağıdaki örneğe benzer:

{
  "value": [
    {
      "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "starting"
    },
    {
      "id": "802894c4-33bc-4f1e-ad64-e886f315cece",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "healthy"
    }
  ]
}

Dışarı aktarma tanımına düzeltme eki uygulama

PATCH https://{your app subdomain}/dataExport/exports/{exportId}?api-version=2022-10-31-preview

Dışarı aktarma için artımlı güncelleştirme gerçekleştirmek için bu çağrıyı kullanabilirsiniz. Örnek istek gövdesi, 'yi dışarı aktarmaya güncelleştiren aşağıdaki örneğe enrichments benzer:

{
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    }
}

Bu isteğin yanıtı aşağıdaki örneğe benzer:

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "healthy"
}

Dışarı aktarma tanımını silme

Dışarı aktarma tanımını silmek için aşağıdaki isteği kullanın:

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Sonraki adımlar

Rest API ile veri dışarı aktarmayı yönetmeyi öğrendiğinize göre, bir sonraki adım ioT Central REST API'sini kullanarak cihaz şablonlarını yönetme adımıdır.

Veri dışarı aktarımlarını yönetmek için IoT Central REST API kullanma

Veri dışarı aktarma

Hedef oluşturma veya güncelleştirme

Kimliğine göre hedef alma

Hedefleri listeleme

Hedefe düzeltme eki uygulama

Hedefi silme

Dışarı aktarma tanımı oluşturma veya güncelleştirme

Zenginleştirmeler

Filtreler

Kimliğine göre dışarı aktarma alma

Dışarı aktarma tanımlarını listeleme

Dışarı aktarma tanımına düzeltme eki uygulama

Dışarı aktarma tanımını silme

Sonraki adımlar

Ek kaynaklar