Mengirim dan menerima pesan cloud-ke-perangkat
Azure IoT Hub adalah layanan terkelola penuh yang memungkinkan komunikasi dua arah, termasuk pesan cloud-to-device (C2D) dari solusi kembali ke jutaan perangkat.
Artikel ini menjelaskan cara menggunakan Azure IoT SDK untuk membangun jenis aplikasi berikut:
Aplikasi perangkat yang menerima dan menangani pesan cloud-ke-perangkat dari antrean olahpesan IoT Hub.
Aplikasi back end yang mengirim pesan cloud-ke-perangkat ke satu perangkat melalui antrean olahpesan IoT Hub.
Artikel ini dimaksudkan untuk melengkapi sampel SDK yang dapat dijalankan yang dirujuk dari dalam artikel ini.
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.
Gambaran Umum
Agar aplikasi perangkat menerima pesan cloud-ke-perangkat, aplikasi harus tersambung ke IoT Hub lalu menyiapkan penanganan pesan untuk memproses pesan masuk. SDK perangkat Azure IoT Hub menyediakan kelas dan metode yang dapat digunakan perangkat untuk menerima dan menangani pesan dari layanan. Artikel ini membahas elemen kunci dari aplikasi perangkat apa pun yang menerima pesan, termasuk:
- Mendeklarasikan objek klien perangkat
- Menyambungkan ke Azure IoT Hub
- Mengambil pesan dari antrean pesan IoT Hub
- Memproses pesan dan mengirim pengakuan kembali ke IoT Hub
- Mengonfigurasi kebijakan percobaan kembali pesan penerimaan
Agar aplikasi back end mengirim pesan cloud-ke-perangkat, aplikasi harus terhubung ke IoT Hub dan mengirim pesan melalui antrean pesan IoT Hub. SDK layanan Azure IoT Hub menyediakan kelas dan metode yang dapat digunakan aplikasi untuk mengirim pesan ke perangkat. Artikel ini membahas elemen kunci dari aplikasi apa pun yang mengirim pesan ke perangkat, termasuk:
- Mendeklarasikan objek klien layanan
- Menyambungkan ke Azure IoT Hub
- Membangun dan mengirim pesan
- Menerima umpan balik pengiriman
- Mengonfigurasi kebijakan coba lagi kirim pesan
Memahami antrean pesan
Untuk memahami pesan cloud-ke-perangkat, penting untuk memahami beberapa dasar tentang cara kerja antrean pesan perangkat IoT Hub.
Pesan cloud-ke-perangkat yang dikirim dari aplikasi backend solusi ke perangkat IoT dirutekan melalui IoT Hub. Tidak ada komunikasi olahpesan peer-to-peer langsung antara aplikasi backend solusi dan perangkat target. IoT Hub menempatkan pesan masuk ke dalam antrean pesannya, siap diunduh oleh perangkat IoT target.
Untuk menjamin pengiriman pesan setidaknya sekali, IoT hub mempertahankan pesan cloud-ke-perangkat dalam antrean per perangkat. Perangkat harus secara eksplisit mengakui penyelesaian pesan sebelum IoT Hub menghapus pesan dari antrean. Pendekatan ini menjamin ketahanan terhadap konektivitas dan kegagalan perangkat.
Saat IoT Hub menempatkan pesan dalam antrean pesan perangkat, IoT Hub mengatur status pesan ke Antrean. Saat utas perangkat mengambil pesan dari antrean, IoT Hub mengunci pesan dengan mengatur status pesan ke Tidak Terlihat. Status ini mencegah utas lain pada perangkat memproses pesan yang sama. Ketika utas perangkat berhasil menyelesaikan pemrosesan pesan, utas tersebut memberi tahu IoT Hub lalu IoT Hub mengatur status pesan ke Selesai.
Aplikasi perangkat yang berhasil menerima dan memproses pesan dikatakan untuk Menyelesaikan pesan. Namun, jika perlu, perangkat juga dapat:
- Tolak pesan, yang menyebabkan IoT Hub mengaturnya ke status Surat mati. Perangkat yang tersambung melalui protokol Message Queuing Telemetry Transport (MQTT) tidak dapat menolak pesan cloud-to-device.
- Abaikan pesan, yang menyebabkan IoT Hub menempatkan pesan kembali dalam antrean, dengan status pesan diatur ke Antrean. Perangkat yang terhubung melalui protokol MQTT tidak dapat meninggalkan pesan cloud-ke-perangkat.
Untuk mengetahui informasi selengkapnya tentang siklus hidup pesan cloud-ke-perangkat cara IoT hub memproses pesan cloud-ke-perangkat, lihat Mengirimkan pesan cloud-ke-perangkat dari IoT hub.
Menerima pesan cloud-ke-perangkat
Bagian ini menjelaskan cara menerima pesan cloud-ke-perangkat menggunakan kelas DeviceClient di Azure IoT SDK untuk .NET.
Ada dua opsi yang dapat digunakan aplikasi klien perangkat untuk menerima pesan:
- Polling: Aplikasi perangkat memeriksa pesan IoT Hub baru menggunakan perulangan kode (misalnya, atau
while
for
perulangan). Perulangan berjalan terus-menerus, memeriksa pesan. - Panggilan balik: Aplikasi perangkat menyiapkan metode handler pesan asinkron yang segera dipanggil ketika pesan tiba.
Mendeklarasikan objek DeviceClient
DeviceClient menyertakan metode dan properti yang diperlukan untuk menerima pesan dari IoT Hub.
Contohnya:
static DeviceClient deviceClient;
Menyediakan parameter koneksi
Berikan string koneksi utama IoT Hub dan ID Perangkat untuk DeviceClient
menggunakan metode CreateFromConnectionString. Selain string koneksi utama IoT Hub yang diperlukan, CreateFromConnectionString
metode ini dapat kelebihan beban untuk menyertakan parameter opsional ini:
transportType
- Protokol transportasi: variasi HTTP versi 1, AMQP, atau MQTT.AMQP
adalah defaultnya. Untuk melihat semua nilai yang tersedia, lihat Enum TransportType.transportSettings
- Antarmuka yang digunakan untuk menentukan berbagai pengaturan khusus transportasi untukDeviceClient
danModuleClient
. Untuk informasi selengkapnya, lihat Antarmuka ITransportSettings.ClientOptions
- Opsi yang memungkinkan konfigurasi perangkat atau instans klien modul selama inisialisasi.
Contoh ini memanggil CreateFromConnectionString
untuk menentukan DeviceClient
hub IoT koneksi dan pengaturan ID perangkat.
static string connectionString = "{your IoT hub connection string}";
static string deviceID = "{your device ID}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString,deviceID);
Polling
Polling menggunakan ReceiveAsync untuk memeriksa pesan.
Panggilan untuk ReceiveAsync
dapat mengambil formulir ini:
ReceiveAsync()
- Tunggu periode batas waktu default untuk pesan sebelum melanjutkan.ReceiveAsync (Timespan)
- Menerima pesan dari antrean perangkat menggunakan batas waktu tertentu.ReceiveAsync (CancellationToken)
- Terima pesan dari antrean perangkat menggunakan token pembatalan. Saat menggunakan token pembatalan, periode batas waktu default tidak digunakan.
Saat menggunakan jenis transportasi HTTP 1 alih-alih MQTT atau AMQP, ReceiveAsync
metode segera kembali. Pola yang didukung untuk pesan cloud-ke-perangkat dengan HTTP 1 adalah perangkat yang terhubung secara terputus-putus yang jarang memeriksa pesan (minimal setiap 25 menit). Mengeluarkan lebih banyak HTTP 1 menerima hasil di IoT Hub yang membatasi permintaan. Untuk informasi selengkapnya tentang perbedaan antara dukungan MQTT, AMQP, dan HTTP 1, lihat Panduan komunikasi cloud-ke-perangkat dan Memilih protokol komunikasi.
Metode CompleteAsync
Setelah perangkat menerima pesan, aplikasi perangkat memanggil metode CompleteAsync untuk memberi tahu IoT Hub bahwa pesan berhasil diproses dan bahwa pesan dapat dihapus dengan aman dari antrean perangkat IoT Hub. Perangkat harus memanggil metode ini ketika pemrosesannya berhasil diselesaikan terlepas dari protokol transportasi yang digunakannya.
Pesan ditinggalkan, ditolak, atau waktu habis
Dengan protokol AMQP dan HTTP versi 1, tetapi bukan protokol MQTT, perangkat juga dapat:
- Abaikan pesan dengan memanggil AbandonAsync. Ini menghasilkan IoT Hub mempertahankan pesan dalam antrean perangkat untuk konsumsi di masa mendatang.
- Tolak pesan dengan memanggil RejectAsync. Ini secara permanen menghapus pesan dari antrean perangkat.
Jika terjadi sesuatu yang mencegah perangkat menyelesaikan, meninggalkan, atau menolak pesan, IoT Hub akan, setelah periode batas waktu tetap, mengantrikan pesan untuk pengiriman ulang. Untuk alasan ini, logika pemrosesan pesan di aplikasi perangkat harus idempotent, sehingga menerima pesan yang sama beberapa kali menghasilkan hasil yang sama.
Untuk mengetahui informasi selengkapnya tentang siklus hidup pesan cloud-ke-perangkat cara IoT hub memproses pesan cloud-ke-perangkat, lihat Mengirimkan pesan cloud-ke-perangkat dari IoT hub.
Perulangan polling
Menggunakan polling, aplikasi menggunakan perulangan kode yang memanggil ReceiveAsync
metode berulang kali untuk memeriksa pesan baru hingga dihentikan.
Jika menggunakan ReceiveAsync
dengan nilai batas waktu atau batas waktu default, dalam perulangan setiap panggilan untuk ReceiveAsync
menunggu periode batas waktu yang ditentukan. Jika ReceiveAsync
waktu habis, null
nilai dikembalikan dan perulangan berlanjut.
Saat pesan diterima, objek Tugas dikembalikan oleh ReceiveAsync
yang harus diteruskan ke CompleteAsync. Panggilan untuk CompleteAsync
memberi tahu IoT Hub untuk menghapus pesan yang ditentukan dari antrean pesan berdasarkan Task
parameter .
Dalam contoh ini, perulangan memanggil ReceiveAsync
hingga pesan diterima atau perulangan polling dihentikan.
static bool stopPolling = false;
while (!stopPolling)
{
// Check for a message. Wait for the default DeviceClient timeout period.
using Message receivedMessage = await _deviceClient.ReceiveAsync();
// Continue if no message was received
if (receivedMessage == null)
{
continue;
}
else // A message was received
{
// Print the message received
Console.WriteLine($"{DateTime.Now}> Polling using ReceiveAsync() - received message with Id={receivedMessage.MessageId}");
PrintMessage(receivedMessage);
// Notify IoT Hub that the message was received. IoT Hub will delete the message from the message queue.
await _deviceClient.CompleteAsync(receivedMessage);
Console.WriteLine($"{DateTime.Now}> Completed C2D message with Id={receivedMessage.MessageId}.");
}
// Check to see if polling loop should end
stopPolling = ShouldPollingstop ();
}
Panggilan balik
Untuk menerima pesan callback cloud-to-device di aplikasi perangkat, aplikasi harus terhubung ke IoT Hub dan menyiapkan pendengar panggilan balik untuk memproses pesan masuk. Pesan masuk ke perangkat diterima dari antrean pesan IoT Hub.
Dengan menggunakan panggilan balik, aplikasi perangkat menyiapkan metode handler pesan menggunakan SetReceiveMessageHandlerAsync. Handler pesan dipanggil kemudian pesan diterima. Membuat metode panggilan balik untuk menerima pesan akan menghapus kebutuhan untuk terus melakukan polling untuk pesan yang diterima.
Panggilan balik hanya tersedia menggunakan protokol ini:
Mqtt
Mqtt_WebSocket_Only
Mqtt_Tcp_Only
Amqp
Amqp_WebSocket_Only
Amqp_Tcp_only
Opsi Http1
protokol tidak mendukung panggilan balik karena metode SDK perlu melakukan polling untuk pesan yang diterima, yang mengalahkan prinsip panggilan balik.
Dalam contoh ini, SetReceiveMessageHandlerAsync
menyiapkan metode handler panggilan balik bernama OnC2dMessageReceivedAsync
, yang disebut setiap kali pesan diterima.
// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");
Menerima kebijakan coba lagi pesan
Kebijakan coba lagi pesan klien perangkat dapat ditentukan menggunakan DeviceClient.SetRetryPolicy.
Batas waktu coba lagi pesan disimpan di properti DeviceClient.OperationTimeoutInMilliseconds .
SDK menerima sampel pesan
.NET/C# SDK menyertakan sampel Terima Pesan yang menyertakan metode pesan terima yang dijelaskan di bagian ini.
Kirim pesan cloud ke perangkat
Bagian ini menjelaskan kode penting untuk mengirim pesan dari aplikasi backend solusi ke perangkat IoT menggunakan kelas ServiceClient di Azure IoT SDK untuk .NET. Seperti yang dibahas sebelumnya, aplikasi backend solusi terhubung ke IoT Hub dan pesan dikirim ke IoT Hub yang dikodekan dengan perangkat tujuan. IoT Hub menyimpan pesan masuk ke antrean pesannya, dan pesan dikirimkan dari antrean pesan IoT Hub ke perangkat target.
Aplikasi backend solusi juga dapat meminta dan menerima umpan balik pengiriman untuk pesan yang dikirim ke IoT Hub yang ditujukan untuk pengiriman perangkat melalui antrean pesan.
Mendeklarasikan objek ServiceClient
ServiceClient mencakup metode dan properti yang diperlukan untuk mengirim pesan dari aplikasi melalui IoT Hub ke perangkat.
static ServiceClient serviceClient;
Menyediakan string koneksi
Berikan string koneksi utama IoT Hub untuk ServiceClient
menggunakan metode CreateFromConnectionString. Selain string koneksi utama IoT Hub yang diperlukan, CreateFromConnectionString
metode ini dapat kelebihan beban untuk menyertakan parameter opsional ini:
transportType
-Amqp
atauAmqp_WebSocket_Only
.transportSettings
- Pengaturan proksi AMQP dan HTTP untuk Klien Layanan.ServiceClientOptions
- Opsi yang memungkinkan konfigurasi instans klien layanan selama inisialisasi. Untuk informasi selengkapnya, lihat ServiceClientOptions.
Contoh ini membuat ServiceClient
objek menggunakan string koneksi IoT Hub.
static string connectionString = "{your iot hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
Mengirim pesan cloud-ke-perangkat asinkron
Gunakan sendAsync untuk mengirim pesan asinkron dari aplikasi melalui cloud (IoT Hub) ke perangkat. Panggilan dilakukan menggunakan protokol AMQP.
sendAsync
menggunakan parameter ini:
deviceID
- Pengidentifikasi string perangkat target.message
- Pesan cloud-ke-perangkat. Pesan berjenis Pesan dan dapat diformat dengan sesuai.timeout
- Nilai batas waktu opsional . Defaultnya adalah satu menit jika tidak ditentukan.
Contoh ini mengirimkan pesan pengujian ke perangkat target dengan nilai batas waktu 10 detik.
string targetDevice = "Device-1";
static readonly TimeSpan operationTimeout = TimeSpan.FromSeconds(10);
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
await serviceClient.SendAsync(targetDevice, commandMessage, operationTimeout);
Menerima umpan balik pengiriman
Program pengiriman dapat meminta pengakuan pengiriman (atau kedaluwarsa) dari IoT Hub untuk setiap pesan cloud-ke-perangkat. Opsi ini memungkinkan program pengirim untuk menggunakan logika informasi, coba lagi, atau kompensasi. Deskripsi lengkap operasi umpan balik pesan dan properti dijelaskan di Umpan balik pesan.
Untuk menerima umpan balik pengiriman pesan:
feedbackReceiver
Membuat objek- Mengirim pesan menggunakan
Ack
parameter - Tunggu untuk menerima umpan balik
Membuat objek feedbackReceiver
Panggil GetFeedbackReceiver untuk membuat objek FeedbackReceiver . FeedbackReceiver
berisi metode yang dapat digunakan layanan untuk melakukan operasi penerimaan umpan balik.
var feedbackReceiver = serviceClient.GetFeedbackReceiver();
Mengirim pesan menggunakan parameter Ack
Setiap pesan harus menyertakan nilai untuk properti Ack pengakuan pengiriman untuk menerima umpan balik pengiriman. Properti Ack
dapat berupa salah satu nilai ini:
none (default): tidak ada pesan umpan balik yang dihasilkan.
Positive
: terima pesan umpan balik jika pesan selesai.Negative
: terima pesan umpan balik jika pesan kedaluwarsa (atau jumlah pengiriman maksimum tercapai) tanpa diselesaikan oleh perangkat.Full
: umpan balik untuk hasilPositive
danNegative
.
Dalam contoh ini, Ack
properti diatur ke Full
, meminta umpan balik pengiriman pesan positif atau negatif untuk satu pesan.
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
commandMessage.Ack = DeliveryAcknowledgement.Full;
await serviceClient.SendAsync(targetDevice, commandMessage);
Tunggu untuk menerima umpan balik
CancellationToken
Tentukan . Kemudian dalam perulangan, panggil ReceiveAsync berulang kali, memeriksa pesan umpan balik pengiriman. Setiap panggilan untuk ReceiveAsync
menunggu periode batas waktu yang ditentukan untuk ServiceClient
objek.
ReceiveAsync
Jika batas waktu kedaluwarsa tanpa pesan yang diterima,ReceiveAsync
pengembaliannull
dan perulangan berlanjut.- Jika pesan umpan balik diterima, objek Tugas dikembalikan oleh
ReceiveAsync
yang harus diteruskan ke CompleteAsync bersama dengan token pembatalan. Panggilan untukCompleteAsync
menghapus pesan terkirim yang ditentukan dari antrean pesan berdasarkanTask
parameter . - Jika diperlukan, kode terima dapat memanggil AbandonAsync untuk menempatkan pesan kirim kembali dalam antrean.
var feedbackReceiver = serviceClient.GetFeedbackReceiver();
// Define the cancellation token.
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;
// Call ReceiveAsync, passing the token. Wait for the timout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync(token);
if (feedbackBatch == null) continue;
Contoh ini menunjukkan metode yang menyertakan langkah-langkah ini.
private async static void ReceiveFeedbackAsync()
{
var feedbackReceiver = serviceClient.GetFeedbackReceiver();
Console.WriteLine("\nReceiving c2d feedback from service");
while (true)
{
// Check for messages, wait for the timeout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync();
// Continue the loop if null is received after a timeout.
if (feedbackBatch == null) continue;
Console.ForegroundColor = ConsoleColor.Yellow;
Console.WriteLine("Received feedback: {0}",
string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
Console.ResetColor();
await feedbackReceiver.CompleteAsync(feedbackBatch);
}
}
Perhatikan pola penerimaan umpan balik ini mirip dengan pola yang digunakan untuk menerima pesan cloud-ke-perangkat di aplikasi perangkat.
Koneksi ulang klien layanan
Saat mengalami pengecualian, klien layanan menyampaikan informasi tersebut ke aplikasi panggilan. Pada titik itu, disarankan agar Anda memeriksa detail pengecualian dan mengambil tindakan yang diperlukan.
Contohnya:
- Jika pengecualian jaringan, Anda dapat mencoba kembali operasi.
- Jika ini adalah pengecualian keamanan (pengecualian tidak sah), periksa kredensial Anda dan pastikan kredensial tersebut sudah diperbarui.
- Jika itu adalah pengecualian pembatasan/kuota yang melebihi pengecualian, pantau dan/atau ubah frekuensi pengiriman permintaan, atau perbarui unit skala instans hub Anda. Lihat kuota dan pembatasan IoT Hub untuk detailnya.
Mengirim kebijakan coba lagi pesan
Kebijakan ServiceClient
coba lagi pesan dapat ditentukan menggunakan ServiceClient.SetRetryPolicy.
Sampel pesan pengiriman SDK
.NET/C# SDK menyertakan sampel klien Layanan yang menyertakan metode kirim pesan yang dijelaskan di bagian ini.
Menerima pesan cloud-ke-perangkat
Bagian ini menjelaskan cara menerima pesan cloud-ke-perangkat menggunakan kelas DeviceClient dari Azure IoT SDK untuk Java.
Agar aplikasi perangkat berbasis Java menerima pesan cloud-ke-perangkat, aplikasi harus tersambung ke IoT Hub, lalu menyiapkan pendengar panggilan balik dan penanganan pesan untuk memproses pesan masuk dari IoT Hub. Aplikasi perangkat juga harus dapat mendeteksi dan menangani pemutusan sambungan jika koneksi pesan device-to-IoT Hub rusak.
Mengimpor pustaka Azure IoT Java SDK
Kode yang direferensikan dalam artikel ini menggunakan pustaka SDK ini.
import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
Mendeklarasikan objek DeviceClient
Instansiasi objek DeviceClient memerlukan parameter ini:
- connString - Perangkat IoT string koneksi. string koneksi adalah sekumpulan pasangan kunci-nilai yang dipisahkan oleh ';', dengan kunci dan nilai yang dipisahkan oleh '='. Ini harus berisi nilai untuk kunci ini:
HostName, DeviceId, and SharedAccessKey
. - Protokol transportasi - Koneksi
DeviceClient
dapat menggunakan salah satu protokol transportasi IoTHubClientProtocol berikut.AMQP
adalah yang paling serbaguna, memungkinkan untuk sering memeriksa pesan, dan memungkinkan penolakan dan pembatalan pesan. MQTT tidak mendukung penolakan pesan atau mengabaikan metode:AMQPS
AMQPS_WS
HTTPS
MQTT
MQTT_WS
Contohnya:
static string connectionString = "{a device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);
Mengatur metode panggilan balik pesan
Gunakan metode setMessageCallback untuk menentukan metode handler pesan yang diberi tahu saat pesan diterima dari IoT Hub.
setMessageCallback
termasuk parameter ini:
callback
- Nama metode panggilan balik. Bisa jadinull
.context
- Konteks opsional jenisobject
. Gunakannull
jika tidak ditentukan.
Dalam contoh ini, metode bernama callback
MessageCallback
tanpa parameter konteks diteruskan ke setMessageCallback
.
client.setMessageCallback(new MessageCallback(), null);
Membuat handler panggilan balik pesan
Handler pesan panggilan balik menerima dan memproses pesan masuk yang diteruskan dari antrean pesan IoT Hub.
Dalam contoh ini, handler pesan memproses pesan masuk lalu mengembalikan IotHubMessageResult.COMPLETE. IotHubMessageResult.COMPLETE
Nilai pengembalian memberi tahu IoT Hub bahwa pesan berhasil diproses dan bahwa pesan dapat dihapus dengan aman dari antrean perangkat. Perangkat harus kembali IotHubMessageResult.COMPLETE
ketika pemrosesannya berhasil diselesaikan, memberi tahu IoT Hub bahwa pesan harus dihapus dari antrean pesan, terlepas dari protokol yang digunakannya.
protected static class MessageCallback implements com.microsoft.azure.sdk.iot.device.MessageCallback
{
public IotHubMessageResult onCloudToDeviceMessageReceived(Message msg, Object context)
{
System.out.println(
"Received message with content: " + new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));
// Notify IoT Hub that the message
return IotHubMessageResult.COMPLETE;
}
}
Opsi pengabaian dan penolakan pesan
Meskipun sejumlah besar pesan masuk ke perangkat harus berhasil diterima dan mengakibatkan IotHubMessageResult.COMPLETE
, mungkin perlu untuk meninggalkan atau menolak pesan.
- Dengan AMQP dan HTTPS, tetapi bukan MQTT, aplikasi dapat:
IotHubMessageResult.ABANDON
pesan. Hub IoT mengantre ulang dan mengirimkannya lagi nanti.IotHubMessageResult.REJECT
pesan. Hub IoT tidak mengantre ulang pesan dan menghapus pesan secara permanen dari antrean pesan.
- Klien yang menggunakan
MQTT
atauMQTT_WS
tidak dapatABANDON
atauREJECT
pesan.
Jika terjadi sesuatu yang mencegah perangkat menyelesaikan, meninggalkan, atau menolak pesan, IoT Hub akan, setelah periode batas waktu tetap, mengantrikan pesan untuk pengiriman ulang. Untuk alasan ini, logika pemrosesan pesan di aplikasi perangkat harus idempotent, sehingga menerima pesan yang sama beberapa kali menghasilkan hasil yang sama.
Untuk mengetahui informasi selengkapnya tentang siklus hidup pesan cloud-ke-perangkat cara IoT hub memproses pesan cloud-ke-perangkat, lihat Mengirimkan pesan cloud-ke-perangkat dari IoT hub.
Catatan
Jika Anda menggunakan HTTPS alih-alih MQTT atau AMQP sebagai transportasi, instans DeviceClient memeriksa pesan dari IoT Hub (minimal setiap 25 menit). Untuk informasi selengkapnya tentang perbedaan antara dukungan MQTT, AMQP, dan HTTPS, lihat Panduan komunikasi cloud-to-device dan Pilih protokol komunikasi.
Membuat metode panggilan balik status pesan
Aplikasi dapat menggunakan registerConnectionStatusChangeCallback untuk mendaftarkan metode panggilan balik yang akan dijalankan saat status koneksi perangkat berubah. Dengan cara ini aplikasi dapat mendeteksi koneksi pesan yang terputus dan mencoba menyambungkan kembali.
Dalam contoh ini, IotHubConnectionStatusChangeCallbackLogger
terdaftar sebagai status koneksi mengubah metode panggilan balik.
client.registerConnectionStatusChangeCallback(new IotHubConnectionStatusChangeCallbackLogger(), new Object());
Panggilan balik diaktifkan dan melewati ConnectionStatusChangeContext
objek.
Panggil connectionStatusChangeContext.getNewStatus()
untuk mendapatkan status koneksi saat ini.
IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();
Status koneksi yang dikembalikan bisa menjadi salah satu nilai ini:
IotHubConnectionStatus.DISCONNECTED
IotHubConnectionStatus.DISCONNECTED_RETRYING
IotHubConnectionStatus.CONNECTED
Panggil connectionStatusChangeContext.getNewStatusReason()
untuk mendapatkan alasan perubahan status koneksi.
IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();
Panggil connectionStatusChangeContext.getCause()
untuk menemukan alasan perubahan status koneksi. getCause()
dapat kembali null
jika tidak ada informasi yang tersedia.
Throwable throwable = connectionStatusChangeContext.getCause();
if (throwable != null)
throwable.printStackTrace();
Lihat sampel HandleMessages yang tercantum di bagian sampel pesan penerima SDK di artikel ini untuk sampel lengkap yang menunjukkan cara mengekstrak status perubahan status perubahan status koneksi metode panggilan balik, alasan mengapa status perangkat berubah, dan konteks.
Buka koneksi antara perangkat dan IoT Hub
Gunakan buka untuk membuat koneksi antara perangkat dan IoT Hub. Perangkat sekarang dapat mengirim dan menerima pesan secara asinkron ke dan dari IoT Hub. Jika klien sudah terbuka, metode tidak melakukan apa pun.
client.open(true);
SDK menerima sampel pesan
HandleMessages: aplikasi perangkat sampel yang disertakan dengan Microsoft Azure IoT SDK untuk Java, yang terhubung ke hub IoT Anda dan menerima pesan cloud-ke-perangkat.
Kirim pesan cloud ke perangkat
Bagian ini menjelaskan cara mengirim pesan cloud-ke-perangkat menggunakan kelas ServiceClient dari Azure IoT SDK untuk Java. Aplikasi backend solusi terhubung ke IoT Hub dan pesan dikirim ke IoT Hub yang dikodekan dengan perangkat tujuan. IoT Hub menyimpan pesan masuk ke antrean pesannya, dan pesan dikirimkan dari antrean pesan IoT Hub ke perangkat target.
Aplikasi backend solusi juga dapat meminta dan menerima umpan balik pengiriman untuk pesan yang dikirim ke IoT Hub yang ditujukan untuk pengiriman perangkat melalui antrean pesan.
Menambahkan pernyataan dependensi
Tambahkan dependensi untuk menggunakan paket iothub-java-service-client di aplikasi Anda untuk berkomunikasi dengan layanan hub IoT Anda:
<dependency>
<groupId>com.microsoft.azure.sdk.iot</groupId>
<artifactId>iot-service-client</artifactId>
<version>1.7.23</version>
</dependency>
Menambahkan pernyataan impor
Tambahkan pernyataan impor ini untuk menggunakan Azure IoT Java SDK dan handler pengecualian.
import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;
Tentukan protokol koneksi
Gunakan IotHubServiceClientProtocol untuk menentukan protokol lapisan aplikasi yang digunakan oleh klien layanan untuk berkomunikasi dengan IoT Hub.
IotHubServiceClientProtocol
hanya menerima AMQPS
atau AMQPS_WS
enum.
private static final IotHubServiceClientProtocol protocol =
IotHubServiceClientProtocol.AMQPS;
Membuat objek ServiceClient
Buat objek ServiceClient, menyediakan string koneksi dan protokol Iot Hub.
private static final String connectionString = "{yourhubconnectionstring}";
private static final ServiceClient serviceClient (connectionString, protocol);
Buka koneksi antara aplikasi dan IoT Hub
buka koneksi pengirim AMQP. Metode ini membuat koneksi antara aplikasi dan IoT Hub.
serviceClient.open();
Buka penerima umpan balik untuk umpan balik pengiriman pesan
Anda dapat menggunakan FeedbackReceiver untuk mendapatkan pengiriman pesan terkirim ke umpan balik IoT Hub. adalah FeedbackReceiver
penerima khusus yang metodenya Receive
mengembalikan alih-alih FeedbackBatch
Message
.
Dalam contoh ini, FeedbackReceiver
objek dibuat dan pernyataan dipanggil open()
untuk menunggu umpan balik.
FeedbackReceiver feedbackReceiver = serviceClient
.getFeedbackReceiver();
if (feedbackReceiver != null) feedbackReceiver.open();
Menambahkan properti pesan
Anda dapat secara opsional menggunakan setProperties untuk menambahkan properti pesan. Properti ini disertakan dalam pesan yang dikirim ke perangkat dan dapat diekstrak oleh aplikasi perangkat setelah diterima.
Map<String, String> propertiesToSend = new HashMap<String, String>();
propertiesToSend.put(messagePropertyKey,messagePropertyKey);
messageToSend.setProperties(propertiesToSend);
Membuat dan mengirim pesan asinkron
Objek Pesan menyimpan pesan yang akan dikirim. Dalam contoh ini, "Pesan cloud ke perangkat" dikirimkan.
Gunakan setDeliveryAcknowledgement untuk meminta pengiriman/tidak dikirimkan ke pengakuan antrean pesan IoT Hub. Dalam contoh ini, pengakuan yang diminta adalah Full
, baik dikirimkan atau tidak dikirimkan.
Gunakan SendAsync untuk mengirim pesan asinkron dari klien ke perangkat. Atau, Anda dapat menggunakan Send
metode (bukan asinkron), tetapi fungsi ini disinkronkan secara internal sehingga hanya satu operasi pengiriman yang diizinkan pada satu waktu. Pesan dikirimkan dari aplikasi ke IoT Hub. IoT Hub menempatkan pesan ke dalam antrean pesan, siap untuk dikirimkan ke perangkat target.
Message messageToSend = new Message("Cloud to device message.");
messageToSend.setDeliveryAcknowledgementFinal(DeliveryAcknowledgement.Full);
serviceClient.sendAsync(deviceId, messageToSend);
Menerima umpan balik pengiriman pesan
Setelah pesan dikirim dari aplikasi, aplikasi dapat memanggil terima dengan atau tanpa nilai batas waktu. Jika nilai batas waktu tidak disediakan, batas waktu default digunakan. Ini meneruskan kembali objek FeedbackBatch yang berisi properti umpan balik pengiriman pesan yang dapat diperiksa.
Contoh ini membuat FeedbackBatch
penerima dan panggilan getEnqueuedTimeUtc, mencetak waktu antrean pesan.
FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
if (feedbackBatch != null) {
System.out.println("Message feedback received, feedback time: "
+ feedbackBatch.getEnqueuedTimeUtc().toString());
}
SDK mengirim sampel pesan
Menginstal pustaka Azure IoT SDK
Instal pustaka SDK azure-iot-device di komputer pengembangan Anda sebelum memanggil kode terkait:
pip install azure-iot-device
Ada dua kelas Python SDK yang digunakan untuk mengirim pesan ke dan dari perangkat IoT. Metode penanganan pesan dari kelas ini dijelaskan di bagian di halaman ini.
Kelas IoTHubDeviceClient menyertakan metode untuk membuat koneksi sinkron dari perangkat ke Azure IoT Hub dan menerima pesan dari IoT Hub.
Kelas IoTHubRegistryManager menyertakan API untuk operasi IoT Hub Registry Manager. Dalam artikel ini, metode dari kelas ini menunjukkan cara menyambungkan ke IoT Hub dan mengirim pesan ke perangkat.
Menerima pesan cloud-ke-perangkat
Bagian ini menjelaskan cara menerima pesan cloud-ke-perangkat menggunakan kelas IoTHubDeviceClient dari Azure IoT SDK untuk Python.
Agar aplikasi perangkat berbasis Python menerima pesan cloud-ke-perangkat, aplikasi harus tersambung ke IoT Hub lalu menyiapkan penanganan pesan panggilan balik untuk memproses pesan masuk dari IoT Hub.
Mengimpor objek IoTHubDeviceClient
Tambahkan baris kode untuk mengimpor IoTHubDeviceClient
fungsi dari azure.iot.device SDK.
from azure.iot.device import IoTHubDeviceClient
Menyambungkan klien perangkat
Buat instans IoTHubDeviceClient, meneruskan string koneksi IoT Hub ke create_from_connection_string. Ini membuat koneksi dari perangkat ke IoT Hub.
Atau, Anda dapat terhubung IoTHubDeviceClient
ke perangkat menggunakan salah satu metode berikut:
deviceConnectionString = "{your IoT hub connection string}";
client = IoTHubDeviceClient.create_from_connection_string ({deviceConnectionString})
Menangani koneksi ulang
IoTHubDeviceClient
secara default akan mencoba membangun kembali koneksi yang terputus. Perilaku koneksi ulang diatur oleh IoTHubDeviceClient
connection_retry dan connection_retry_interval
parameter.
Membuat handler pesan
Buat fungsi handler pesan untuk memproses pesan masuk ke perangkat.
Dalam contoh ini, message_handler
dipanggil ketika pesan diterima. Properti pesan (.items
) dicetak ke konsol menggunakan perulangan.
def message_handler(message):
global RECEIVED_MESSAGES
RECEIVED_MESSAGES += 1
print("")
print("Message received:")
# print data from both system and application (custom) properties
for property in vars(message).items():
print (" {}".format(property))
print("Total calls received: {}".format(RECEIVED_MESSAGES))
Menetapkan handler pesan
Gunakan metode on_message_received untuk menetapkan metode handler pesan ke IoTHubDeviceClient
objek.
Dalam contoh ini, metode handler pesan bernama message_handler
dilampirkan ke IoTHubDeviceClient
client
objek. Objek client
menunggu untuk menerima pesan cloud-ke-perangkat dari IoT Hub. Kode ini menunggu hingga 300 detik (5 menit) untuk pesan, atau keluar jika tombol keyboard ditekan.
try:
# Attach the handler to the client
client.on_message_received = message_handler
while True:
time.sleep(300)
except KeyboardInterrupt:
print("IoT Hub C2D Messaging device sample stopped")
finally:
# Graceful exit
print("Shutting down IoT Hub Client")
client.shutdown()
SDK menerima sampel pesan
Terima Pesan - Terima pesan Cloud-to-Device (C2D) yang dikirim dari Azure IoT Hub ke perangkat.
Kirim pesan cloud ke perangkat
Bagian ini menjelaskan cara mengirim pesan cloud-ke-perangkat menggunakan kelas IoTHubRegistryManager dari Azure IoT SDK untuk Python. Aplikasi backend solusi terhubung ke IoT Hub dan pesan dikirim ke IoT Hub yang dikodekan dengan perangkat tujuan. IoT Hub menyimpan pesan masuk ke antrean pesannya, dan pesan dikirimkan dari antrean pesan IoT Hub ke perangkat target.
Mengimpor objek IoTHubRegistryManager
Tambahkan pernyataan import
berikut. IoTHubRegistryManager menyertakan API untuk operasi IoT Hub Registry Manager.
from azure.iot.hub import IoTHubRegistryManager
Menyambungkan manajer registri IoT Hub
Buat instans objek IoTHubRegistryManager yang terhubung ke hub IoT, meneruskan IoT Hub string koneksi ke from_connection_string.
IoTHubConnectionString = "{Primary connection string to an IoT hub}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)
Membangun dan mengirim pesan
Gunakan send_c2d_message untuk mengirim pesan melalui cloud (IoT Hub) ke perangkat.
send_c2d_message
menggunakan parameter ini:
deviceID
- Pengidentifikasi string perangkat target.message
- Pesan cloud-ke-perangkat. Pesan berjenisstr
(string).properties
- Koleksi opsional properti jenisdict
. Properti dapat berisi properti aplikasi dan properti sistem. Nilai defaultnya adalah{}
.
Contoh ini mengirim pesan pengujian ke perangkat target.
# define the device ID
deviceID = "Device-1"
# define the message
message = "{\"c2d test message\"}"
# include optional properties
props={}
props.update(messageId = "message1")
props.update(prop1 = "test property-1")
props.update(prop1 = "test property-2")
prop_text = "Test message"
props.update(testProperty = prop_text)
# send the message through the cloud (IoT Hub) to the device
registry_manager.send_c2d_message(deviceID, message, properties=props)
Sampel pesan pengiriman SDK
send_message.py - Menunjukkan cara mengirim pesan cloud-ke-perangkat.
Menginstal paket olahpesan Node.js
Jalankan perintah ini untuk menginstal paket azure-iot-device dan azure-iothub di komputer pengembangan Anda:
npm install azure-iot-device --save
npm install azure-iothub --save
Paket azure-iot-device berisi objek yang berinteraksi dengan perangkat IoT. Artikel ini menjelaskan Client
kode kelas yang menerima pesan dari IoT Hub.
Paket azure-iothub berisi objek yang berinteraksi dengan IoT Hub. Artikel ini menjelaskan Client
kode kelas yang mengirim pesan dari aplikasi ke perangkat melalui IoT Hub.
Menerima pesan dalam aplikasi perangkat
Bagian ini menjelaskan cara menerima pesan cloud-ke-perangkat menggunakan paket azure-iot-device di Azure IoT SDK untuk Node.js.
Agar aplikasi perangkat berbasis Node.js menerima pesan cloud-ke-perangkat, aplikasi harus tersambung ke IoT Hub, lalu menyiapkan pendengar panggilan balik dan penangan pesan untuk memproses pesan masuk dari IoT Hub. Aplikasi perangkat juga harus dapat mendeteksi dan menangani pemutusan sambungan jika koneksi pesan device-to-IoT Hub rusak.
Membuat modul klien
Dari azure-iot-device
paket, buat Client
menggunakan kelas Klien . Kelas Client
berisi metode yang dapat digunakan perangkat untuk menerima dan mengirim ke IoT Hub.
const Client = require('azure-iot-device').Client;
Pilih protokol transportasi
Objek Client
mendukung protokol ini:
Amqp
Http
- Saat menggunakanHttp
,Client
instans memeriksa pesan dari IoT Hub jarang (minimal setiap 25 menit).Mqtt
MqttWs
AmqpWs
Untuk informasi selengkapnya tentang perbedaan antara dukungan MQTT, AMQP, dan HTTPS, lihat Panduan komunikasi cloud-to-device dan Pilih protokol komunikasi.
Contoh ini menetapkan protokol AMQP ke Protocol
variabel. Variabel Protokol ini diteruskan ke Client.fromConnectionString
metode di bagian Tambahkan string koneksi dari artikel ini.
const Protocol = require('azure-iot-device-mqtt').Amqp;
Penyelesaian pesan, penolakan, dan pengabaian kemampuan
Penyelesaian pesan, penolakan, dan metode pengabaian dapat digunakan tergantung pada protokol yang dipilih.
AMQP dan HTTP
Transportasi AMQP dan HTTP dapat menyelesaikan, menolak, atau meninggalkan pesan:
- Selesai - Untuk menyelesaikan pesan, layanan yang mengirim pesan cloud-ke-perangkat diberi tahu bahwa pesan diterima. IoT Hub menghapus pesan dari antrean pesan. Metode ini mengambil bentuk
client.complete(message, callback function)
. - Tolak - Untuk menolak pesan, layanan yang mengirim pesan cloud-ke-perangkat diberi tahu bahwa pesan tidak diproses oleh perangkat. IoT Hub menghapus pesan secara permanen dari antrean perangkat. Metode ini mengambil bentuk
client.reject(message, callback function)
. - Tinggalkan - Untuk meninggalkan pesan, IoT Hub segera mencoba mengirimnya kembali. IoT Hub mempertahankan pesan dalam antrean perangkat untuk konsumsi di masa mendatang. Metode ini mengambil bentuk
client.abandon(message, callback function)
.
MQTT
MQTT tidak mendukung fungsi selesai, tolak, atau tinggalkan pesan. Sebagai gantinya, MQTT menerima pesan secara default dan pesan dihapus dari antrean pesan IoT Hub.
Upaya redelivery
Jika terjadi sesuatu yang mencegah perangkat menyelesaikan, meninggalkan, atau menolak pesan, IoT Hub akan, setelah periode batas waktu tetap, mengantrikan pesan untuk pengiriman ulang. Untuk alasan ini, logika pemrosesan pesan di aplikasi perangkat harus idempotent, sehingga menerima pesan yang sama beberapa kali menghasilkan hasil yang sama.
Menambahkan string IoT Hub dan protokol transportasi
Panggil dariConnectionString untuk membuat koneksi hub perangkat-ke-IoT menggunakan parameter ini:
- connStr - string koneksi yang merangkum izin "device connect" untuk hub IoT. string koneksi berisi Nama Host, ID Perangkat & Kunci Akses Bersama dalam format ini: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>"
- transportCtor - Protokol transportasi.
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);
Membuat handler pesan masuk
Handler pesan dipanggil untuk setiap pesan masuk.
Setelah pesan berhasil diterima, jika menggunakan transportasi AMQP atau HTTP, panggil client.complete
metode untuk memberi tahu IoT Hub bahwa pesan dapat dihapus dari antrean pesan.
Misalnya, handler pesan ini mencetak ID pesan dan isi pesan ke konsol, lalu memanggil untuk memberi tahu IoT Hub bahwa pesan tersebut diproses client.complete
dan dapat dihapus dengan aman dari antrean perangkat. Panggilan ke complete
tidak diperlukan jika Anda menggunakan transportasi MQTT dan dapat dihilangkan. Panggilan kecomplete
diperlukan untuk transportasi AMQP atau HTTPS.
function messageHandler(msg) {
console.log('Id: ' + msg.messageId + ' Body: ' + msg.data);
client.complete(msg, printResultFor('completed'));
}
Membuat handler pemutusan sambungan
Handler pemutusan sambungan dipanggil ketika koneksi terputus. Handler pemutusan sambungan berguna untuk menerapkan kode koneksi ulang.
Contoh ini menangkap dan menampilkan pesan kesalahan pemutusan sambungan ke konsol.
function disconnectHandler() {
clearInterval(sendInterval);
sendInterval = null;
client.open().catch((err) => {
console.error(err.message);
});
}
Menambahkan pendengar peristiwa
Anda dapat menentukan pendengar peristiwa ini menggunakan metode .on .
- Penangan koneksi
- Penangan kesalahan
- Putuskan sambungan handler
- Penangan pesan
Contoh ini mencakup penangan pesan dan pemutusan sambungan yang ditentukan sebelumnya.
client.on('connect', connectHandler);
client.on('error', errorHandler);
client.on('disconnect', disconnectHandler);
client.on('message', messageHandler);
Buka koneksi ke IoT Hub
Gunakan metode terbuka untuk membuka koneksi antara perangkat IoT dan IoT Hub.
Gunakan .catch(err)
untuk menangkap kesalahan dan kode handler panggilan.
Contohnya:
client.open()
.catch((err) => {
console.error('Could not connect: ' + err.message);
});
SDK menerima sampel pesan
simple_sample_device - Aplikasi perangkat yang terhubung ke hub IoT Anda dan menerima pesan cloud-to-device.
Kirim pesan cloud ke perangkat
Bagian ini menjelaskan cara mengirim pesan cloud-ke-perangkat menggunakan paket azure-iothub dari Azure IoT SDK untuk Node.js. Seperti yang dibahas sebelumnya, aplikasi backend solusi terhubung ke IoT Hub dan pesan dikirim ke IoT Hub yang dikodekan dengan perangkat tujuan. IoT Hub menyimpan pesan masuk ke antrean pesannya, dan pesan dikirimkan dari antrean pesan IoT Hub ke perangkat target.
Aplikasi backend solusi juga dapat meminta dan menerima umpan balik pengiriman untuk pesan yang dikirim ke IoT Hub yang ditujukan untuk pengiriman perangkat melalui antrean pesan.
Memuat modul klien dan pesan
Deklarasikan Client
objek menggunakan Client
kelas dari azure-iothub
paket.
Deklarasikan Message
objek menggunakan Message
kelas dari azure-iot-common
paket.
'use strict';
var Client = require('azure-iothub').Client;
var Message = require('azure-iot-common').Message;
Membuat objek Klien
Buat Klien menggunakan fromConnectionString menggunakan parameter ini:
- String koneksi IoT Hub
- Jenis transportasi
Dalam contoh ini, serviceClient
objek dibuat dengan Amqp
jenis transportasi.
var connectionString = '{IoT Hub connection string}';
var serviceClient = Client.fromConnectionString(connectionString,`Amqp`);
Buka koneksi Klien
Client
Panggil metode terbuka untuk membuka koneksi antara aplikasi dan IoT Hub.
open
dapat dipanggil dengan atau tanpa menentukan fungsi panggilan balik yang dipanggil ketika open
operasi selesai.
Dalam contoh ini, open
metode ini menyertakan fungsi panggilan balik koneksi terbuka opsional err
. Jika terjadi kesalahan terbuka, objek kesalahan dikembalikan. Jika koneksi terbuka berhasil, null
nilai panggilan balik dikembalikan.
serviceClient.open(function (err)
if (err)
console.error('Could not connect: ' + err.message);
Membuat pesan
Objek pesan menyertakan pesan cloud-ke-perangkat asinkron. Fungsionalitas pesan berfungsi dengan cara yang sama melalui AMQP, MQTT, dan HTTP.
Objek pesan mendukung beberapa properti, termasuk properti ini. Lihat properti pesan untuk daftar lengkap.
ack
- Umpan balik pengiriman. Dijelaskan di bagian berikutnya.properties
- Peta yang berisi kunci string dan nilai untuk menyimpan properti pesan kustom.- messageId - Digunakan untuk menghubungkan komunikasi dua arah.
Tambahkan isi pesan saat objek pesan dibuat. Dalam contoh ini, pesan 'Cloud to device message.'
ditambahkan.
var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";
Pengakuan pengiriman
Program pengiriman dapat meminta pengakuan pengiriman (atau kedaluwarsa) dari IoT Hub untuk setiap pesan cloud-ke-perangkat. Opsi ini memungkinkan program pengirim untuk menggunakan logika informasi, coba lagi, atau kompensasi. Deskripsi lengkap operasi umpan balik pesan dan properti dijelaskan di Umpan balik pesan.
Setiap pesan yang menerima umpan balik pesan harus menyertakan nilai untuk properti ack pengakuan pengiriman. Properti ack
dapat berupa salah satu nilai ini:
none (default): tidak ada pesan umpan balik yang dihasilkan.
sent
: terima pesan umpan balik jika pesan selesai.: terima pesan umpan balik jika pesan kedaluwarsa (atau jumlah pengiriman maksimum tercapai) tanpa diselesaikan oleh perangkat.
full
: umpan balik untuk hasil yang dikirim dan tidak dikirim.
Dalam contoh ini, ack
properti diatur ke full
, meminta umpan balik pengiriman pesan terkirim dan tidak dikirim untuk satu pesan.
message.ack = 'full';
Menautkan penerima umpan balik pesan
Fungsi panggilan balik penerima umpan balik pesan ditautkan ke Client
menggunakan getFeedbackReceiver.
Penerima umpan balik pesan menerima dua argumen:
- Objek kesalahan (bisa null)
- Objek AmqpReceiver - Memancarkan peristiwa ketika pesan umpan balik baru diterima oleh klien.
Contoh fungsi ini menerima dan mencetak pesan umpan balik pengiriman ke konsol.
function receiveFeedback(err, receiver){
receiver.on('message', function (msg) {
console.log('Feedback message:')
console.log(msg.getData().toString('utf-8'));
});
}
Kode ini menautkan receiveFeedback
fungsi panggilan balik umpan balik ke objek layanan Client
menggunakan getFeedbackReceiver
.
serviceClient.getFeedbackReceiver(receiveFeedback);
Menentukan penangan hasil penyelesaian pesan
Fungsi panggilan balik pengiriman pesan dipanggil setelah setiap pesan dikirim.
Contoh fungsi ini mencetak hasil operasi pesan send
ke konsol. Dalam contoh ini, printResultFor
fungsi disediakan sebagai parameter untuk fungsi yang send
dijelaskan di bagian berikutnya.
function printResultFor(op) {
return function printResult(err, res) {
if (err) console.log(op + ' error: ' + err.toString());
if (res) console.log(op + ' status: ' + res.constructor.name);
};
}
Mengirim pesan
Gunakan fungsi kirim untuk mengirim pesan cloud-ke-perangkat asinkron ke aplikasi perangkat melalui IoT Hub.
send
mendukung parameter ini:
- deviceID - ID perangkat perangkat target.
- message - Isi pesan yang akan dikirim ke perangkat.
- selesai - Fungsi opsional untuk memanggil ketika operasi selesai. Selesai dipanggil dengan dua argumen:
- Objek kesalahan (bisa null).
- objek respons khusus transportasi berguna untuk pengelogan atau penelusuran kesalahan.
Kode ini memanggil send
untuk mengirim pesan cloud-ke-perangkat ke aplikasi perangkat melalui IoT Hub. Fungsi panggilan balik printResultFor
yang ditentukan di bagian sebelumnya menerima informasi pengakuan pengiriman.
var targetDevice = '{device ID}';
serviceClient.send(targetDevice, message, printResultFor('send'));
Contoh ini menunjukkan cara mengirim pesan ke perangkat Anda dan menangani pesan umpan balik saat perangkat mengakui pesan cloud-to-device:
serviceClient.open(function (err) {
if (err) {
console.error('Could not connect: ' + err.message);
} else {
console.log('Service client connected');
serviceClient.getFeedbackReceiver(receiveFeedback);
var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";
console.log('Sending message: ' + message.getData());
serviceClient.send(targetDevice, message, printResultFor('send'));
}
});
Sampel pesan pengiriman SDK
send_c2d_message.js - Mengirim pesan C2D ke perangkat melalui IoT Hub.
Kebijakan koneksi rekoneksi
Artikel ini tidak menunjukkan kebijakan coba lagi pesan untuk perangkat ke koneksi IoT Hub atau aplikasi eksternal ke koneksi IoT Hub. Dalam kode produksi, Anda harus menerapkan kebijakan coba lagi koneksi seperti yang dijelaskan dalam Mengelola koneksi ulang perangkat untuk membuat aplikasi tangguh.
Waktu retensi pesan, upaya coba lagi, dan jumlah pengiriman maks
Seperti yang dijelaskan dalam Mengirim pesan cloud-ke-perangkat dari IoT Hub, Anda dapat melihat dan mengonfigurasi default untuk nilai pesan berikut menggunakan opsi konfigurasi IoT Hub portal atau Azure CLI. Opsi konfigurasi ini dapat memengaruhi pengiriman pesan dan umpan balik.
- TTL default (waktu hidup) - Jumlah waktu pesan tersedia untuk digunakan perangkat sebelum kedaluwarsa oleh IoT Hub.
- Waktu retensi umpan balik - Jumlah waktu IoT Hub mempertahankan umpan balik untuk kedaluwarsa atau pengiriman pesan cloud-ke-perangkat.
- Frekuensi IoT Hub mencoba mengirimkan pesan cloud-ke-perangkat ke perangkat.