Cara menggunakan REST API IoT Central untuk mengelola perangkat

Artikel
03/01/2024

IoT Central REST API memungkinkan Anda mengembangkan aplikasi klien yang terintegrasi dengan aplikasi IoT Central. Anda dapat menggunakan REST API untuk mengelola perangkat 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.

Tip

Anda dapat menggunakan Postman untuk mencoba panggilan REST API yang dijelaskan dalam artikel ini. Unduh koleksi IoT Central Postman dan impor ke Postman. Dalam koleksi, Anda harus mengatur variabel seperti subdomain aplikasi dan token admin.

Untuk mempelajari cara mengelola perangkat dengan menggunakan UI IoT Central, lihat Mengelola perangkat individual di aplikasi Azure IoT Central Anda.

REST API Perangkat

IoT Central REST API memungkinkan Anda:

Menambahkan perangkat ke aplikasi Anda
Memperbarui perangkat di aplikasi Anda
Mendapatkan daftar perangkat dalam aplikasi
Mendapatkan perangkat berdasarkan ID
Mendapatkan kredensial perangkat
Menghapus perangkat di aplikasi Anda
Memfilter daftar perangkat dalam aplikasi

Menambahkan perangkat

Gunakan permintaan berikut untuk membuat perangkat baru.

PUT https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Contoh berikut menunjukkan isi permintaan yang menambahkan perangkat untuk templat perangkat. Anda bisa mendapatkan template detail dari halaman templat perangkat di antarmuka pengguna aplikasi IoT Central.

{
  "displayName": "CheckoutThermostat",
  "template": "dtmi:contoso:Thermostat;1",
  "simulated": true,
  "enabled": true
}

Isi permintaan memiliki beberapa bidang yang diperlukan:

@displayName: Nama tampilan perangkat.
@enabled: Menyatakan bahwa objek ini adalah antarmuka.
@etag: ETag digunakan untuk mencegah konflik dalam pembaruan perangkat.
simulated: Apakah perangkat disimulasikan?
template : Definisi templat perangkat untuk perangkat.

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true
}

Mendapatkan perangkat

Gunakan permintaan berikut untuk mengambil detail perangkat dari aplikasi Anda:

GET https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Catatan

Anda bisa mendapatkan deviceId dari IoT Central Application UI dengan mengarahkan mouse ke perangkat.

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "id": "5jcwskdwbm",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
    "displayName": "Thermostat - 5jcwskdwbm",
    "simulated": false,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true
}

Tabel berikut ini memperlihatkan bagaimana nilai status untuk perangkat di UI memetakan ke nilai yang digunakan oleh REST API untuk berinteraksi dengan perangkat:

Status Perangkat UI	Catatan	Dapatkan REST API
Menunggu persetujuan	Opsi persetujuan otomatis dinonaktifkan di grup koneksi perangkat dan perangkat tidak ditambahkan melalui UI. Pengguna harus menyetujui perangkat secara manual melalui UI sebelum dapat digunakan.	`Provisioned: false` `Enabled: false`
Terdaftar	Perangkat disetujui secara otomatis atau manual.	`Provisioned: false` `Enabled: true`
Tersedia	Perangkat diprovisikan dan dapat terhubung ke aplikasi IoT Central Anda.	`Provisioned: true` `Enabled: true`
Terblokir	Perangkat tidak diizinkan untuk terhubung ke aplikasi IoT Central Anda. Anda dapat memblokir perangkat yang berada di salah satu status lainnya.	`Provisioned:` tergantung pada `Waiting for approval`/`Registered`/`Provisioned status` `Enabled: false`

Dapatkan kredensial perangkat

Gunakan permintaan berikut untuk mengambil kredensial perangkat dari aplikasi Anda:

GET https://{your app subdomain}/api/devices/{deviceId}/credentials?api-version=2022-07-31

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "idScope": "0ne003E64EF",
    "symmetricKey": {
        "primaryKey": "XUQvxGl6+Q1R0NKN5kOTmLOWsSKiuqs5N9unrjYCH4k=",
        "secondaryKey": "Qp/MTGHjn5MUTw4NVGhRfG+P+L1zh1gtAhO/KH8kn5c="
    }
}

Memperbarui perangkat

PATCH https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Isi permintaan sampel berikut mengubah bidang menjadi enabledfalse:

{
  "enabled": false
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": false
}

Menghapus perangkat

Gunakan permintaan berikut untuk menghapus perangkat:

DELETE https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Daftar perangkat

Gunakan permintaan berikut untuk mengambil daftar perangkat dari aplikasi Anda:

GET https://{your app subdomain}/api/devices?api-version=2022-07-31

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "CheckoutThermostat",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

Menetapkan manifes penyebaran

Jika Anda menambahkan perangkat IoT Edge, Anda dapat menggunakan API untuk menetapkan manifes penyebaran IoT Edge ke perangkat. Untuk mempelajari selengkapnya, lihat Menetapkan manifes penyebaran ke perangkat.

Menggunakan filter ODATA

Dalam versi pratinjau API (api-version=2022-10-31-preview), Anda dapat menggunakan filter ODATA untuk memfilter dan mengurutkan hasil yang dikembalikan oleh API perangkat daftar.

maxpagesize

Gunakan maxpagesize untuk mengatur ukuran hasil. Ukuran hasil maksimum yang dikembalikan adalah 100 dan ukuran defaultnya adalah 25.

Gunakan permintaan berikut untuk mengambil 10 perangkat teratas dari aplikasi Anda:

GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&maxpagesize=10

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "5jcwskdgdwbm",
            "etag": "eyJoZWdhhZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "RS40 Occupancy Sensor - 5jcwskdgdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "urn:modelDefinition:aqlyr1ulfku:tz5rut2pvx",
            "enabled": true
        },
        ...
    ],
    "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-07-31&%24top=1&%24skiptoken=%257B%2522token%2522%253A%2522%252BRID%253A%7EJWYqAOis7THQbBQAAAAAAg%253D%253D%2523RT%253A1%2523TRC%253A1%2523ISV%253A2%2523IEO%253A65551%2523QCF%253A4%2522%252C%2522range%2522%253A%257B%2522min%2522%253A%2522%2522%252C%2522max%2522%253A%252205C1D7F7591D44%2522%257D%257D"
}

Respons menyertakan nilai nextLink yang dapat Anda gunakan untuk mengambil halaman hasil berikutnya.

filter

Gunakan filter untuk membuat ekspresi yang memfilter daftar perangkat. Tabel berikut ini memperlihatkan operator perbandingan yang bisa Anda gunakan:

Operator Perbandingan	Simbol	Contoh
Sama dengan	eq	`id eq 'device1' and scopes eq 'redmond'`
Tidak Sama	ne	`Enabled ne true`
Kurang dari atau sama dengan	le	`id le '26whl7mure6'`
Kurang dari	lt	`id lt '26whl7mure6'`
Lebih besar atau sama dengan	ge	`id ge '26whl7mure6'`
Lebih dari	gt	`id gt '26whl7mure6'`

Tabel berikut ini memperlihatkan operator logika yang bisa Anda gunakan dalam ekspresi filter :

Operator Logika	Simbol	Contoh
AND	dan	`id eq 'device1' and enabled eq true`
ATAU	or	`id eq 'device1' or simulated eq false`

Saat ini, filter berfungsi dengan bidang perangkat berikut:

FieldName	Tipe	Deskripsi
`id`	string	ID Perangkat
`displayName`	string	Nama tampilan perangkat
`enabled`	Boolean	Status perangkat diaktifkan
`provisioned`	Boolean	Status yang disediakan perangkat
`simulated`	Boolean	Status simulasi perangkat
`template`	string	ID templat perangkat
`scopes`	string	ID organisasi

filter fungsi yang didukung:

Saat ini, satu-satunya fungsi filter yang didukung untuk daftar perangkat adalah contains fungsi :

filter=contains(displayName, 'device1')

Contoh berikut menunjukkan cara mengambil semua perangkat tempat nama tampilan berisi string thermostat:

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "thermostat1",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "thermostat2",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

urut berdasarkan

Gunakan orderby untuk mengurutkan hasilnya. Saat ini, orderby hanya memungkinkan Anda mengurutkan pada displayName. Secara default, orderby mengurutkan dalam urutan naik. Gunakan turunan untuk mengurutkan dalam urutan turun, misalnya:

orderby=displayName
orderby=displayName desc

Contoh berikut menunjukkan cara mengambil semua templat perangkat tempat hasilnya diurutkan menurut displayName :

GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&orderby=displayName

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "value": [
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "CheckoutThermostat",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

Anda juga dapat menggabungkan dua filter atau lebih.

Contoh berikut menunjukkan cara mengambil tiga perangkat teratas di mana nama tampilan berisi string Thermostat.

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'Thermostat')&maxpagesize=3

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "value": [
    {
      "id": "1fpwlahp0zp",
      "displayName": "Thermostat - 1fpwlahp0zp",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiYTRjZGQyMjQtZjIxMi00MTI4LTkyMTMtZjcwMTBlZDhkOWQ0In0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    },
    {
      "id": "1yg0zvpz9un",
      "displayName": "Thermostat - 1yg0zvpz9un",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiZGQ1YTY4MDUtYzQxNS00ZTMxLTgxM2ItNTRiYjdiYWQ1MWQ2In0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    },
    {
      "id": "20cp9l96znn",
      "displayName": "Thermostat - 20cp9l96znn",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiNGUzNWM4OTItNDBmZi00OTcyLWExYjUtM2I4ZjU5NGZkODBmIn0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    }
  ],
  "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-10-31-preview&filter=contains%28displayName%2C+%27Thermostat%27%29&maxpagesize=3&$skiptoken=aHR0cHM6Ly9pb3RjLXByb2QtbG4taW5ma3YteWRtLnZhdWx0LmF6dXJlLm5ldC9zZWNyZXRzL2FwaS1lbmMta2V5LzY0MzZkOTY2ZWRjMjRmMDQ5YWM1NmYzMzFhYzIyZjZi%3AgWMDkfdpzBF0eYiYCGRdGQ%3D%3D%3ATVTgi5YVv%2FBfCd7Oos6ayrCIy9CaSUVu2ULktGQoHZDlaN7uPUa1OIuW0MCqT3spVXlSRQ9wgNFXsvb6mXMT3WWapcDB4QPynkI%2FE1Z8k7s3OWiBW3EQpdtit3JTCbj8qRNFkA%3D%3D%3Aq63Js0HL7OCq%2BkTQ19veqA%3D%3D"
}

Grup perangkat

Anda dapat membuat grup perangkat di aplikasi IoT Central untuk memantau data agregat, untuk digunakan dengan pekerjaan, dan mengelola akses. Grup perangkat ditentukan oleh filter yang memilih perangkat untuk ditambahkan ke grup. Anda dapat membuat grup perangkat di portal IoT Central atau dengan menggunakan API.

Menambahkan grup perangkat

Gunakan permintaan berikut untuk membuat grup perangkat baru.

PUT https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

Saat membuat grup perangkat, Anda menentukan filter yang memilih perangkat untuk ditambahkan ke grup. filter Mengidentifikasi templat perangkat dan properti apa pun yang cocok. Contoh berikut membuat grup perangkat yang berisi semua perangkat yang terkait dengan templat "dtmi:modelDefinition:dtdlv2" di mana provisioned properti adalah true.

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Isi permintaan memiliki beberapa bidang yang diperlukan:

@displayName: Nama tampilan grup perangkat.
@filter: Kueri menentukan perangkat mana yang harus berada dalam grup ini.
@etag: ETag digunakan untuk mencegah konflik dalam pembaruan perangkat.
description: Ringkasan singkat grup perangkat.

Bidang organisasi hanya digunakan saat aplikasi memiliki hierarki organisasi yang ditentukan. Untuk mempelajari selengkapnya tentang organisasi, lihat Mengelola organisasi IoT Central.

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Mendapatkan grup perangkat

Gunakan permintaan berikut untuk mengambil detail grup perangkat dari aplikasi Anda:

GET https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

deviceGroupId - ID unik untuk grup perangkat.

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "475cad48-b7ff-4a09-b51e-1a9021385453",
  "displayName": "DeviceGroupEntry1",
  "description": "This is a default device group containing all the devices for this particular Device Template.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Memperbarui grup perangkat

PATCH https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

Isi permintaan sampel terlihat seperti contoh berikut yang memperbarui displayName grup perangkat:

{
  "displayName": "New group name"
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "group1",
  "displayName": "New group name",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Menghapus grup perangkat

Gunakan permintaan berikut untuk menghapus grup perangkat:

DELETE https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

Mencantumkan grup perangkat

Gunakan permintaan berikut untuk mengambil daftar grup perangkat dari aplikasi Anda:

GET https://{your app subdomain}/api/deviceGroups?api-version=2022-07-31

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "value": [
    {
      "id": "475cad48-b7ff-4a09-b51e-1a9021385453",
      "displayName": "DeviceGroupEntry1",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
      "organizations": [
        "seattle"
      ]
    },
    {
      "id": "c2d5ae1d-2cb7-4f58-bf44-5e816aba0a0e",
      "displayName": "DeviceGroupEntry2",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model1\"",
      "organizations": [
        "redmond"
      ]
    },
    {
      "id": "241ad72b-32aa-4216-aabe-91b240582c8d",
      "displayName": "DeviceGroupEntry3",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model2\" AND $simulated = true"
    },
    {
      "id": "group4",
      "displayName": "DeviceGroupEntry4",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model3\""
    }
  ]
}

Grup pendaftaran

Grup pendaftaran digunakan untuk mengelola opsi autentikasi perangkat di aplikasi IoT Central Anda. Untuk mempelajari selengkapnya, lihat Konsep autentikasi perangkat di IoT Central.

Untuk mempelajari cara membuat dan mengelola grup pendaftaran di UI, lihat Cara menyambungkan perangkat dengan sertifikat X.509 ke Aplikasi IoT Central.

Saat Anda membuat grup pendaftaran untuk perangkat yang menggunakan sertifikat X.509, Anda harus terlebih dahulu mengunggah sertifikat root atau menengah ke aplikasi IoT Central Anda.

Membuat sertifikat akar dan perangkat

Di bagian ini, Anda membuat sertifikat X.509 yang Anda butuhkan untuk menyambungkan perangkat ke IoT Central.

Peringatan

Cara pembuatan sertifikat X.509 ini hanya untuk pengujian. Untuk lingkungan produksi, Anda harus menggunakan mekanisme yang resmi dan aman untuk pembuatan sertifikat.

Navigasikan ke skrip generator sertifikat di Microsoft Azure IoT SDK untuk Node.js yang Anda unduh. Instal paket yang diperlukan:
```
cd azure-iot-sdk-node/provisioning/tools
npm install
```
Buat sertifikat root dan buat sertifikat perangkat dengan menjalankan skrip:
```
node create_test_cert.js root mytestrootcert
node create_test_cert.js device sample-device-01 mytestrootcert
```
Tip

ID perangkat dapat menggunakan huruf, angka, dan karakter -.

Perintah ini menghasilkan akar berikut dan sertifikat perangkat:

filename	konten
mytestrootcert_cert.pem	Bagian publik sertifikat X.509 akar
mytestrootcert_key.pem	Kunci privat untuk sertifikat X.509 akar
mytestrootcert_fullchain.pem	Seluruh rantai kunci untuk sertifikat X.509 akar.
mytestrootcert.pfx	File PFX untuk sertifikat X.509 akar.
sampleDevice01_cert.pem	Bagian publik sertifikat X.509 perangkat
sampleDevice01_key.pem	Kunci privat untuk sertifikat X.509 perangkat
sampleDevice01_fullchain.pem	Seluruh rantai kunci untuk sertifikat X.509 perangkat.
sampleDevice01.pfx	File PFX untuk sertifikat X.509 perangkat.

Catat lokasi file-file ini. Anda akan membutuhkannya nanti.

Hasilkan versi sertifikat akar yang dikodekan base-64

Di folder di komputer lokal Anda yang berisi sertifikat yang Anda buat, buat file yang disebut convert.js dan tambahkan konten JavaScript berikut:

const fs = require('fs')
const fileContents = fs.readFileSync(process.argv[2]).toString('base64');
console.log(fileContents);

Jalankan perintah berikut untuk menghasilkan versi enkode dasar-64 sertifikat:

node convert.js mytestrootcert_cert.pem

Catat versi sertifikat yang dikodekan base-64. Anda akan membutuhkannya nanti.

Menambahkan grup pendaftaran X.509

Gunakan permintaan berikut untuk membuat grup pendaftaran baru dengan myx509eg sebagai ID:

PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31

Contoh berikut menunjukkan isi permintaan yang menambahkan grup pendaftaran X.509 baru:

{
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "x509"
  }
}

Isi permintaan memiliki beberapa bidang yang diperlukan:

@displayName: Nama tampilan grup pendaftaran.
@enabled: Apakah perangkat yang menggunakan grup diizinkan untuk terhubung ke IoT Central.
@type: Jenis perangkat yang terhubung melalui grup, baik iot atau iotEdge.
attestation: Mekanisme pengesahan untuk grup pendaftaran, baik symmetricKey atau x509.

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "id": "myEnrollmentGroupId",
    "displayName": "My group",
    "enabled": true,
    "type": "iot",
    "attestation": {
        "type": "x509",
        "x509": {
            "signingCertificates": {}
        }
    },
    "etag": "IjdiMDcxZWQ5LTAwMDAtMDcwMC0wMDAwLTYzMWI3MWQ4MDAwMCI="
}

Menambahkan sertifikat X.509 ke grup pendaftaran

Gunakan permintaan berikut untuk mengatur sertifikat utama X.509 dari grup pendaftaran myx509eg:

PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

Gunakan permintaan ini untuk menambahkan sertifikat X.509 primer atau sekunder ke grup pendaftaran.

Contoh berikut menunjukkan isi permintaan yang menambahkan sertifikat X.509 ke grup pendaftaran:

{
  "verified": false,
  "certificate": "<base64-certificate>"
}

sertifikat - Versi dasar-64 sertifikat yang Anda catat sebelumnya.
terverifikasi - true jika Anda membuktikan bahwa sertifikat valid, false jika Anda perlu membuktikan validitas sertifikat.

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "verified": false,
  "info": {
    "sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
  },
  "etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
}

Membuat kode verifikasi untuk sertifikat X.509

Gunakan permintaan berikut untuk menghasilkan kode verifikasi untuk sertifikat X.509 primer atau sekunder dari grup pendaftaran.

Jika Anda mengatur verified ke false dalam permintaan sebelumnya, gunakan permintaan berikut untuk membuat kode verifikasi untuk sertifikat X.509 utama di myx509eg grup pendaftaran:

POST https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/generateVerificationCode?api-version=2022-07-31

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "verificationCode": "<certificate-verification-code>"
}

Catat kode verifikasi, Anda membutuhkannya di langkah berikutnya.

Hasilkan sertifikat verifikasi

Gunakan perintah berikut untuk membuat sertifikat verifikasi dari kode verifikasi di langkah sebelumnya:

node create_test_cert.js verification --ca mytestrootcert_cert.pem --key mytestrootcert_key.pem --nonce  {verification-code}

Jalankan perintah berikut untuk menghasilkan versi sertifikat yang dikodekan base-64:

node convert.js verification_cert.pem

Catat versi sertifikat yang dikodekan base-64. Anda akan membutuhkannya nanti.

Memverifikasi sertifikat X.509 dari grup pendaftaran

Gunakan permintaan berikut untuk memverifikasi sertifikat utama X.509 dari myx509eg grup pendaftaran dengan memberikan sertifikat dengan kode verifikasi yang ditandatangani:

POST PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/verify?api-version=2022-07-31

Contoh berikut menunjukkan isi permintaan yang memverifikasi sertifikat X.509:

{
  "certificate": "base64-verification-certificate"
}

Mendapatkan sertifikat X.509 dari grup pendaftaran

Gunakan permintaan berikut untuk mengambil detail sertifikat X.509 dari grup pendaftaran dari aplikasi Anda:

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

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "verified": true,
  "info": {
    "sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
  },
  "etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
}

Menghapus sertifikat X.509 dari grup pendaftaran

Gunakan permintaan berikut untuk menghapus sertifikat X.509 utama dari grup pendaftaran dengan ID myx509eg:

DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

Menambahkan grup pendaftaran kunci konten

Gunakan permintaan berikut untuk membuat grup pendaftaran baru dengan mysymmetric sebagai ID:

PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/mysymmetric?api-version=2022-07-31

Contoh berikut menunjukkan isi permintaan yang menambahkan grup pendaftaran baru:

{
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey"
  }
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "mysymmetric",
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

IoT Central menghasilkan kunci konten primer dan sekunder saat Anda melakukan panggilan API ini.

Mendapatkan grup pendaftaran

Gunakan permintaan berikut untuk mengambil detail grup pendaftaran dengan mysymmetric sebagai ID:

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

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "mysymmetric",
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

Memperbarui grup pendaftaran

Gunakan permintaan berikut untuk memperbarui grup pendaftaran.

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

Contoh berikut menunjukkan isi permintaan yang memperbarui nama tampilan grup pendaftaran:

{
  "displayName": "My new group name",
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "myEnrollmentGroupId",
  "displayName": "My new group name",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

Menghapus grup pendaftaran

Gunakan permintaan berikut untuk menghapus grup pendaftaran dengan ID myx509eg:

DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31

Mencantumkan grup pendaftaran

Gunakan permintaan berikut untuk mengambil daftar grup pendaftaran dari aplikasi Anda:

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

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "value": [
        {
            "id": "myEnrollmentGroupId",
            "displayName": "My group",
            "enabled": true,
            "type": "iot",
            "attestation": {
                "type": "symmetricKey",
                "symmetricKey": {
                    "primaryKey": "primaryKey",
                    "secondaryKey": "secondarykey"
                }
            },
            "etag": "IjZkMDc1YTgzLTAwMDAtMDcwMC0wMDAwLTYzMTc5ZjA4MDAwMCI="
        },
        {
            "id": "enrollmentGroupId2",
            "displayName": "My group",
            "enabled": true,
            "type": "iot",
            "attestation": {
                "type": "x509",
                "x509": {
                    "signingCertificates": {}
                }
            },
            "etag": "IjZkMDdjNjkyLTAwMDAtMDcwMC0wMDAwLTYzMTdhMDY1MDAwMCI="
        }
    ]
}

Share via

Cara menggunakan REST API IoT Central untuk mengelola perangkat

REST API Perangkat

Menambahkan perangkat

Mendapatkan perangkat

Dapatkan kredensial perangkat

Memperbarui perangkat

Menghapus perangkat

Daftar perangkat

Menetapkan manifes penyebaran

Menggunakan filter ODATA

maxpagesize

filter

urut berdasarkan

Grup perangkat

Menambahkan grup perangkat

Mendapatkan grup perangkat

Memperbarui grup perangkat

Menghapus grup perangkat

Mencantumkan grup perangkat

Grup pendaftaran

Membuat grup pendaftaran

Membuat sertifikat akar dan perangkat

Hasilkan versi sertifikat akar yang dikodekan base-64

Menambahkan grup pendaftaran X.509

Menambahkan sertifikat X.509 ke grup pendaftaran

Membuat kode verifikasi untuk sertifikat X.509

Hasilkan sertifikat verifikasi

Memverifikasi sertifikat X.509 dari grup pendaftaran

Mendapatkan sertifikat X.509 dari grup pendaftaran

Menghapus sertifikat X.509 dari grup pendaftaran

Menambahkan grup pendaftaran kunci konten

Mendapatkan grup pendaftaran

Memperbarui grup pendaftaran

Menghapus grup pendaftaran

Mencantumkan grup pendaftaran

Sumber Daya Tambahan: