Memahami dan menjalankan metode langsung dari IoT Hub

  • Artikel

IoT Hub memberi Anda kemampuan untuk memanggil metode langsung pada perangkat dari cloud. Metode langsung mewakili interaksi permintaan-balasan dengan perangkat yang sama dengan panggilan HTTP yang langsung berhasil atau gagal (setelah batas waktu yang ditentukan pengguna). Pendekatan ini berguna untuk skenario di mana tindakan langsung tergantung pada apakah perangkat mampu merespons.

Catatan

Fitur yang dijelaskan dalam artikel ini hanya tersedia di tingkat standar IoT Hub. Untuk informasi selengkapnya tentang tingkat IoT Hub dasar dan standar/gratis, lihat Memilih tingkat IoT Hub yang tepat untuk solusi Anda.

Setiap metode perangkat menargetkan satu perangkat. Jadwalkan pekerjaan di beberapa perangkat menunjukkan cara menyediakan cara untuk memanggil metode langsung di beberapa perangkat, dan menjadwalkan pemanggilan metode untuk perangkat yang terputus.

Siapa pun yang memiliki izin koneksi layanan di IoT Hub dapat memanggil metode di perangkat.

Metode langsung mengikuti pola permintaan-respons dan dimaksudkan untuk komunikasi yang memerlukan konfirmasi segera atas hasilnya. Misalnya, kontrol interaktif perangkat, seperti menyalakan kipas angin.

Lihat Panduan komunikasi cloud-ke-perangkat jika ragu antara menggunakan properti yang diinginkan, metode langsung, atau pesan cloud-ke-perangkat.

Siklus hidup metode

Metode langsung diimplementasikan pada perangkat dan mungkin memerlukan nol atau lebih input dalam payload metode untuk membuat instans dengan benar. Anda memanggil metode langsung melalui URI yang menghadap ke layanan ({iot hub}/twins/{device id}/methods/). Perangkat menerima metode langsung melalui topik MQTT khusus perangkat ($iothub/methods/POST/{method name}/) atau melalui tautan AMQP (properti aplikasi IoThub-methodname dan IoThub-status).

Catatan

Saat Anda memanggil metode langsung pada perangkat, nama dan nilai properti hanya dapat berisi alfanumerik US-ASCII yang dapat dicetak, kecuali yang ada dalam himpunan berikut: {'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}

Metode langsung bersifat sinkron dan berhasil atau gagal setelah periode waktu habis (default: 30 detik, dapat diatur antara 5 dan 300 detik). Metode langsung berguna dalam skenario interaktif di mana Anda ingin perangkat bertindak jika dan hanya jika perangkat online dan menerima perintah. Misalnya, menyalakan lampu dari telepon. Dalam skenario ini, Anda ingin melihat keberhasilan atau kegagalan langsung sehingga layanan cloud dapat menindaklanjuti hasilnya sesegera mungkin. Perangkat dapat mengembalikan beberapa isi pesan sebagai hasil dari metode tersebut, tetapi metode tersebut tidak diperlukan untuk melakukannya. Tidak ada jaminan pemesanan atau semantik konkurensi pada pemanggilan metode.

Metode langsung hanya HTTPS dari sisi cloud dan MQTT, AMQP, MQTT melalui WebSockets, atau AMQP melalui WebSockets dari sisi perangkat.

Payload untuk permintaan dan tanggapan metode adalah dokumen JSON hingga 128 KB.

Panggil metode langsung dari aplikasi back-end

Untuk memanggil metode langsung dari aplikasi back-end, gunakan REST API metode perangkat Invoke atau yang setara di salah satu SDK layanan IoT Hub.

Pemanggilan metode

Pemanggilan metode langsung pada perangkat adalah panggilan HTTPS yang terdiri dari item berikut:

  • URI permintaan khusus untuk perangkat bersama dengan versi API:

    https://fully-qualified-iothubname.azure-devices.net/twins/{deviceId}/methods?api-version=2021-04-12

  • Metode POSTING

  • Header yang berisi otorisasi, jenis konten, dan pengodean konten.

  • body JSON transparan dalam format berikut:

    {
    "connectTimeoutInSeconds": 200,
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}

Nilai yang diberikan sebagai responseTimeoutInSeconds dalam permintaan adalah jumlah waktu yang harus ditunggu oleh layanan IoT Hub untuk penyelesaian eksekusi metode langsung pada perangkat. Setel batas waktu ini setidaknya selama waktu eksekusi yang diharapkan dari metode langsung oleh perangkat. Jika batas waktu tidak disediakan, nilai default 30 detik digunakan. Nilai minimum dan maksimum untuk responseTimeoutInSeconds masing-masing adalah 5 dan 300 detik.

Nilai yang diberikan sebagai connectTimeoutInSeconds dalam permintaan adalah jumlah waktu setelah pemanggilan metode langsung yang harus ditunggu oleh layanan IoT Hub agar perangkat yang terputus terhubung online. Nilai defaultnya adalah 0, artinya perangkat harus sudah online saat memanggil metode langsung. Nilai maksimum untuk connectTimeoutInSeconds adalah 300 detik.

Contoh

Contoh ini akan memungkinkan Anda untuk secara aman memulai permintaan untuk memanggil Metode Langsung pada perangkat IoT yang terdaftar ke Azure IoT Hub.

Untuk memulai, gunakan ekstensi Microsoft Azure IoT untuk Azure CLI untuk membuat SharedAccessSignature.

az iot hub generate-sas-token -n <iothubName> --du <duration>

Selanjutnya, ganti header Otorisasi dengan SharedAccessSignature yang baru dibuat, lalu ubah parameter iothubName, deviceId, methodName, dan payload agar sesuai dengan penerapan Anda dalam contoh perintah curl di bawah.

curl -X POST \
  https://<iothubName>.azure-devices.net/twins/<deviceId>/methods?api-version=2021-04-12\
  -H 'Authorization: SharedAccessSignature sr=iothubname.azure-devices.net&sig=x&se=x&skn=iothubowner' \
  -H 'Content-Type: application/json' \
  -d '{
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}'

Jalankan perintah yang dimodifikasi untuk memanggil metode langsung yang ditentukan. Permintaan yang berhasil akan mengembalikan kode status HTTP 200.

Catatan

Contoh di atas menunjukkan pemanggilan metode langsung pada perangkat. Jika Anda ingin memanggil metode langsung dalam Modul IoT Edge, Anda perlu mengubah permintaan url seperti yang ditunjukkan di bawah ini:

https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12

Tanggapan

Aplikasi back-end menerima respons yang terdiri dari item berikut:

  • Kode status HTTP:

    • 200 menunjukkan keberhasilan eksekusi metode langsung;
    • 404 menunjukkan bahwa salah satu ID perangkat tidak valid, atau bahwa perangkat tidak online saat memanggil metode langsung dan untuk connectTimeoutInSeconds setelahnya (gunakan pesan kesalahan yang disertai untuk memahami akar penyebab);
    • 504 menunjukkan batas waktu gateway yang disebabkan oleh perangkat yang tidak menanggapi panggilan metode langsung dalam responseTimeoutInSeconds.

  • Header yang berisi ETag, ID permintaan, jenis konten, dan pengodean konten.

  • body JSON dalam format berikut:

    {
    "status" : 201,
    "payload" : {...}
}

    Baik status dan payload disediakan oleh perangkat dan digunakan untuk merespons dengan kode status dan metode respons.

Pemanggilan metode untuk modul IoT Edge

Memanggil metode langsung pada modul didukung oleh REST API metode modul panggil atau yang setara di salah satu SDK layanan IoT Hub.

moduleId diteruskan bersama dengan deviceId dalam URI permintaan saat menggunakan REST API atau sebagai parameter saat menggunakan SDK layanan. Contohnya:https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12 Isi permintaan dan respons mirip dengan metode langsung yang dipanggil pada perangkat.

Menangani metode langsung pada perangkat

Pada perangkat IoT, metode langsung dapat diterima melalui MQTT, AMQP, atau salah satu protokol ini melalui WebSocket. SDK perangkat IoT Hub membantu Anda menerima dan merespons metode langsung pada perangkat tanpa harus khawatir tentang detail protokol yang mendasar.

MQTT

Bagian berikut adalah untuk protokol MQTT. Untuk mempelajari selengkapnya tentang menggunakan protokol MQTT secara langsung dengan IoT Hub, lihat dukungan protokol MQTT.

Pemanggilan metode

Perangkat menerima permintaan metode langsung pada topik MQTT: $iothub/methods/POST/{method name}/?$rid={request id}. Namun, request id dihasilkan oleh IoT Hub dan tidak dapat diketahui sebelumnya, jadi berlangganan $iothub/methods/POST/# lalu filter pesan yang dikirim berdasarkan nama metode yang didukung oleh perangkat Anda. (Anda akan menggunakan request id untuk merespons.)

Badan yang diterima perangkat dalam format berikut:

{
    "input1": "someInput",
    "input2": "anotherInput"
}

Permintaan metode adalah QoS 0.

Tanggapan

Perangkat mengirimkan tanggapan ke $iothub/methods/res/{status}/?$rid={request id}, di mana:

  • Properti status adalah status eksekusi metode yang disediakan perangkat.

  • Properti $rid adalah ID permintaan dari pemanggilan metode yang diterima dari IoT Hub. ID permintaan adalah nilai berformat heksadesimal.

Tubuh diatur oleh perangkat dan dapat berupa status apa pun.

AMQP

Bagian berikut adalah untuk protokol AMQP. Untuk mempelajari selengkapnya tentang menggunakan protokol MQTT secara langsung dengan IoT Hub, lihat dukungan protokol MQTT.

Pemanggilan metode

Perangkat menerima permintaan metode langsung dengan membuat tautan terima di alamat amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Pesan AMQP tiba di tautan terima yang mewakili permintaan metode. Hal ini berisi bagian-bagian berikut:

  • Properti ID korelasi, yang berisi ID permintaan yang harus diteruskan kembali dengan respons metode yang sesuai.

  • Properti aplikasi bernama IoThub-methodname, yang berisi nama metode yang dipanggil.

  • Badan pesan AMQP yang berisi payload metode sebagai JSON.

Tanggapan

Perangkat membuat tautan pengiriman untuk mengembalikan respons metode pada alamat amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Respons metode dikembalikan pada tautan pengiriman dan disusun sebagai berikut:

  • Properti ID korelasi, yang berisi ID permintaan yang diteruskan dalam pesan permintaan metode.

  • Properti aplikasi bernama IoThub-status, yang berisi status metode yang disediakan pengguna.

  • Badan pesan AMQP yang berisi respons metode sebagai JSON.

Materi referensi tambahan

Topik referensi lain dalam panduan pengembang IoT Hub meliputi:

Langkah berikutnya

Sekarang Anda telah mempelajari cara menggunakan metode langsung, Anda mungkin tertarik dengan artikel panduan pengembang IoT Hub berikut:

Jika Anda ingin mencoba beberapa konsep yang dijelaskan dalam artikel ini, Anda mungkin tertarik dengan tutorial IoT Hub berikut: