Gunakan REST API untuk membuat dan mengelola aplikasi IoT Central

Artikel
24/06/2024

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:

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:

HTTP

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01

Untuk mendapatkan daftar aplikasi IoT Central dalam langganan:

HTTP

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01

Anda dapat mengambil rincian aplikasi individual:

HTTP

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:

HTTP

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:

JSON

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

HTTP

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:

JSON

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

HTTP

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.

HTTP

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:

JSON

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

JSON

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

HTTP

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 nama fileuploads.
etag: ETag untuk mencegah konflik dengan beberapa unggahan
sasTtl: Standar durasi ISO 8601, Jumlah waktu permintaan perangkat untuk mengunggah file valid sebelum kedaluwarsa.

JSON

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

JSON

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

HTTP

GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

JSON

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

HTTP

PATCH https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

JSON

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

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

JSON


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

HTTP

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.

HTTP

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:

JSON

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

HTTP

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:

JSON


{
    "displayName": "New Dashboard Name",
    "favorite": true
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

JSON

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

HTTP

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:

HTTP

GET https://{your app subdomain}.azureiotcentral.com/api/dashboards?api-version=2022-10-31-preview

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

JSON

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

Sumber Daya Tambahan:

Dokumentasi

Mengelola dan memantau IoT Central - Azure IoT Central

Artikel ini menjelaskan cara membuat, mengelola, dan memantau aplikasi IoT Central Anda dan mengaktifkan identitas terkelola.
Mengelola perangkat satu per satu di aplikasi Anda - Azure IoT Central

Pelajari cara mengelola perangkat satu per satu di aplikasi Azure IoT Central Anda. Pantau, kelola, buat, hapus, dan perbarui perangkat.
Memigrasikan perangkat dari Azure IoT Central ke Azure IoT Hub - Azure IoT Central

Menjelaskan cara menggunakan alat migrasi untuk memigrasikan perangkat yang saat ini tersambung ke aplikasi Azure IoT Central ke hub Azure IoT.
Cara menggunakan REST API IoT Central untuk mengelola perangkat - Azure IoT Central

Pelajari cara menggunakan REST API IoT Central untuk menambahkan, memodifikasi, menghapus, dan mengelola perangkat dalam aplikasi.
Mengelola organisasi dengan REST API di Azure IoT Central - Azure IoT Central

Cara menggunakan IoT Central REST API untuk mengelola organisasi dalam aplikasi. Organisasi memungkinkan Anda mengelola akses ke sumber daya aplikasi.
Membuat dan menjalankan pekerjaan di aplikasi Azure IoT Central Anda - Azure IoT Central

Pekerjaan Azure IoT Central memungkinkan kemampuan manajemen perangkat massal, seperti memperbarui properti atau menjalankan perintah.
Mengautentikasi panggilan REST API di Azure IoT Central - Azure IoT Central

Cara mengautentikasi dan mengotorisasi panggilan IoT Central REST API dengan menggunakan token pembawa atau token IoT Central API.

Pelatihan

Jalur pembelajaran

Use advance techniques in canvas apps to perform custom updates and optimization - Training

Use advance techniques in canvas apps to perform custom updates and optimization

Sertifikasi

Bersertifikat Microsoft: Azure Developer Associate - Certifications

Bangun solusi end-to-end di Microsoft Azure untuk membuat Azure Functions, menerapkan dan mengelola aplikasi web, mengembangkan solusi yang menggunakan penyimpanan Azure, dan banyak lagi.

Bagikan melalui

Gunakan REST API untuk membuat dan mengelola aplikasi IoT Central

Daftar aplikasi Anda

Buat aplikasi IoT Central

Memodifikasi aplikasi IoT Central

Hapus aplikasi IoT Central

Dashboard

REST API Dasbor

Menambahkan dasbor

Petak diagram garis

Petak peta markdown

Petak peta nilai terakhir yang diketahui

Menambahkan konfigurasi akun penyimpanan unggahan file

Mendapatkan konfigurasi akun penyimpanan unggahan file

Memperbarui konfigurasi akun penyimpanan unggahan file

Menghapus konfigurasi akun penyimpanan unggahan file

Mendapatkan dasbor

Memperbarui dasbor

Menghapus dasbor

Daftar dasbor

Saran dan Komentar

Sumber Daya Tambahan: