IoT Platform:Koneksi dan komunikasi melalui HTTPS

Penggunaan dan batasan

• Komunikasi HTTPS hanya didukung di wilayah China (Shanghai).
• Hanya wilayah China (Shanghai) yang mendukung koneksi HTTPS berdurasi pendek. Status online dan offline perangkat terlihat di Konsol IoT Platform. Berlangganan perubahan status perangkat melalui langganan sisi server AMQP.
• Hanya perangkat yang terhubung langsung yang dapat berkomunikasi melalui HTTPS. Perangkat gateway dan perangkat sub tidak didukung.
• Dirancang untuk pelaporan data sederhana. Muatan (payload) unggah data dibatasi hingga 128 KB.
• Topik mengikuti format topik MQTT dan dapat digunakan kembali dari koneksi MQTT. Untuk melaporkan data, kirim permintaan POST ke ${endpoint}/topic/${topic}. Parameter string kueri (?query_String=xxx) tidak didukung.
• Koneksi HTTPS hanya mendukung metode permintaan POST.
• Token otentikasi berlaku selama tujuh hari. Aplikasi Anda harus menangani masa kedaluwarsa token dan melakukan otentikasi ulang.

Alur koneksi

Alur koneksi terdiri dari dua langkah: otentikasi perangkat untuk memperoleh token, lalu penggunaan token tersebut untuk melaporkan data.

1. Lakukan otentikasi perangkat untuk memperoleh token.

   Permintaan otentikasi perangkat:

   POST /auth HTTP/1.1
   Host: ${YourEndpoint}
   Content-Type: application/json
   Content-Length: 214
   body: {"version":"default","clientId":"mylight1000002","signmethod":"hmacsha1","sign":"4870141D4067227128CBB4377906C3731CAC221C","productKey":"ZG1EvTE****","deviceName":"NlwaSPXsCpTQuh8FxBGH","timestamp":"1501668289957"}

   Tabel 1. Deskripsi parameter

   Parameter	Deskripsi
   Method	Metode permintaan. Hanya POST yang didukung.
   URL	URL. Hanya HTTPS. Nilai: /auth.
   Host	Titik akhir HTTP. Dapatkan titik akhir dari Lihat dan konfigurasi titik akhir instans.
   Content-Type	Format encoding data. Hanya application/json yang didukung. Format lain akan mengembalikan error parameter.
   Content-Length	Panjang body pesan HTTP. Penting HTTP/1.1+ menyertakan Content-Length secara default; HTTP/1.0 tidak. Sertakan bidang Content-Length saat melakukan otentikasi melalui HTTP. Nilai Content-Length harus persis sesuai dengan panjang body. Ketidaksesuaian akan menyebabkan kegagalan penguraian body dan otentikasi gagal.
   body	Informasi otentikasi perangkat dalam format JSON. Parameter dijelaskan dalam tabel parameter body.

   Tabel 2. Parameter body

   Nama bidang	Wajib	Deskripsi
   productKey	Ya	ProductKey perangkat. Temukan di halaman Device Details di instans yang sesuai.
   deviceName	Ya	Nama perangkat. Temukan di halaman Device Details di Konsol IoT Platform.
   clientId	Ya	ID klien. Maksimal 64 karakter. Gunakan alamat MAC atau nomor seri (SN) sebagai clientId.
   timestamp	Tidak	Timestamp dalam milidetik sejak 1 Januari 1970 (UTC). Permintaan kedaluwarsa 15 menit setelah timestamp ini.
   sign	Ya	Signature. Format signature: hmacmd5(DeviceSecret,content). content adalah semua parameter (kecuali version, sign, dan signmethod) yang diurutkan secara alfabetis dan digabung tanpa pemisah. Contoh signature: Dengan clientId = 127.0.0.1, deviceName = http_test, productKey = a1FHTWxQ****, timestamp = 1567003778853, signmethod = hmacmd5, deviceSecret = 89VTJylyMRFuy2T3sywQGbm5Hmk1****, maka signature-nya adalah: hmacmd5("89VTJylyMRFuy2T3sywQGbm5Hmk1****","clientId127.0.0.1deviceNamehttp_testproductKeya1FHTWxQ****timestamp1567003778853").toHexString(); Fungsi toHexString() mengonversi data biner menjadi string heksadesimal yang tidak membedakan huruf besar/kecil. Misalnya, array desimal [60 68 -67 -7 -17 99 30 69 117 -54 -58 -58 103 -23 113 71] dikonversi menjadi: 3C44BDF9EF631E4575CAC6C667E97147.
   signmethod	Tidak	Algoritma penandatanganan. Nilai yang valid: hmacmd5, hmacsha1. Default: hmacmd5.
   version	Tidak	Nomor versi. Default: default.

   Tanggapan otentikasi berhasil:

   body:
   {
     "code": 0,
     "message": "success",
     "info": {
       "token":  "6944e5bfb92e4d4ea3918d1eda39****"
     }
   }

   Catatan

   • Simpan token yang dikembalikan secara lokal.
   • Sertakan token dalam setiap permintaan pelaporan data. Jika token kedaluwarsa, lakukan otentikasi ulang untuk memperoleh token baru.

   Tabel 3. Kode error

   code	message	Keterangan
   10000	common error	Error tidak dikenal.
   10001	param error	Parameter permintaan tidak valid.
   20000	auth check error	Otentikasi perangkat gagal.
   20004	update session error	Pembaruan gagal.
   40000	request too many	Jumlah permintaan melebihi batas. Throttling dipicu.

2. Laporkan data.

   Perangkat mengirim data ke topik dengan izin Publish. Topik kustom didukung.

   Sebagai contoh, jika topiknya adalah /${YourProductKey}/${YourDeviceName}/pub, nama perangkatnya adalah device123, dan ProductKey produknya adalah a1GFjLP****, Anda dapat memanggil URL https://iot-as-http.cn-shanghai.aliyuncs.com/topic/a1GFjLP****/device123/pub untuk melaporkan data.

   Permintaan pelaporan data:

   POST /topic/${topic} HTTP/1.1
   Host: ${YourEndpoint}
   password:${token}
   Content-Type: application/octet-stream
   Content-Length: 53
   body: ${your_data}

   Tabel 4. Parameter pelaporan data

   Parameter	Deskripsi
   Method	Metode permintaan. Hanya POST yang didukung.
   URL	/topic/${topic}. Ganti ${topic} dengan topik tujuan. Hanya HTTPS.
   Host	Alamat titik akhir.
   password	Parameter header. Atur ke token yang dikembalikan oleh operasi auth.
   Content-Type	Format encoding data. Hanya application/octet-stream yang didukung. Format lain akan mengembalikan error parameter.
   Content-Length	Panjang entitas pesan HTTP.
   body	Data yang akan dikirim ke ${topic}.

   Tanggapan berhasil:

   body:
   {
     "code": 0,
     "message": "success",
     "info": {
       "messageId": 892687****47040
     }
   }

   Tabel 5. Kode error

   code	message	Keterangan
   10000	common error	Error tidak dikenal.
   10001	param error	Parameter permintaan tidak valid.
   20001	token is expired	Token telah kedaluwarsa. Panggil kembali operasi auth untuk memperoleh token baru.
   20002	token is null	Token tidak ditemukan di header permintaan.
   20003	check token error	Gagal mengambil informasi identitas dari token. Panggil kembali operasi auth untuk memperoleh token baru.
   30001	publish message error	Gagal melaporkan data.
   40000	request too many	Jumlah permintaan melebihi batas. Throttling dipicu.

Contoh

Untuk menghubungkan klien HTTP ke IoT Platform, ikuti langkah-langkah dalam Hubungkan klien HTTP.