Tutorial: Menggunakan REST API untuk mengelola aplikasi Azure IoT Central

Artikel
03/04/2024

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 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.

Postman

Dalam tutorial ini, Anda menggunakan Postman untuk melakukan panggilan REST API. Jika Anda lebih suka tidak mengunduh dan menginstal Postman, Anda dapat menggunakan versi online. Anda dapat menyelesaikan semua langkah dalam tutorial dengan menggunakan versi gratis Postman.

Tutorial ini menggunakan koleksi Postman yang telah ditentukan sebelumnya yang menyertakan beberapa skrip untuk membantu Anda menyelesaikan langkah-langkahnya.

Mengimpor koleksi Postman

Untuk mengimpor koleksi, buka Postman dan pilih Impor. Dalam dialog Impor, pilih Tautkan dan tempel di URL berikut, pilih Lanjutkan.

Ruang kerja Anda sekarang berisi koleksi tutorial IoT Central REST. Koleksi ini mencakup semua API yang Anda gunakan dalam tutorial.

Koleksi menggunakan variabel untuk membuat parameter panggilan REST API. Untuk melihat variabel, pilih di ... samping tutorial REST IoT Central dan pilih Edit. Lalu pilih Variabel. Banyak variabel diatur secara otomatis saat Anda melakukan panggilan API atau memiliki nilai prasetel.

Mengotorisasi REST API

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

Token pembawa yang mengotorisasi akses ke https://management.azure.com. Anda menggunakan token pembawa ini saat membuat dan menghapus dan aplikasi IoT Central. Aplikasi IoT Central adalah sumber daya Azure.
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.

Tetapkan nilai ke variabel berikut dalam koleksi Postman:

bearerToken: Jalankan perintah Azure CLI berikut untuk menghasilkan token pembawa yang mengotorisasi akses ke https://management.azure.com:
```
az login
az account get-access-token --resource https://management.azure.com
```
Tip

Anda mungkin perlu menjalankan az login bahkan jika Anda menggunakan Cloud Shell.

Salin nilai ke accessTokenkolom Nilai saat ini untuk bearerToken dalam variabel koleksi.
bearerTokenApp: 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.

Salin nilai ke accessTokenkolom Nilai saat ini untuk bearerTokenApp dalam variabel koleksi.
subscriptionId: ID langganan Anda disertakan dalam output dari dua perintah sebelumnya. Salin nilai ke subscriptionkolom Nilai saat ini untuk subscriptionId dalam variabel koleksi.

Screenshot that shows the variables set manually in the Postman collection.

Pastikan untuk menyimpan perubahan ke koleksi Postman.

Catatan

Token pembawa kedaluwarsa setelah satu jam.

Membuat aplikasi

Gunakan permintaan sarana kontrol untuk membuat dan mengelola aplikasi pusat IoT. Gunakan permintaan PUT berikut untuk membuat aplikasi yang Anda gunakan dalam tutorial ini. Permintaan menggunakan token pembawa untuk mengotorisasi dan menghasilkan nama aplikasi acak.

Di Postman, buka koleksi tutorial IoT Central REST, dan pilih permintaan Buat aplikasi pusat IoT.
Pilih Kirim.
Periksa permintaan berhasil. Jika gagal, verifikasi bahwa Anda memasukkan nilai variabel bearerToken dan subscriptionId di koleksi Postman.
Pilih Visualisasikan untuk melihat URL aplikasi IoT Central baru Anda. Catat URL ini, Anda membutuhkannya nanti dalam tutorial ini.

Screenshot that shows the Visualize tab with the application URL in Postman.

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:

Di Postman, buka koleksi tutorial IoT Central REST, dan pilih permintaan Buat token operator.
Pilih Kirim.
Di Postman, buka koleksi tutorial IoT Central REST, dan pilih permintaan Buat token admin.
Pilih Kirim.

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

Catatan

Skrip di Postman secara otomatis menambahkan token API ini ke daftar variabel koleksi untuk Anda.

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:

Di Postman, buka koleksi tutorial IoT Central REST, dan pilih tambahkan permintaan perangkat .
Pilih Kirim. Sebagai respons, perhatikan bahwa perangkat tidak disediakan.
Di Postman, buka koleksi tutorial IoT Central REST, dan pilih permintaan Dapatkan kredensial perangkat.
Pilih Kirim.
Tab Visualisasi memperlihatkannilai Cakupan ID dan Kunci primer yang perlu disambungkan perangkat.

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 Koneksi > kode QR. Biarkan halaman ini tetap terbuka hingga perangkat tersambung.

Screenshot that shows the QR code you use to connect the device.

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:

Di Postman, buka koleksi tutorial IoT Central REST, dan pilih permintaan Dapatkan perangkat .
Pilih Kirim. Sebagai respons, perhatikan bahwa perangkat sekarang disediakan. IoT Central juga menetapkan templat perangkat ke perangkat berdasarkan ID model yang dikirim oleh perangkat.

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

Di Postman, buka koleksi tutorial IoT Central REST, dan pilih permintaan Daftar templat perangkat.
Pilih Kirim.

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:

Di Postman, buka koleksi tutorial IoT Central REST, dan pilih permintaan Jalankan kueri .
Pilih Kirim.

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

Di Postman, buka koleksi tutorial IoT Central REST, dan pilih permintaan Dapatkan properti dari komponen .
Pilih Kirim.

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:

Di Postman, buka koleksi tutorial IoT Central REST, dan pilih permintaan perintah Panggil.
Pilih Kirim.

Ekspor telemetri

Anda dapat menggunakan REST API untuk mengonfigurasi dan mengelola aplikasi IoT Central Anda. Langkah-langkah berikut menunjukkan cara mengonfigurasi ekspor data untuk mengirim nilai telemetri ke webhook. Untuk menyederhanakan penyiapan, artikel ini menggunakan webhook RequestBin sebagai tujuan. RequestBin adalah layanan non-Microsoft.

Untuk membuat titik akhir pengujian Anda untuk tujuan ekspor data:

Navigasi ke RequestBin.
Pilih Buat RequestBin.
Masuk dengan salah satu metode yang tersedia.
Salin URL titik akhir RequestBin Anda.
Di Postman, buka koleksi tutorial IoT Central REST dan navigasikan ke variabel koleksi.
Tempelkan URL titik akhir RequestBin Anda ke kolom Nilai saat ini untuk webHookURL dalam variabel koleksi.
Simpan perubahan.

Untuk mengonfigurasi tujuan ekspor di aplikasi IoT Central Anda dengan menggunakan REST API:

Di Postman, buka koleksi tutorial IoT Central REST, dan pilih permintaan Buat tujuan ekspor webhook.
Pilih Kirim.

Untuk mengonfigurasi definisi ekspor di aplikasi IoT Central Anda dengan menggunakan REST API:

Di Postman, buka koleksi tutorial IoT Central REST, dan pilih permintaan Buat definisi ekspor telemetri.
Pilih Kirim. Perhatikan bahwa status Belum dimulai.

Mungkin perlu waktu beberapa menit agar ekspor dimulai. Untuk memeriksa status ekspor dengan menggunakan REST API:

Di Postman, buka koleksi tutorial IoT Central REST, dan pilih permintaan Dapatkan ekspor berdasarkan ID.
Pilih Kirim. Ketika status sehat, IoT Central mengirim telemetri ke webhook Anda.

Aplikasi di ponsel cerdas Anda tidak mengirim telemetri kecuali layar menyala dan aplikasi IoT Plug and Play terlihat.

Saat aplikasi ponsel cerdas Anda mengirim telemetri, navigasikan ke RequestBin Anda untuk melihat telemetri yang diekspor.

Membersihkan sumber daya

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

Di Postman, buka koleksi tutorial IoT Central REST, dan pilih permintaan Hapus aplikasi pusat IoT.
Pilih Kirim.

Tip

Permintaan ini menggunakan token pembawa yang Anda buat di awal tutorial. Token pembawa kedaluwarsa setelah jam. Anda mungkin perlu membuat token pembawa baru yang mengotorisasi akses ke https://apps.azureiotcentral.com.

Langkah berikutnya

Jika Anda lebih suka melanjutkan melalui rangkaian tutorial IoT Central dan mempelajari lebih lanjut tentang membangun solusi IoT Central, lihat:

Membuat templat perangkat gateway