Bagikan melalui

Memahami dan memanggil metode langsung dari IoT Hub

Metode langsung IoT Hub memungkinkan Anda memanggil panggilan dari jarak jauh pada perangkat dari cloud. Metode langsung mengikuti pola respons permintaan dan dimaksudkan untuk komunikasi yang memerlukan konfirmasi segera tentang hasilnya. Misalnya, kontrol interaktif perangkat, seperti menyalakan kipas angin. Fungsionalitas ini berguna untuk skenario di mana tindakan langsung berbeda tergantung pada apakah perangkat dapat merespons.

Nota

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 dan ukuran IoT Hub yang tepat untuk solusi Anda.

Setiap metode perangkat menargetkan satu perangkat. Jika Anda ingin memanggil metode langsung di beberapa perangkat, atau menjadwalkan metode untuk perangkat yang terputus, lihat Menjadwalkan pekerjaan di beberapa perangkat.

Siapa pun dengan izin koneksi layanan di IoT Hub dapat memanggil metode pada perangkat.

Lihat panduan komunikasi Cloud-ke-perangkat apabila Anda ragu antara menggunakan properti yang diinginkan, metode langsung, atau pesan dari cloud-ke-perangkat.

Siklus hidup metode

Metode langsung diimplementasikan pada perangkat dan mungkin memerlukan nol atau lebih input dalam payload metode untuk menginstansiasi dengan benar. Anda memanggil metode langsung melalui URI yang ditujukan untuk 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).

Nota

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

Metode langsung adalah sinkron dan dapat berhasil atau gagal setelah periode habis waktu (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 ponsel. Dalam skenario ini, Anda ingin melihat keberhasilan atau kegagalan segera sehingga layanan cloud dapat bertindak berdasarkan hasilnya sesegera mungkin. Perangkat mungkin mengembalikan beberapa isi pesan sebagai hasil dari metode, tetapi itu tidak wajib. Tidak ada jaminan urutan atau semantik keserentakan apa pun pada panggilan metode.

Metode langsung untuk sisi cloud menggunakan hanya HTTPS, dan untuk sisi perangkat menggunakan MQTT, AMQP, MQTT melalui WebSocket, atau AMQP melalui WebSocket.

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

Memanggil metode langsung dari aplikasi back-end

Untuk memanggil metode langsung dari aplikasi back-end, gunakan Device - Invoke Method REST API 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 POST

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

  • Isi JSON transparan dalam format berikut:

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

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

Nilai yang disediakan seperti connectTimeoutInSeconds dalam permintaan adalah jumlah waktu pada saat pemanggilan metode langsung yang harus ditunggu layanan IoT Hub agar perangkat yang terputus dapat terhubung kembali ke jaringan. Nilai defaultnya adalah 0, artinya perangkat harus sudah online saat memanggil metode langsung. Nilai maksimum untuk connectTimeoutInSeconds adalah 300 detik.

Contoh

Contoh ini memulai permintaan untuk memanggil metode langsung pada perangkat IoT yang terdaftar ke hub Azure IoT.

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, lalu ubah parameter iothubName, deviceId, methodName, dan payload agar sesuai dengan implementasi Anda dalam perintah contoh curl berikut.

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 mengembalikan kode status HTTP 200.

Nota

Contoh sebelumnya menunjukkan pemanggilan metode langsung pada perangkat. Jika Anda ingin memanggil metode langsung dalam modul IoT Edge, ubah permintaan URL untuk disertakan /modules/<moduleName> seperti yang ditunjukkan dalam contoh berikut:

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 ID perangkat tidak valid, atau bahwa perangkat tidak online setelah pemanggilan metode langsung dan untuk connectTimeoutInSeconds selanjutnya (gunakan pesan kesalahan yang disertai untuk memahami akar penyebabnya);
    • 504 menunjukkan batas waktu gateway yang disebabkan oleh perangkat yang tidak merespons panggilan metode langsung dalam responseTimeoutInSeconds.

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

  • Isi JSON dalam format berikut:

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

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

Pemanggilan metode pada modul IoT Edge

Untuk memanggil metode langsung pada modul, gunakan Modul - Panggil Metode REST API 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 sebuah metode langsung pada sebuah 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 langsung dengan IoT Hub, lihat Berkomunikasi dengan hub IoT menggunakan protokol MQTT.

Pemanggilan metode

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

Isi yang diterima perangkat dalam format berikut:

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

Permintaan metode adalah QoS 0.

Tanggapan

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

  • Properti status adalah status eksekusi metode yang disediakan perangkat.

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

Perangkat mengatur isi dan dapat berupa status apa pun.

AMQP

Bagian berikut adalah untuk protokol AMQP. Untuk mempelajari selengkapnya tentang menggunakan protokol AMQP langsung dengan IoT Hub, lihat Berkomunikasi dengan hub IoT Anda dengan menggunakan Protokol AMQP.

Pemanggilan metode

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

Pesan AMQP tiba di tautan terima yang mewakili permintaan metode. Ini berisi 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 sedang dipanggil.

  • Isi pesan AMQP yang memuat payload metode dalam bentuk 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.

  • Isi pesan AMQP yang berisi respons dari metode dalam bentuk JSON.

Langkah berikutnya

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

  • Last updated on