Gunakan REST API untuk membuat dan mengelola aplikasi IoT Central
Anda dapat menggunakan REST API sarana kontrol untuk membuat dan mengelola aplikasi IoT Central. Anda juga dapat menggunakan REST API untuk:
- Tambahkan identitas terkelola ke aplikasi Anda.
- Mengelola dasbor di aplikasi Anda
Untuk menggunakan API ini, Anda memerlukan token pembawa untuk management.azure.com sumber daya. Untuk mendapatkan token pembawa, Anda dapat menggunakan Azure CLI:
az account get-access-token --resource https://management.azure.com
Untuk mempelajari cara mengelola aplikasi IoT Central dengan menggunakan UI IoT Central, lihat Membuat aplikasi IoT Central.
Daftar aplikasi Anda
Untuk mendapatkan daftar aplikasi IoT Central dalam langganan:
GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
Untuk mendapatkan daftar aplikasi IoT Central dalam langganan:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
Anda dapat mengambil rincian aplikasi individual:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps/{applicationName}?api-version=2021-06-01
Buat aplikasi IoT Central
Untuk membuat aplikasi IoT Central dengan sistem yang diberikan identitas terkelola:
PUT https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
Payload berikut menunjukkan konfigurasi untuk aplikasi baru, termasuk identitas terkelola:
{
"location": "eastus",
"sku": {
"name": "ST2"
},
"properties": {
"displayName": "Contoso IoT Central App",
"subdomain": "my-iot-central-app",
"template": "iotc-pnp-preview@1.0.0"
},
"identity": {
"type": "SystemAssigned"
}
}
Memodifikasi aplikasi IoT Central
Anda dapat memodifikasi aplikasi IoT Central yang ada. Contoh berikut menunjukkan cara mengubah nama tampilan dan mengaktifkan identitas terkelola yang ditetapkan sistem:
PATCH https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
Gunakan payload berikut untuk mengubah nama tampilan dan mengaktifkan identitas terkelola yang ditetapkan sistem:
{
"properties": {
"displayName": "Contoso IoT Central App"
},
"identity": {
"type": "SystemAssigned"
}
}
Catatan
Anda hanya dapat menambahkan identitas terkelola ke aplikasi IoT Central yang dibuat di suatu wilayah. Semua aplikasi baru dibuat di suatu wilayah.
Hapus aplikasi IoT Central
Untuk menghapus aplikasi IoT Central, gunakan:
DELETE https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
Dashboard
Anda dapat membuat dasbor yang terkait dengan organisasi tertentu. Dasbor organisasi hanya dapat dilihat oleh pengguna yang memiliki akses ke organisasi yang dikaitkan dengan dasbor. Hanya pengguna dalam peran yang memiliki izin dasbor organisasi yang dapat membuat, mengedit, dan menghapus dasbor organisasi.
Semua pengguna dapat membuat dasbor pribadi, hanya terlihat oleh diri mereka sendiri. Pengguna dapat beralih dari dasbor organisasi dan pribadi.
Catatan
Membuat dasbor pribadi menggunakan API saat ini tidak didukung.
Untuk mempelajari cara mengelola dasbor dengan menggunakan UI IoT Central, lihat Cara mengelola dasbor.
REST API Dasbor
IoT Central REST API memungkinkan Anda:
- Menambahkan dasbor ke aplikasi Anda
- Memperbarui dasbor di aplikasi Anda
- Mendapatkan daftar dasbor dalam aplikasi
- Mendapatkan dasbor menurut ID
- Menghapus dasbor di aplikasi Anda
Menambahkan dasbor
Gunakan permintaan berikut untuk membuat dasbor.
PUT https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
dashboardId- Pengidentifikasi DTMI unik untuk dasbor.
Isi permintaan memiliki beberapa bidang yang diperlukan:
@displayName: Nama tampilan dasbor.@favorite: Apakah dasbor dalam daftar favorit?group: ID grup perangkat.Tile: Konfigurasi yang menentukan objek petak peta, termasuk tata letak, nama tampilan, dan konfigurasi.
Petak peta memiliki beberapa bidang yang diperlukan:
| Nama | Deskripsi |
|---|---|
displayName |
Tampilkan nama petak peta |
height |
Tinggi petak peta |
width |
Lebar petak peta |
x |
Posisi horizontal petak peta |
y |
Posisi vertikal petak peta |
Dimensi dan lokasi petak peta keduanya menggunakan unit bilangan bulat. Petak peta sekecil mungkin memiliki tinggi dan lebar satu.
Anda dapat mengonfigurasi objek petak untuk menampilkan beberapa jenis data. Artikel ini menyertakan contoh petak peta yang memperlihatkan bagan garis, markdown, dan nilai terakhir yang diketahui. Untuk mempelajari selengkapnya tentang berbagai jenis petak peta yang bisa Anda tambahkan ke dasbor, lihat Jenis petak peta.
Petak diagram garis
Plot satu atau beberapa nilai telemetri agregat untuk satu atau beberapa perangkat selama periode waktu tertentu. Misalnya, Anda dapat menampilkan diagram garis untuk melihat suhu dan tekanan rata-rata satu atau beberapa perangkat selama satu jam terakhir.
Petak peta bagan garis memiliki konfigurasi berikut:
| Nama | Deskripsi |
|---|---|
capabilities |
Menentukan nilai agregat telemetri yang akan ditampilkan. |
devices |
Daftar perangkat yang akan ditampilkan. |
format |
Konfigurasi format bagan seperti sumbu yang akan digunakan. |
group |
ID grup perangkat yang akan ditampilkan. |
queryRange |
Rentang waktu dan resolusi yang akan ditampilkan. |
type |
lineChart |
Petak peta markdown
Petak peta yang dapat diklik yang menampilkan teks judul dan deskripsi yang diformat dalam Markdown. URL dapat berupa tautan relatif ke halaman lain dalam aplikasi, atau tautan absolut ke situs eksternal. Petak peta markdown memiliki konfigurasi berikut:
| Nama | Deskripsi |
|---|---|
description |
String markdown untuk dirender di dalam petak peta. |
href |
Tautan yang akan dikunjungi saat petak peta dipilih. |
image |
Gambar yang dikodekan base64 untuk ditampilkan. |
type |
markdown |
Petak peta nilai terakhir yang diketahui
Tampilkan nilai telemetri terbaru untuk satu atau beberapa perangkat. Misalnya, Anda dapat menggunakan petak peta ini untuk menampilkan nilai suhu, tekanan, dan kelembapan terbaru untuk satu atau beberapa perangkat.
Petak peta nilai terakhir yang diketahui (LKV) memiliki konfigurasi berikut:
| Nama | Deskripsi |
|---|---|
capabilities |
Menentukan telemetri yang akan ditampilkan. |
devices |
Daftar perangkat yang akan ditampilkan. |
format |
Konfigurasi format petak peta LKV seperti ukuran teks pembungkus kata. |
group |
ID grup perangkat yang akan ditampilkan. |
showTrend |
Perlihatkan perbedaan antara nilai terakhir yang diketahui dan nilai sebelumnya. |
type |
lkv |
Contoh berikut menunjukkan isi permintaan yang menambahkan dasbor baru dengan bagan garis, markdown, dan petak peta nilai terakhir yang diketahui. Petak peta LKV dan bagan garis adalah 2x2 petak peta. Petak peta markdown adalah 1x1 petak peta. Petak peta disusun di baris atas dasbor:
{
"displayName": "My Dashboard ",
"tiles": [
{
"displayName": "LKV Temperature",
"configuration": {
"type": "lkv",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"group": "0fb6cf08-f03c-4987-93f6-72103e9f6100",
"devices": [
"3xksbkqm8r",
"1ak6jtz2m5q",
"h4ow04mv3d"
],
"format": {
"abbreviateValue": false,
"wordWrap": false,
"textSize": 14
}
},
"x": 0,
"y": 0,
"width": 2,
"height": 2
},
{
"displayName": "Documentation",
"configuration": {
"type": "markdown",
"description": "Comprehensive help articles and links to more support.",
"href": "https://aka.ms/iotcentral-pnp-docs",
"image": "4d6c6373-0220-4191-be2e-d58ca2a289e1"
},
"x": 2,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Average temperature",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"devices": [
"3xksbkqm8r",
"1ak6jtz2m5q",
"h4ow04mv3d"
],
"group": "0fb6cf08-f03c-4987-93f6-72103e9f6100",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 3,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "My Dashboard",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
Menambahkan konfigurasi akun penyimpanan unggahan file
Gunakan permintaan berikut untuk membuat konfigurasi akun penyimpanan blob unggahan file di aplikasi IoT Central Anda:
PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
Isi permintaan memiliki bidang berikut:
account: Nama akun penyimpanan tempat mengunggah file.connectionString: string koneksi untuk menyambungkan ke akun penyimpanan.container: Nama kontainer di dalam akun penyimpanan. Contoh berikut menggunakan namafileuploads.etag: ETag untuk mencegah konflik dengan beberapa unggahansasTtl: Standar durasi ISO 8601, Jumlah waktu permintaan perangkat untuk mengunggah file valid sebelum kedaluwarsa.
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "fileuploads",
"sasTtl": "PT1H"
}
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "fileuploads",
"sasTtl": "PT1H",
"state": "pending",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
Mendapatkan konfigurasi akun penyimpanan unggahan file
Gunakan permintaan berikut untuk mengambil detail konfigurasi akun penyimpanan blob unggahan file di aplikasi IoT Central Anda:
GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "yourContainerName",
"state": "succeeded",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
Memperbarui konfigurasi akun penyimpanan unggahan file
Gunakan permintaan berikut untuk memperbarui akun penyimpanan blob unggahan file string koneksi di aplikasi IoT Central Anda:
PATCH https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
{
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/"
}
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "yourContainerName",
"sasTtl": "PT1H",
"state": "succeeded",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
Menghapus konfigurasi akun penyimpanan unggahan file
Gunakan permintaan berikut untuk menghapus konfigurasi akun penyimpanan:
DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
Mendapatkan dasbor
Gunakan permintaan berikut untuk mengambil detail dasbor dengan menggunakan ID dasbor.
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "My Dashboard",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
Memperbarui dasbor
PATCH https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Contoh berikut menunjukkan isi permintaan yang memperbarui nama tampilan dasbor dan menambahkan dasbor ke daftar favorit:
{
"displayName": "New Dashboard Name",
"favorite": true
}
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "New Dashboard Name",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 5,
"height": 5
}
],
"favorite": true
}
Menghapus dasbor
Gunakan permintaan berikut untuk menghapus dasbor dengan menggunakan ID dasbor:
DELETE https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Daftar dasbor
Gunakan permintaan berikut untuk mengambil daftar dasbor dari aplikasi Anda:
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards?api-version=2022-10-31-preview
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"value": [
{
"id": "dtmi:kkfvwa2xi:p7pyt5x3o",
"displayName": "Dashboard",
"personal": false,
"tiles": [
{
"displayName": "Device templates",
"configuration": {
"type": "markdown",
"description": "Get started by adding your first device.",
"href": "/device-templates/new/devicetemplates",
"image": "f5ba1b00-1d24-4781-869b-6f954df48736"
},
"x": 1,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Quick start demo",
"configuration": {
"type": "markdown",
"description": "Learn how to use Azure IoT Central in minutes.",
"href": "https://aka.ms/iotcentral-pnp-video",
"image": "9eb01d71-491a-44e5-8fac-7af3bc9f9acd"
},
"x": 2,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Tutorials",
"configuration": {
"type": "markdown",
"description": "Step-by-step articles teach you how to create apps and devices.",
"href": "https://aka.ms/iotcentral-pnp-tutorials",
"image": "7d9fc12c-d46e-41c6-885f-0a67c619366e"
},
"x": 3,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Documentation",
"configuration": {
"type": "markdown",
"description": "Comprehensive help articles and links to more support.",
"href": "https://aka.ms/iotcentral-pnp-docs",
"image": "4d6c6373-0220-4191-be2e-d58ca2a289e1"
},
"x": 4,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "IoT Central Image",
"configuration": {
"type": "image",
"format": {
"backgroundColor": "#FFFFFF",
"fitImage": true,
"showTitle": false,
"textColor": "#FFFFFF",
"textSize": 0,
"textSizeUnit": "px"
},
"image": ""
},
"x": 0,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Contoso Image",
"configuration": {
"type": "image",
"format": {
"backgroundColor": "#FFFFFF",
"fitImage": true,
"showTitle": false,
"textColor": "#FFFFFF",
"textSize": 0,
"textSizeUnit": "px"
},
"image": "c9ac5af4-f38e-4cd3-886a-e0cb107f391c"
},
"x": 0,
"y": 1,
"width": 5,
"height": 3
},
{
"displayName": "Available Memory",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
]
}