Menghubungkan klien AMQP ke IoT Platform - IoT Platform

Topik ini menjelaskan cara menghubungkan klien Protokol Antrian Pesan Lanjutan (AMQP) ke IoT Platform. Setelah mengonfigurasi langganan sisi server AMQP di konsol IoT Platform, Anda dapat menerima pesan perangkat melalui klien AMQP pada server bisnis Anda.

Batasan

Untuk informasi lebih lanjut tentang AMQP, kunjungi situs resmi AMQP.

Langganan sisi server IoT Platform hanya mendukung protokol AMQP 1.0.

Menghubungkan ke IoT Platform

Klien AMQP membangun koneksi TCP dengan IoT Platform menggunakan jabat tangan tiga arah. Kemudian, dilakukan Proses jabat tangan TLS untuk mengotentikasi klien AMQP.
Catatan
Untuk memastikan keamanan, klien AMQP harus mentransmisikan data menggunakan enkripsi TLS. Data tidak dapat ditransmisikan melalui saluran TCP tanpa enkripsi.
Klien meminta untuk membangun koneksi.
Mekanisme SASL PLAIN digunakan untuk mengotentikasi koneksi berdasarkan nama pengguna dan kata sandi. Setelah otentikasi disetujui oleh IoT Platform, koneksi dibuat.
Sesuai dengan AMQP, klien harus menambahkan bidang idle-time-out ke frame terbuka saat membangun koneksi. Bidang ini menentukan periode waktu habis untuk detak jantung, yang berkisar antara 30.000 ms hingga 300.000 ms. Jika tidak ada frame yang ditransmisikan setelah periode waktu habis detak jantung berakhir, IoT Platform akan menutup koneksi. Metode konfigurasi bidang idle-time-out bervariasi berdasarkan bahasa pemrograman SDK. Untuk detail lebih lanjut, lihat kode contoh SDK spesifik bahasa.
Klien mengirim permintaan ke IoT Platform untuk membangun tautan penerima. Tautan penerima adalah saluran satu arah yang digunakan untuk mendorong data dari IoT Platform ke klien.
Klien harus membangun tautan penerima dalam 15 detik setelah koneksi AMQP dibuat. Jika tidak, IoT Platform akan menutup koneksi AMQP.
Setelah tautan penerima dibuat, klien terhubung ke IoT Platform.
Catatan
- Hanya satu tautan penerima yang dapat dibuat untuk setiap koneksi. Tautan pengirim tidak didukung. IoT Platform dapat mendorong pesan ke klien, tetapi klien tidak dapat mengirim pesan ke IoT Platform.
- Nama kelas tautan penerima bervariasi berdasarkan bahasa pemrograman SDK. Sebagai contoh, tautan penerima diberi nama MessageConsumer di beberapa SDK.

Pengaturan koneksi

Bagian ini menjelaskan cara menentukan titik akhir dan mengonfigurasi parameter otentikasi saat menghubungkan klien AMQP ke IoT Platform.

Titik akhir dan port

Tentukan titik akhir instance publik atau instance Enterprise Edition yang ingin dihubungkan dengan klien AMQP. Untuk informasi lebih lanjut tentang titik akhir yang didukung, lihat Kelola Titik Akhir Suatu Instance.

Catatan

Variabel ${YourHost} dalam SDK menentukan titik akhir.

Sebelum menghubungkan klien ke instance IoT Platform, pastikan produk dan perangkat Anda telah dibuat di instance tersebut.

Jika menggunakan klien Java, .NET, Python 2.7, Node.js, atau Go, nomor portnya adalah 5671.
Jika menggunakan klien Python 3 atau PHP, nomor portnya adalah 61614.

Parameter otentikasi

Parameter otentikasi yang perlu dikonfigurasi bervariasi berdasarkan identitas Alibaba Cloud yang digunakan untuk menghubungkan klien AMQP ke IoT Platform.

Jika menggunakan akun Alibaba Cloud tempat instance IoT Platform berada atau Pengguna Resource Access Management (RAM) yang secara langsung diberi izin yang diperlukan dalam akun Alibaba Cloud, Anda harus mengonfigurasi parameter otentikasi berikut:
Catatan
Jika menggunakan pengguna RAM, Anda harus melampirkan kebijakan RAM yang berisi tindakan iot:sub ke pengguna RAM. Dengan cara ini, pengguna RAM dapat menggunakan fitur langganan sisi server IoT Platform. Jika tidak, koneksi gagal. Untuk informasi lebih lanjut, lihat Pemetaan antara Operasi API IoT Platform dan Kebijakan RAM.
Untuk meningkatkan keamanan data, kami sarankan menggunakan Peran RAM untuk memberi otorisasi kepada pengguna RAM agar menggunakan fitur langganan sisi server. Untuk informasi lebih lanjut, lihat bagian berikutnya.
```
userName = clientId|iotInstanceId=${iotInstanceId},authMode=aksign,signMethod=hmacsha1,consumerGroupId=${consumerGroupId},authId=${accessKey},timestamp=1573489088171|
password = signMethod(stringToSign, accessSecret)
```

Jika menggunakan pengguna RAM yang diberi otorisasi oleh Peran RAM, Anda harus mengonfigurasi parameter otentikasi berikut:

Catatan

Selain pengguna RAM dari akun Alibaba Cloud tempat instance IoT Platform berada, Anda dapat menggunakan Peran RAM untuk memberi otorisasi kepada pengguna RAM dari akun Alibaba Cloud lain untuk menggunakan fitur langganan sisi server. Untuk informasi lebih lanjut tentang cara menggunakan Peran RAM untuk memberi otorisasi kepada pengguna RAM agar menggunakan fitur langganan sisi server IoT Platform, lihat Memberi Otorisasi kepada Pengguna RAM Akun Alibaba Cloud Saat Ini untuk Menggunakan Langganan Sisi Server dan Memberi Otorisasi kepada Pengguna RAM Akun Lain untuk Menggunakan Langganan Sisi Server.

userName = clientId|iotInstanceId=${iotInstanceId},authMode=ststoken,securityToken=${SecurityToken},signMethod=hmacsha1,consumerGroupId=${consumerGroupId},authId=${accessKey},timestamp=1573489088171|
password = signMethod(stringToSign, accessSecret)

Tabel 1. Parameter dalam userName

Parameter	Diperlukan	Deskripsi
clientId	Ya	ID klien. Anda harus menentukan ID kustom. ID harus memiliki panjang 1 hingga 64 karakter. Kami sarankan Anda menggunakan pengenal unik sebagai ID klien, seperti UUID, alamat MAC, atau alamat IP server tempat klien berjalan. Setelah klien AMQP terhubung ke IoT Platform dan dimulai, lakukan langkah-langkah berikut untuk melihat detail klien: Masuk ke konsol IoT Platform dan klik kartu instance yang ingin Anda kelola. Di panel navigasi sebelah kiri, pilih Message Forwarding > Server-side Subscription. Pada tab Consumer Groups, temukan grup konsumen yang ingin Anda kelola dan klik View di kolom Tindakan. ID setiap klien ditampilkan di tab Consumer Group Status. Anda dapat menggunakan ID klien untuk mengidentifikasi klien dengan mudah.
iotInstanceId	Tidak	ID instance IoT Platform. Anda dapat melihat ID instance di tab Overview di konsol IoT Platform. Jika ID instance ditampilkan, Anda harus menyetel parameter ini ke ID instance. Jika tab Overview tidak ditampilkan atau instance Anda tidak memiliki ID, Anda tidak perlu menentukan parameter ini.
authMode	Ya	Mode otentikasi. Jika Anda menggunakan akun Alibaba Cloud tempat instance IoT Platform berada atau pengguna RAM yang secara langsung diberi izin yang diperlukan dalam akun Alibaba Cloud, gunakan mode `aksign`. Jika Anda menggunakan pengguna RAM yang diberi otorisasi oleh Peran RAM, gunakan mode `ststoken`.
securityToken	Tidak	Penting Parameter ini hanya diperlukan jika Anda menggunakan pengguna RAM yang diberi otorisasi oleh Peran RAM untuk menghubungkan klien AMQP ke IoT Platform. Token Layanan Keamanan (STS) yang ditugaskan kepada pengguna RAM yang mengasumsikan Peran RAM. Anda dapat memanggil operasi AssumeRole untuk mendapatkan token STS. Untuk informasi lebih lanjut, lihat AssumeRole.
signMethod	Ya	Algoritma tanda tangan. Nilai valid: `hmacmd5`, `hmacsha1`, dan `hmacsha256`.
consumerGroupId	Ya	ID grup konsumen instance IoT Platform. Untuk melihat ID grup konsumen, lakukan langkah-langkah berikut: Masuk ke konsol IoT Platform dan klik kartu instance yang ingin Anda kelola. Di panel navigasi sebelah kiri, pilih Message Forwarding > Server-side Subscription. ID grup konsumen ditampilkan di tab Consumer Groups.
authId	Ya	Informasi otentikasi. Jika Anda menggunakan akun Alibaba Cloud tempat instance IoT Platform berada atau pengguna RAM yang secara langsung diberi izin yang diperlukan dalam akun Alibaba Cloud: Setel parameter ini ke ID AccessKey akun Alibaba Cloud atau ID AccessKey pengguna RAM. Masuk ke konsol IoT Platform, gerakkan pointer ke foto profil Anda, lalu klik AccessKey Management. Di halaman yang muncul, dapatkan ID AccessKey. Jika Anda menggunakan pengguna RAM yang diberi otorisasi oleh Peran RAM: Setel parameter ini ke ID AccessKey pengguna RAM yang mengasumsikan Peran RAM.
timestamp	Ya	Waktu saat ini. Timestamp adalah bilangan bulat LONG. Unit: milidetik.

Tabel 2. Parameter dalam password
Parameter	Diperlukan	Deskripsi
signMethod	Ya	Algoritma tanda tangan. Gunakan algoritma tanda tangan yang ditentukan dalam parameter userName untuk menghitung nilai tanda tangan. Kemudian, ubah nilai tersebut menjadi string yang dikodekan Base64.
stringToSign	Ya	String untuk ditandatangani. Urutkan parameter yang harus ditandatangani dalam urutan abjad. Gabungkan kunci dan nilai setiap parameter menggunakan tanda sama dengan (=). Gabungkan parameter menggunakan ampersand (&). Jika Anda menggunakan akun Alibaba Cloud tempat instance IoT Platform berada atau pengguna RAM yang secara langsung diberi izin yang diperlukan dalam akun Alibaba Cloud: Parameter yang harus ditandatangani mencakup `authId` dan `timestamp`. Setel nilainya dalam format `stringToSign = authId=${accessKey}&timestamp=1573489088171`. Jika Anda menggunakan pengguna RAM yang diberi otorisasi oleh Peran RAM: Parameter yang harus ditandatangani mencakup `securityToken`, `authId`, dan `timestamp`. Setel nilainya dalam format `stringToSign = authId=${accessKey}&securityToken=${SecurityToken}&timestamp=1573489088171`.
accessSecret	Ya	Jika Anda menggunakan akun Alibaba Cloud tempat instance IoT Platform berada atau pengguna RAM yang secara langsung diberi izin yang diperlukan dalam akun Alibaba Cloud: Setel parameter ini ke Rahasia AccessKey akun Alibaba Cloud atau Rahasia AccessKey pengguna RAM. Masuk ke konsol IoT Platform, gerakkan pointer ke foto profil Anda, lalu klik AccessKey Management. Di halaman yang muncul, dapatkan Rahasia AccessKey. Jika Anda menggunakan pengguna RAM yang diberi otorisasi oleh Peran RAM: Setel parameter ini ke Rahasia AccessKey pengguna RAM yang mengasumsikan Peran RAM.

Menerima pesan yang didorong oleh IoT Platform

Setelah tautan penerima dibuat antara klien AMQP dan IoT Platform, IoT Platform mendorong pesan ke klien melalui tautan tersebut.

Catatan

Klien hanya dapat menerima pesan jenis yang ditentukan dalam langganan. Jika ingin mengirim pesan atau perintah ke perangkat, panggil operasi yang sesuai berdasarkan kebutuhan bisnis Anda. Untuk informasi lebih lanjut, lihat Daftar Operasi Berdasarkan Fungsi.

Setiap pesan yang didorong oleh IoT Platform ke klien terdiri dari bagian-bagian berikut:

Tubuh pesan. Payload pesan dalam format biner.
Atribut pesan, seperti topik dan ID pesan. Anda dapat memperoleh atribut dari bagian application-properties yang didefinisikan dalam AMQP. Atribut dalam format key:value.
Kunci
Deskripsi
topic
Topik pesan.
messageId
ID pesan.
generateTime
Waktu ketika pesan dihasilkan.
Catatan
Anda tidak dapat menentukan urutan pesan berdasarkan parameter generateTime.

Tanda Terima Pesan:

Klien AMQP mengirim tanda terima ke IoT Platform untuk memberi tahu bahwa pesan diterima. Tanda terima dapat dikirim secara manual atau otomatis. Kami sarankan menggunakan mode otomatis. Untuk informasi lebih lanjut, lihat panduan pengguna klien.

Kebijakan Pesan:

Pesan didorong secara real-time.
Pesan diakumulasikan.
Pesan mungkin tidak dikonsumsi secara real-time karena masalah tertentu. Misalnya, jika konsumen terputus dari IoT Platform atau pesan dikonsumsi dengan kecepatan rendah, pesan diakumulasikan dalam kasus-kasus ini.
- Setelah konsumen yang terputus tersambung kembali ke IoT Platform dan mulai mengonsumsi pesan dengan kecepatan stabil, IoT Platform mendorong pesan yang terakumulasi ke konsumen.
- Jika konsumen gagal mengonsumsi pesan yang didorong, antrian tempat pesan terakumulasi mungkin terblokir. Ketika pesan gagal dikonsumsi, IoT Platform mencoba lagi mendorong pesan yang terakumulasi ke konsumen setelah sekitar 1 menit.

Catatan

Jumlah lalu lintas yang diproses oleh konsumen mungkin berfluktuasi selama periode waktu singkat. Dalam kebanyakan kasus, fluktuasi hilang dalam 10 menit. Jika jumlah permintaan per detik (QPS) tinggi atau pemrosesan pesan membutuhkan banyak sumber daya, kami sarankan meningkatkan jumlah konsumen. Dengan cara ini, Anda dapat mempertahankan tingkat redundansi yang dapat diterima dalam konsumsi pesan.
Ketika IoT Platform meneruskan pesan, pesan mungkin dikirim berulang kali sampai klien mengembalikan Pesan ACK atau pesan kedaluwarsa. Jika beberapa pesan menggunakan ID pesan yang sama, Anda dapat menghapus duplikat pesan berdasarkan ID tersebut.
Untuk informasi lebih lanjut tentang batasan pada pesan, lihat Batasan pada Langganan Sisi Server.
Anda dapat membersihkan pesan yang terakumulasi di konsol IoT Platform. Untuk informasi lebih lanjut, lihat bagian Lihat dan Pantau Grup Konsumen dari topik "Kelola Grup Konsumen".

Urutan Pesan:

Catatan

Urutan pesan tidak dijamin. Oleh karena itu, pesan mungkin tidak diterima berdasarkan urutan waktu ketika pesan dihasilkan.

Pesan Perangkat Upstream dan Downstream:
Pesan yang dikembalikan tidak diurutkan berdasarkan waktu. Anda perlu mengurutkan pesan secara manual.
Sebagai contoh, Anda menerima pesan berikut secara berurutan:
1. Waktu online: 2018-08-31 10:02:28.195
2. Waktu offline: 2018-08-31 10:01:28.195
3. Waktu offline: 2018-08-31 10:03:28.195
Pesan-pesan di atas menunjukkan bahwa perangkat terputus, tersambung kembali, lalu terputus lagi.
Untuk informasi lebih lanjut tentang parameter dalam pesan, lihat Format Data.
Jenis Pesan Lainnya:
Anda harus menambahkan nomor urut ke setiap pesan di lapisan aplikasi. Berdasarkan nomor urut pesan yang diterima, IoT Platform menggunakan algoritma idempoten untuk memeriksa apakah pesan perlu diproses.

Contoh

Anda dapat menggunakan salah satu SDK AMQP spesifik bahasa pemrograman berikut untuk menghubungkan klien ke IoT Platform. Untuk informasi lebih lanjut tentang cara mengonfigurasi parameter, lihat bagian Pengaturan Koneksi dari topik ini.

Penting

Kami sarankan menggunakan SDK AMQP yang disediakan oleh IoT Platform. Alibaba Cloud tidak menyediakan dukungan teknis untuk SDK AMQP yang dikembangkan sendiri.

Saat menghubungkan klien ke IoT Platform, Anda mungkin menerima kode kesalahan terkait pesan. Untuk informasi lebih lanjut, lihat bagian Kode Kesalahan Terkait Pesan dari topik "Log IoT Platform".

Kunci	Deskripsi
topic	Topik pesan.
messageId	ID pesan.
generateTime	Waktu ketika pesan dihasilkan. Catatan Anda tidak dapat menentukan urutan pesan berdasarkan parameter generateTime.