Tutorial: Menggunakan REST API untuk mengelola aplikasi Azure IoT Central

Tutorial ini menunjukkan kepada Anda cara menggunakan REST API Azure IoT Central untuk membuat dan berinteraksi dengan aplikasi IoT Central. Tutorial ini menggunakan REST API untuk menyelesaikan banyak langkah yang Anda selesaikan dengan menggunakan UI Web di mulai cepat. Langkah-langkah ini termasuk menggunakan aplikasi di ponsel cerdas Anda sebagai perangkat IoT yang terhubung ke IoT Central.

Dalam tutorial ini, Anda akan mempelajari cara:

Prasyarat

Untuk menyelesaikan langkah-langkah dalam tutorial ini, Anda perlu:

• Langganan Azure aktif. Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.

• Smartphone Android atau iOS tempat Anda dapat menginstal aplikasi gratis dari salah satu toko aplikasi resmi.

Azure CLI

Anda menggunakan Azure CLI untuk melakukan panggilan REST API dan menghasilkan token pembawa yang digunakan beberapa REST API untuk otorisasi.

• Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai Cepat untuk Bash di Azure Cloud Shell.

  

• Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal Azure CLI. Jika Anda menjalankan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat Cara menjalankan Azure CLI di kontainer Docker.

  • Jika Anda menggunakan instalasi lokal, masuk ke Azure CLI dengan menggunakan perintah login az. Untuk menyelesaikan proses autentikasi, ikuti langkah-langkah yang ditampilkan di terminal Anda. Untuk opsi masuk lainnya, lihat Masuk dengan Azure CLI.

  • Saat Anda diminta, instal ekstensi Azure CLI pada penggunaan pertama. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan ekstensi dengan Azure CLI.

  • Jalankan versi az untuk menemukan versi dan pustaka dependen yang diinstal. Untuk meningkatkan ke versi terbaru, jalankan peningkatan az.

Mengotorisasi REST API

Sebelum dapat menggunakan REST API, Anda harus mengonfigurasi otorisasi. Panggilan REST API dalam tutorial ini menggunakan salah satu dari dua jenis otorisasi:

• Token pembawa yang mengotorisasi akses ke https://apps.azureiotcentral.com. Anda menggunakan token pembawa ini untuk membuat token API di aplikasi IoT Central.
• Token API administrator dan operator yang mengotorisasi akses ke kemampuan di aplikasi IoT Central Anda. Anda menggunakan token ini untuk sebagian besar panggilan API dalam tutorial ini. Token ini hanya mengotorisasi akses ke satu aplikasi IoT Central tertentu.

Jalankan perintah Azure CLI berikut untuk menghasilkan token pembawa yang mengotorisasi akses ke https://apps.azureiotcentral.com:

az account get-access-token --resource https://apps.azureiotcentral.com

Catat nilainya accessToken , Anda menggunakannya nanti dalam tutorial.

Buat grup sumber daya

Gunakan Azure cli untuk membuat grup sumber daya yang berisi aplikasi IoT Central yang Anda buat dalam tutorial ini:

az group create --name iot-central-rest-tutorial --location eastus

Buat aplikasi IoT Central

Gunakan perintah berikut untuk menghasilkan aplikasi IoT Central dengan nama acak untuk digunakan dalam tutorial ini:

appName=app-rest-$(date +%s)

az iot central app create --name $appName --resource-group iot-central-rest-tutorial --subdomain $appName

Catat nama aplikasi, Anda menggunakannya nanti dalam tutorial ini.

Membuat token API

Gunakan permintaan data plane berikut untuk membuat token API aplikasi di aplikasi IoT Central Anda. Beberapa permintaan dalam tutorial ini memerlukan token API dengan izin administrator, tetapi sebagian besar dapat menggunakan izin operator:

Untuk membuat token operator yang dipanggil operator-token dengan menggunakan Azure CLI, jalankan perintah berikut. PERAN GUID adalah ID peran operator di semua aplikasi IoT Central:

appName=<the app name generated previously>
bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/operator-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ae2c9854-393b-4f97-8c42-479d70ce626e"}]}'

Catat token operator yang dikembalikan perintah, Anda menggunakannya nanti dalam tutorial. Token terlihat seperti SharedAccessSignature sr=2....

Untuk membuat token admin yang dipanggil admin-token dengan menggunakan Azure CLI, jalankan perintah berikut. PERAN GUID adalah ID peran admin di semua aplikasi IoT Central:

$appName=<the app name generated previously>
$bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/admin-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"}]}'

Catat token admin yang dikembalikan perintah, Anda menggunakannya nanti dalam tutorial. Token terlihat seperti SharedAccessSignature sr=2....

Jika Anda ingin melihat token ini di aplikasi IoT central Anda, buka aplikasi dan navigasikan ke token API Izin Keamanan.> >

Mendaftarkan perangkat

Anda harus mendaftarkan perangkat dengan IoT Central sebelum dapat tersambung. Gunakan permintaan berikut untuk mendaftarkan perangkat Anda di aplikasi Anda dan mengambil kredensial perangkat. Permintaan pertama membuat perangkat dengan telepon-001 sebagai ID perangkat:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"displayName": "My phone app","simulated": false,"enabled": true}'

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/credentials?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Catat idScope nilai dan primaryKey yang dikembalikan perintah, Anda menggunakannya nanti dalam tutorial.

Memprovisikan dan menyambungkan perangkat

Untuk menghindari kebutuhan untuk memasukkan kredensial perangkat secara manual di smartphone Anda, Anda dapat menggunakan kode QR yang dihasilkan oleh IoT central. Kode QR mengodekan ID perangkat, cakupan ID, kunci primer. Untuk menampilkan kode QR:

1. Buka aplikasi IoT central Anda dengan menggunakan URL aplikasi yang Anda catat sebelumnya.
2. Di aplikasi IoT Central Anda, navigasikan ke Perangkat > Aplikasi > ponsel saya Sambungkan > kode QR. Biarkan halaman ini tetap terbuka hingga perangkat tersambung.

Untuk menyederhanakan penyiapan, artikel ini menggunakan aplikasi smartphone IoT Plug and Play sebagai perangkat IoT. Aplikasi ini mengirim telemetri yang dikumpulkan dari sensor smartphone, menanggapi perintah yang dipanggil dari IoT Central, dan melaporkan nilai properti ke IoT Central.

Pasang aplikasi di smartphone Anda dari salah satu app store:

Untuk menyambungkan aplikasi IoT Plug and Play ke aplikasi Iot Central Anda:

1. Buka aplikasi IoT PnP di ponsel cerdas Anda.

2. Pada halaman selamat datang, pilih Pindai kode QR. Arahkan kamera smartphone ke kode QR. Kemudian tunggu beberapa detik saat koneksi dibuat.

3. Pada halaman telemetri di aplikasi, Anda dapat melihat data yang dikirim aplikasi ke IoT Central. Pada halaman log, Anda dapat melihat perangkat tersambung dan beberapa pesan inisialisasi.

Untuk memverifikasi perangkat sekarang disediakan, Anda dapat menggunakan REST API:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Catat nilai yang template dikembalikan perintah, Anda menggunakannya nanti dalam tutorial.

Anda dapat menggunakan REST API untuk mengelola templat perangkat dalam aplikasi. Misalnya, untuk melihat templat perangkat dalam aplikasi:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Mengkueri dan mengontrol perangkat

Anda dapat menggunakan REST API untuk mengkueri telemetri dari perangkat Anda. Permintaan berikut mengembalikan data akselerometer dari semua perangkat yang berbagi ID templat perangkat tertentu:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
deviceTemplateId=<the device template Id you made a note of previously>
q1='{"query": "SELECT $id as ID, $ts as timestamp, sensors.accelerometer FROM '
q2=' WHERE WITHIN_WINDOW(P1D) AND sensors.accelerometer <> NULL"}'
query="$q1 $deviceTemplateId $q2"
echo $query

az rest --method post --uri https://$appName.azureiotcentral.com/api/query?api-version=2022-10-31-preview --headers Authorization="$operatorToken" "Content-Type=application/json" --body "$query"

Anda dapat menggunakan REST API untuk membaca dan mengatur properti perangkat. Permintaan berikut mengembalikan semua nilai properti dari komponen Info Perangkat yang diterapkan perangkat:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/components/device_info/properties?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Anda dapat menggunakan REST API untuk memanggil perintah perangkat. Permintaan berikut memanggil perintah yang menyalakan lampu smartphone Anda dua kali selama tiga detik. Agar perintah berjalan, layar smartphone Anda harus aktif dengan aplikasi IoT Plug and Play terlihat:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method post --uri https://$appName.azureiotcentral.com/api/devices/phone-001/commands/lightOn?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"duration": 3, "delay": 1, "pulses": 2}'

Membersihkan sumber daya

Jika Anda telah selesai dengan aplikasi IoT Central yang Anda gunakan dalam tutorial ini, Anda dapat menghapusnya:

appName=<the app name generated previously>

az iot central app delete --name $appName --resource-group iot-central-rest-tutorial