Hubungkan Device ke IoT Platform lewat HTTPS dengan Token Auth - IoT Platform

Anda dapat menghubungkan perangkat ke IoT Platform melalui HTTPS. Topik ini menjelaskan cara menghubungkan perangkat ke IoT Platform menggunakan protokol HTTPS.

Catatan penggunaan dan batasan

Anda hanya dapat menghubungkan perangkat ke IoT Platform melalui HTTPS di wilayah China (Shanghai).
Koneksi singkat melalui HTTPS antara perangkat dan IoT Platform hanya dapat dibuat di wilayah China (Shanghai). Anda dapat melihat perubahan status perangkat dengan koneksi HTTPS singkat di konsol IoT Platform ketika perangkat terhubung atau memutuskan koneksi dari IoT Platform. Anda juga dapat mengonfigurasi langganan server-sisi Protokol Pengantrean Pesan Lanjutan (AMQP) untuk menerima pesan tentang perubahan status perangkat.
Hanya perangkat yang terhubung langsung ke IoT Platform yang dapat dihubungkan melalui HTTPS. Gateway atau sub-perangkat tidak dapat dihubungkan ke IoT Platform melalui HTTPS.
Koneksi melalui HTTPS digunakan untuk perangkat mengirimkan data. Perangkat dapat mengirimkan maksimum 128 KB data dalam satu waktu.
Topik HTTPS dan topik MQTT memiliki standar yang sama. Jika Anda menghubungkan perangkat ke IoT Platform melalui HTTPS, Anda dapat menggunakan topik MQTT untuk komunikasi antara perangkat dan IoT Platform. Ketika perangkat terhubung ke IoT Platform melalui HTTPS, data dikirimkan ke topik dalam format ${endpoint}/topic/${topic}. Format ?query_String=xxx tidak didukung.
Hanya metode permintaan POST yang didukung.
Token yang diterima selama autentikasi perangkat kedaluwarsa setelah periode tertentu. Masa berlaku saat ini adalah tujuh hari. Pastikan Anda menentukan logika untuk memproses token yang kedaluwarsa.

Proses

Untuk mengirimkan data, Anda harus mengautentikasi perangkat untuk mendapatkan token perangkat, lalu gunakan token tersebut.

Autentikasi perangkat untuk mendapatkan token perangkat.

Permintaan autentikasi:

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. Tabel berikut menjelaskan parameter.
Parameter	Deskripsi
Metode	Metode permintaan. Nilai valid: POST.
URL	URL. Hanya HTTPS yang didukung. Nilai valid: /auth.
Host	Titik akhir dari instansi publik atau instansi Enterprise Edition tempat Anda ingin menghubungkan perangkat Anda melalui HTTP. Untuk informasi lebih lanjut, lihat Kelola titik akhir instansi.
Content-Type	Jenis MIME (Multipurpose Internet Mail Extensions) dari data upstream yang dikirim oleh perangkat ke IoT Platform. Nilai valid: application/json. Jika jenis MIME lain ditentukan, akan terjadi kesalahan.
Content-Length	Panjang badan pesan HTTP. Penting Jika Anda menggunakan HTTP/1.1 atau yang lebih baru, parameter Content-Length secara default disertakan dalam permintaan. Jika Anda menggunakan HTTP/1.0 atau yang lebih lama, parameter ini tidak disertakan dalam permintaan secara default. Jika Anda menggunakan protokol HTTP untuk mengautentikasi perangkat, Anda harus menentukan parameter Content-Length. Nilai dari Content-Length harus sama dengan panjang sebenarnya dari badan pesan. Jika tidak, badan pesan tidak dapat diuraikan dan autentikasi gagal.
body	Informasi perangkat untuk autentikasi dalam format JSON. Untuk informasi lebih lanjut, lihat Parameter dalam badan pesan.

Tabel 2. Parameter dalam badan pesan
Parameter	Diperlukan	Deskripsi
productKey	Ya	ProductKey dari produk tempat perangkat milik. Anda dapat masuk ke konsol IoT Platform dan mendapatkan ProductKey pada halaman Device Details dari instansi.
deviceName	Ya	DeviceName dari perangkat. Anda dapat masuk ke konsol IoT Platform dan mendapatkan DeviceName pada halaman Device Details dari instansi.
clientId	Ya	ID klien. ID klien harus memiliki panjang 1 hingga 64 karakter. Kami merekomendasikan Anda menggunakan alamat MAC atau SN perangkat sebagai nilai parameter clientId.
timestamp	Tidak	Timestamp. Permintaan valid selama 15 menit setelah timestamp dihasilkan. Timestamp dalam format numerik di mana nilainya mewakili jumlah milidetik yang telah berlalu sejak pukul 00:00:00 Kamis, 1 Januari 1970.
sign	Ya	Tanda tangan. Tanda tangan dihitung menggunakan fungsi `hmacmd5(deviceSecret,content)`. Nilai dari content adalah string yang berisi semua parameter yang dikirimkan perangkat ke IoT Platform, kecuali parameter version, sign, dan signmethod. Parameter yang dikirimkan diurutkan secara alfabetis dan digabungkan tanpa simbol penggabungan. Contoh: Jika parameter clientId diatur ke 127.0.0.1, parameter deviceName diatur ke http_test, parameter productKey diatur ke a1FHTWxQ**, parameter timestamp diatur ke 1567003778853, parameter signmethod diatur ke hmacmd5, dan parameter deviceSecret diatur ke 89VTJylyMRFuy2T3sywQGbm5Hmk1, gunakan fungsi berikut untuk menghitung tanda tangan: `hmacmd5("89VTJylyMRFuy2T3sywQGbm5Hmk1","clientId127.0.0.1deviceNamehttp_testproductKeya1FHTWxQ**timestamp1567003778853").toHexString();` Metode `toHexString()` digunakan untuk mengonversi serangkaian empat digit biner yang membentuk hasil biner menjadi string heksadesimal. String heksadesimal tidak peka huruf besar/kecil. Misalnya, array yang mencakup hasil dalam format desimal adalah [60 68 -67 -7 -17 99 30 69 117 -54 -58 -58 103 -23 113 71]. Array tersebut dikonversi menjadi string heksadesimal berikut: 3C44BDF9EF631E4575CAC6C667E97147.
signmethod	Tidak	Algoritma tanda tangan. Nilai valid: hmacmd5 dan hmacsha1. Nilai default: hmacmd5.
version	Tidak	Nomor versi. Nilai default: default.

Contoh respons:

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

Catatan

Simpan token yang diterima di perangkat.
Token diperlukan setiap kali perangkat mengirimkan data ke IoT Platform. Jika token kedaluwarsa, autentikasi ulang perangkat diperlukan untuk mendapatkan token baru.

Tabel 3. Kode kesalahan
code	message	Deskripsi
10000	kesalahan umum	Pesan kesalahan yang dikembalikan karena kesalahan tidak dikenal telah terjadi.
10001	kesalahan parameter	Pesan kesalahan yang dikembalikan karena satu atau lebih parameter tidak valid.
20000	kesalahan pengecekan autentikasi	Pesan kesalahan yang dikembalikan karena perangkat gagal diautentikasi.
20004	kesalahan pembaruan sesi	Pesan kesalahan yang dikembalikan karena perangkat gagal diperbarui.
40000	permintaan terlalu banyak	Pesan kesalahan yang dikembalikan karena jumlah permintaan yang dapat diproses oleh IoT Platform melebihi ambang batas throttling.

Kirimkan data.

Perangkat hanya dapat mengirimkan data ke topik tempat perangkat memiliki izin Publish. Topik kustom dapat digunakan.

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

Contoh permintaan:

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

Tabel 4. Parameter
Parameter	Deskripsi
Metode	Metode permintaan. Nilai valid: POST.
URL	`/topic/${topic}`. Ganti variabel `${topic}` dengan topik ke mana data dikirim. Hanya HTTPS yang didukung.
Host	Titik akhir.
password	Parameter ini disertakan dalam header permintaan. Atur parameter ini ke token yang dikembalikan setelah Anda memanggil operasi auth untuk mengautentikasi perangkat.
Content-Type	Jenis MIME dari data upstream yang dikirimkan perangkat ke IoT Platform. Nilai valid: application/octet-stream. Jika jenis MIME lain ditentukan, akan terjadi kesalahan.
Content-Length	Panjang badan pesan HTTP.
body	Data yang dikirimkan ke topik yang ditentukan. Untuk informasi lebih lanjut tentang format data, lihat Topik.

Contoh respons:

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

Tabel 5. Kode kesalahan
code	message	Deskripsi
10000	kesalahan umum	Pesan kesalahan yang dikembalikan karena kesalahan tidak dikenal telah terjadi.
10001	kesalahan parameter	Pesan kesalahan yang dikembalikan karena satu atau lebih parameter tidak valid.
20001	token telah kedaluwarsa	Pesan kesalahan yang dikembalikan karena token telah kedaluwarsa. Anda harus memanggil operasi auth untuk mengautentikasi ulang perangkat dan mendapatkan token baru.
20002	token kosong	Pesan kesalahan yang dikembalikan karena tidak ada token yang ditentukan dalam header permintaan.
20003	kesalahan pengecekan token	Pesan kesalahan yang dikembalikan karena IoT Platform gagal mendapatkan informasi identitas perangkat berdasarkan token. Anda harus memanggil operasi auth untuk mengautentikasi ulang perangkat dan mendapatkan token baru.
30001	kesalahan pengiriman pesan	Pesan kesalahan yang dikembalikan karena perangkat gagal mengirimkan data.
40000	permintaan terlalu banyak	Pesan kesalahan yang dikembalikan karena jumlah permintaan yang dapat diproses oleh IoT Platform melebihi ambang batas throttling.

Contoh nilai

Untuk informasi lebih lanjut tentang cara menghubungkan klien HTTP dengan IoT Platform, lihat Akses IoT Platform menggunakan HTTP.