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:
- Otorisasi REST API.
- Membuat aplikasi IoT Central.
- Tambahkan perangkat ke aplikasi Anda.
- Mengkueri dan mengontrol perangkat.
- Siapkan ekspor data.
- Menghapus aplikasi.
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
Tip
Jika Anda memulai instans baru shell Anda, jalankan az login
lagi.
Catat nilainya accessToken
, Anda menggunakannya nanti dalam tutorial.
Catatan
Token pembawa kedaluwarsa setelah satu jam. Jika kedaluwarsa, jalankan perintah yang sama untuk menghasilkan token pembawa baru.
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:
- Buka aplikasi IoT central Anda dengan menggunakan URL aplikasi yang Anda catat sebelumnya.
- 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:
Buka aplikasi IoT PnP di ponsel cerdas Anda.
Pada halaman selamat datang, pilih Pindai kode QR. Arahkan kamera smartphone ke kode QR. Kemudian tunggu beberapa detik saat koneksi dibuat.
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