Bagikan melalui

Cara menggunakan IoT Central REST API untuk mengelola ekspor data

IoT Central REST API memungkinkan Anda mengembangkan aplikasi klien yang terintegrasi dengan aplikasi IoT Central. Anda dapat menggunakan REST API untuk membuat dan mengelola ekspor data di aplikasi IoT Central Anda.

Setiap panggilan IoT Central REST API memerlukan header otorisasi. Untuk mempelajari selengkapnya, lihat Cara mengautentikasi dan mengotorisasi panggilan IoT Central REST API.

Untuk dokumentasi referensi untuk IoT Central REST API, lihat Referensi IoT Central REST API.

Untuk mempelajari cara mengelola ekspor data dengan menggunakan UI IoT Central, lihat Mengekspor data IoT ke Blob Storage.

Ekspor Data

Anda dapat menggunakan fitur ekspor data IoT Central untuk melakukan streaming telemetri, perubahan properti, aktivitas konektivitas perangkat, aktivitas siklus hidup perangkat, dan aktivitas siklus hidup template perangkat ke tujuan seperti Azure Event Hubs, Azure Service Bus, Azure Blob Storage, dan titik akhir webhook.

Setiap definisi ekspor data dapat mengirim data ke satu atau beberapa tujuan. Buat definisi tujuan sebelum Anda membuat definisi ekspor.

Buat atau perbarui tujuan

Gunakan permintaan berikut untuk membuat atau memperbarui definisi tujuan:

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

destinationId adalah ID unik untuk tujuan.

Contoh berikut menunjukkan isi permintaan yang membuat tujuan penyimpanan blob:

{
  "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data"
    }
}

Isi permintaan memiliki beberapa bidang yang diperlukan:

  • displayName: Menampilkan nama tujuan.
  • type: Jenis objek tujuan. Salah satu dari: blobstorage@v1, , dataexplorer@v1eventhubs@v1, servicebusqueue@v1, servicebustopic@v1, webhook@v1.
  • authorization: Detail otorisasi untuk tujuan. Jenis otorisasi yang didukung adalah systemAssignedManagedIdentity dan connectionString.

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Dapatkan tujuan dengan ID

Gunakan permintaan berikut untuk mengambil detail tujuan dari aplikasi Anda:

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

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Daftar tujuan

Gunakan permintaan berikut untuk mengambil daftar tujuan dari aplikasi Anda:

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

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "value": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
            "displayName": "Blob Storage Destination",
            "type": "blobstorage@v1",
            "authorization": {
              "type": "systemAssignedManagedIdentity",
              "endpointUri": "https://yourapplication.blob.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"
        }
    ]
}

Menambal tujuan

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

Anda dapat menggunakan panggilan ini untuk melakukan pembaruan inkremental ke ekspor. Isi permintaan sampel terlihat seperti contoh berikut yang memperbarui containerName tujuan:

{
  "containerName": "central-data-analysis"
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data-analysis"
    },
    "status": "waiting"
}

Hapus tujuan

Gunakan permintaan berikut untuk menghapus tujuan:

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

Buat atau perbarui definisi ekspor

Gunakan permintaan berikut untuk membuat atau memperbarui definisi ekspor data:

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

Contoh berikut menunjukkan isi permintaan yang membuat definisi ekspor untuk telemetri perangkat:

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

Isi permintaan memiliki beberapa bidang yang diperlukan:

  • displayName: Nama tampilan ekspor.
  • enabled: Beralih untuk memulai/menghentikan ekspor dari pengiriman data.
  • source: Jenis data yang akan diekspor.
  • destinations: Daftar tujuan pengiriman data ekspor. ID tujuan harus sudah ada di aplikasi.

Ada beberapa bidang opsional yang dapat Anda gunakan untuk menambahkan lebih banyak detail ke ekspor.

  • enrichments: Potongan informasi tambahan untuk disertakan dengan setiap pesan yang dikirim. Data direpresentasikan sebagai sekumpulan pasangan kunci/nilai, di mana kuncinya adalah nama pengayaan untuk muncul dalam pesan output dan nilai mengidentifikasi data yang akan dikirim.
  • filter: Kueri yang menentukan peristiwa mana dari sumber yang harus diekspor.

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

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

Pengayaan

Ada tiga jenis pengayaan yang dapat Anda tambahkan ke ekspor: string kustom, properti sistem, dan properti kustom:

Contoh berikut menunjukkan cara menggunakan simpul enrichments untuk menambahkan string kustom ke pesan keluar:

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

Contoh berikut menunjukkan cara menggunakan simpul enrichments untuk menambahkan properti sistem ke pesan keluar:

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

Anda bisa menambahkan properti sistem berikut:

Properti Deskripsi
$enabled Apakah perangkat diaktifkan?
$displayName Nama perangkat.
$templateDisplayName Nama templat perangkat.
$organizations Organisasi tempat perangkat berada.
$provisioned Apakah perangkat disediakan?
$simulated Apakah perangkat disimulasikan?

Contoh berikut menunjukkan cara menggunakan simpul enrichments untuk menambahkan properti kustom ke pesan keluar. Properti kustom adalah properti yang ditentukan dalam templat perangkat yang terkait dengan perangkat:

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

Filter

Anda dapat memfilter pesan yang diekspor berdasarkan nilai telemetri atau properti.

Contoh berikut menunjukkan cara menggunakan filter bidang untuk mengekspor hanya pesan di mana nilai telemetri akselerometer-X lebih besar dari 0:

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

Contoh berikut menunjukkan cara menggunakan filter bidang untuk mengekspor hanya pesan di mana temperature nilai telemetri lebih besar dari targetTemperature properti :

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

Dapatkan ekspor dengan ID

Gunakan permintaan berikut untuk mengambil detail definisi ekspor dari aplikasi Anda:

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

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

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

Buat daftar definisi ekspor

Gunakan permintaan berikut untuk mengambil daftar definisi ekspor dari aplikasi Anda:

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

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

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

Menambal definisi ekspor

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

Anda dapat menggunakan panggilan ini untuk melakukan pembaruan inkremental ke ekspor. Isi permintaan sampel terlihat seperti contoh berikut yang memperbarui enrichments ke ekspor:

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

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

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

Hapus definisi ekspor

Gunakan permintaan berikut untuk menghapus definisi ekspor:

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

Langkah berikutnya

Sekarang setelah Anda mempelajari cara mengelola ekspor data dengan REST API, langkah berikutnya yang disarankan adalah Cara menggunakan IoT Central REST API untuk mengelola template perangkat.