Properti perangkat, peristiwa, dan layanan - IoT Platform

Setelah mendefinisikan model Thing Specification Language (TSL) untuk suatu produk, perangkat dalam produk tersebut dapat mengirimkan data properti dan data peristiwa ke IoT Platform sesuai dengan model TSL. Anda juga dapat mengirimkan perintah ke perangkat untuk memodifikasi properti atau memanggil layanan melalui konsol manajemen IoT Platform.

Untuk detail lebih lanjut tentang format data properti, peristiwa, dan layanan yang didefinisikan dalam model TSL, lihat Apa itu model TSL?.

Perangkat dapat mengirimkan data dalam format JSON Alink ke IoT Platform atau menggunakan mode kustom. Kami merekomendasikan agar perangkat dikonfigurasi untuk mengirimkan data dalam format JSON Alink.

JSON Alink: Format data standar yang ditentukan oleh IoT Connectivity Alliance (ICA). Perangkat menghasilkan data dalam format JSON Alink lalu mengirimkannya ke IoT Platform. Untuk informasi lebih lanjut, lihat contoh dalam topik ini.
Kustom: Jika mode kustom digunakan, perangkat dapat mengirimkan data mentah seperti aliran data biner ke IoT Platform. Kemudian, IoT Platform akan menguraikan data mentah tersebut ke format JSON Alink berdasarkan skrip kustom yang Anda kirimkan. Untuk informasi lebih lanjut, lihat Penguraian Pesan. Data yang dihasilkan oleh IoT Platform dalam format JSON Alink kemudian dikonversi menjadi data biner berdasarkan skrip yang Anda kirimkan dan dikirimkan kembali ke perangkat.

Penting

Jika data TSL bertipe float atau double, nilai parameter yang sesuai dengan data TSL harus memiliki setidaknya satu tempat desimal. Contoh: 10.0 dan 11.1.
Perangkat hanya dapat mengirimkan data properti TSL dan peristiwa TSL dalam rentang 24 jam ke depan. Nilai waktu yang ditentukan saat perangkat mengirimkan nilai properti atau peristiwa harus berada dalam rentang 24 jam setelah waktu pengiriman sebenarnya. Jika batas waktu terlampaui, pengiriman gagal.
ID setiap pesan untuk komunikasi hulu atau hilir harus unik dalam pesan harian perangkat. Parameter id menentukan ID pesan.
ID dari setiap pesan downstream yang dikirim dari IoT Platform digunakan untuk mencocokkan setiap respons yang dikembalikan dari perangkat secara asinkron. IoT Platform harus memastikan bahwa ID dari setiap pesan downstream unik dalam pesan harian sebuah perangkat. Pastikan bahwa ID dari setiap pesan upstream yang dikirim dari perangkat unik dalam pesan harian perangkat tersebut.

Perangkat mengirimkan data properti ke IoT Platform

Untuk informasi lebih lanjut tentang cara perangkat mengirimkan data properti, lihat Kirim Properti atau Peristiwa Perangkat.

Topik dan format data yang digunakan untuk mengirim data dari perangkat ke IoT Platform:

Kustom

Topik

Format data

Topik permintaan: /sys/${productKey}/${deviceName}/thing/model/up_raw

Permintaan berisi data mentah yang harus dikirimkan perangkat ke IoT Platform.

Catatan

Data heksadesimal dikirimkan melalui Message Queuing Telemetry Transport (MQTT).
Data yang dikirimkan harus berisi parameter method yang menentukan metode permintaan. Nilai parameter tersebut harus sama dengan metode permintaan yang Anda tentukan dalam skrip penguraian data. Sebagai contoh, dalam topik Contoh skrip JavaScript, data yang harus dikirimkan perangkat ke IoT Platform harus berisi parameter method. Nilai parameter tersebut harus sama dengan nilai thing.event.property.post yang Anda tentukan untuk parameter ALINK_PROP_REPORT_METHOD dalam skrip penguraian data.

Contoh:

0x00002233441232013fa00000

Topik respons: /sys/${productKey}/${deviceName}/thing/model/up_raw_reply

Contoh respons:

Contoh respons sukses

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "version": "1.0"
}

Contoh respons gagal

{
    "code": 6813,
    "data": {},
    "id": "123",
    "message": "topik ilegal",
    "version": "1.0"
}

JSON Alink

Topik

Format data

Topik permintaan: /sys/${productKey}/${deviceName}/thing/event/property/post

Contoh permintaan:

{
    "id": "123",
    "version": "1.0",
    "sys":{
        "ack":0
    },
    "params": {
        "Power": {
            "value": "on",
            "time": 1524448722000
        },
        "WF": {
            "value": 23.6,
            "time": 1524448722000
        }
    },
    "method": "thing.event.property.post"
}

Topik respons: /sys/${productKey}/${deviceName}/thing/event/property/post_reply

Contoh respons:

Contoh respons sukses

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "method": "thing.event.property.post",
    "version": "1.0"
}

Contoh respons gagal

{
    "code": 6813,
    "data": {},
    "id": "123",
    "message": "format hasil salah!",
    "method": "thing.event.property.post",
    "version": "1.0"
}

Parameter:

Tabel 1. Parameter Permintaan
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat.
version	String	Nomor versi protokol. Tetapkan nilainya menjadi 1.0.
sys	Object	Parameter untuk fitur tambahan. Nilainya berisi bidang untuk setiap fitur. Catatan Jika tidak ada fitur tambahan yang dikonfigurasikan saat Anda menggunakan SDK perangkat untuk mengembangkan fitur perangkat, parameter ini tidak tersedia. Fitur tambahan menggunakan konfigurasi default.
ack	Integer	Bidang fitur tambahan dalam parameter sys. Bidang ini menentukan apakah IoT Platform mengembalikan data respons untuk permintaan pendaftaran. Nilai valid: 1: IoT Platform mengembalikan data respons. 0: IoT Platform tidak mengembalikan data respons. Penting Untuk informasi lebih lanjut tentang parameter ini, lihat Contoh penggunaan model TSL. Jika fitur tidak dikonfigurasikan, parameter ini tidak tersedia. Secara default, IoT Platform mengembalikan data respons untuk permintaan pendaftaran.
method	String	Metode permintaan. Contoh: thing.event.property.post
params	Object	Data properti yang harus dikirimkan perangkat dalam permintaan. Dalam contoh sebelumnya, perangkat mengirimkan informasi tentang properti Power (catu daya) dan WF (arus kerja). Informasi tersebut berisi nilai properti dan timestamp. Timestamp menunjukkan titik waktu ketika properti dikirimkan. Jika Anda hanya menentukan nilai properti, informasi tersebut tidak berisi timestamp. Contoh: `"params": { "Power": "on", "WF": 23.6 }` Jika Anda menggunakan properti modul kustom, pengenal setiap properti berada dalam format ${Pengenal Modul}:${Pengenal Properti}. Titik dua (:) digunakan untuk menghubungkan kedua bagian ekspresi ini. Contoh: `"test:Power": { "value": "on", "time": 1524448722000 }`
time	Long	Timestamp UTC ketika properti dikirimkan. Unit: milidetik. Parameter ini opsional. Anda dapat menentukan apakah akan menentukan timestamp dalam permintaan berdasarkan kebutuhan bisnis Anda. Jika perangkat sering mengirimkan pesan ke IoT Platform, kami sarankan Anda menentukan timestamp dalam permintaan untuk membantu mengidentifikasi urutan pesan. Jika permintaan berisi parameter time, IoT Platform menyimpan nilai parameter tersebut sebagai titik waktu ketika properti dikirimkan. Jika permintaan tidak berisi parameter time, IoT Platform secara otomatis menghasilkan timestamp untuk mencatat titik waktu ketika properti dikirimkan.
value	Object	Nilai properti yang dikirimkan oleh perangkat. Parameter ini hanya diperlukan jika Anda menentukan parameter time. Anda juga dapat mengirimkan nilai properti tanpa menentukan parameter time.

Tabel 2. Parameter Respons
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat.
code	Integer	Kode status. Untuk informasi lebih lanjut, lihat Kode umum pada perangkat. Catatan IoT Platform memverifikasi semua properti yang dikirimkan oleh perangkat. IoT Platform memeriksa apakah format setiap properti sesuai dengan format yang didefinisikan dalam model TSL. Jika properti tidak valid, IoT Platform membuang properti tersebut dan mengembalikan kode kesalahan.
data	Object	Jika permintaan berhasil, parameter ini dibiarkan kosong.
pesan	String	Pesan respons. Jika permintaan berhasil, pesan "success" akan ditampilkan.
method	String	Metode permintaan dalam respons. Nilai parameter ini sama dengan nilai parameter method dalam permintaan.
version	String	Nomor versi protokol. Nilai parameter ini sama dengan nilai parameter version dalam permintaan.

Kode Kesalahan: IoT Platform dapat mengembalikan kode kesalahan ke perangkat. Untuk informasi lebih lanjut, lihat Kode Kesalahan untuk Perangkat.

Penerusan Data: IoT Platform dapat meneruskan data properti yang dikirimkan oleh perangkat ke server Anda atau layanan lainnya di Alibaba Cloud dengan menggunakan fitur Langganan Sisi Server atau Penerusan Data. Untuk informasi lebih lanjut tentang topik dan format data terkait, lihat Kirim Properti Perangkat.

Konfigurasi properti perangkat

Anda dapat memanggil operasi SetDeviceProperty atau SetDevicesProperty untuk mengirimkan perintah ke perangkat guna memodifikasi propertinya. Untuk informasi lebih lanjut tentang cara mengonfigurasi properti perangkat, lihat Memanggil Layanan Perangkat atau Mengonfigurasi Properti Perangkat.

Penting

Pesan sukses hanya menunjukkan bahwa perangkat telah menerima perintah untuk mengubah nilai properti dari IoT Platform. Perangkat mungkin belum menjalankan perintah tersebut. Setelah Link SDK yang digunakan untuk mengonfigurasi perangkat merespons permintaan konfigurasi properti, perangkat harus mengirimkan nilai properti terbaru untuk membuktikan bahwa nilai properti telah diubah. Untuk informasi lebih lanjut, lihat bagian "Perangkat Mengirimkan Data Properti ke IoT Platform" dari topik ini.

Topik dan format data yang digunakan untuk mengirim data dari IoT Platform ke perangkat:

Format data (dari IoT Platform ke perangkat)	Topik permintaan dan respons
Kustom	Topik permintaan: `/sys/${productKey}/${deviceName}/thing/model/down_raw` Topik respons: `/sys/${productKey}/${deviceName}/thing/model/down_raw_reply`
JSON Alink	Topik permintaan: `/sys/${productKey}/${deviceName}/thing/service/property/set` Topik respons: `/sys/${productKey}/${deviceName}/thing/service/property/set_reply`

Contoh Permintaan:

{
    "id": "123",
    "version": "1.0",
    "params": {
        "temperature": "30.5"
    },
    "method": "thing.service.property.set"
}

Contoh Respons:

Contoh Respons Sukses

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "version": "1.0"
}

Contoh Respons Gagal

{
    "code": 9201,
    "data": {},
    "id": "123",
    "message": "perangkat offLine",
    "version": "1.0"
}

Parameter:

Tabel 3. Parameter Permintaan
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat.
version	String	Nomor versi protokol. Tetapkan nilainya menjadi 1.0.
params	Object	Properti yang ingin Anda ubah. Dalam contoh sebelumnya, { "temperature": "30.5" } menunjukkan bahwa Anda mengatur properti suhu menjadi 30.5. Jika properti yang ingin Anda ubah adalah properti modul kustom, masukkan pengenal properti dalam format ${Pengenal Modul}:${Pengenal Properti}. Contoh: `{ "test:temperature": "30,5" }`. Tanda titik dua (:) digunakan untuk menghubungkan dua bagian dari ekspresi ini.
method	String	Metode permintaan. Contoh: thing.service.property.set

Tabel 4. Parameter Respons
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat.
code	Integer	Kode status. Untuk informasi lebih lanjut, lihat Kode umum pada perangkat.
data	Object	Jika permintaan berhasil, parameter ini dibiarkan kosong.
pesan	String	Pesan respons. Jika permintaan berhasil, pesan "success" akan ditampilkan.
version	String	Nomor versi protokol. Nilai parameter ini sama dengan nilai parameter version dalam permintaan.

Kode Kesalahan: IoT Platform mungkin mengembalikan kode kesalahan ke perangkat. Untuk informasi lebih lanjut, lihat Kode Kesalahan untuk Perangkat.

Penerusan Data: IoT Platform dapat meneruskan hasil modifikasi properti yang dikirimkan oleh perangkat ke server Anda atau layanan lainnya di Alibaba Cloud dengan menggunakan fitur langganan sisi server atau penerusan data. Untuk informasi lebih lanjut tentang topik dan format data terkait, lihat Kirim Respons ke Permintaan Downstream.

Perangkat mengirimkan peristiwa ke IoT Platform

Untuk informasi lebih lanjut tentang cara perangkat mengirimkan peristiwa, lihat Kirim Properti atau Peristiwa Perangkat.

Topik dan format data yang digunakan untuk mengirim data dari perangkat ke IoT Platform:

Kustom

Topik

Format data

Topik permintaan: /sys/${productKey}/${deviceName}/thing/model/up_raw

Permintaan berisi data mentah yang harus dikirimkan perangkat ke IoT Platform.

Catatan

Data yang dikirimkan harus berisi parameter method yang menentukan metode permintaan. Nilai parameter tersebut harus sama dengan metode permintaan yang Anda tentukan dalam skrip penguraian data. Sebagai contoh, Anda dapat menetapkan parameter method menjadi thing.event.${tsl.event.identifier}.post.

Contoh:

0xff0000007b00

Topik respons: /sys/${productKey}/${deviceName}/thing/model/up_raw_reply

Contoh respons:

Contoh respons sukses

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "version": "1.0"
}

Contoh respons gagal

{
    "code": 6813,
    "data": {},
    "id": "123",
    "message": "topik ilegal",
    "version": "1.0"
}

JSON Alink

Modul TSL

Topik

Format data

Modul default

Topik permintaan: /sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post
Topik respons: /sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post_reply

Contoh permintaan dalam format JSON Alink jika modul TSL default digunakan:

{
    "id": "123",
    "version": "1.0",
    "sys":{
        "ack":0
    },
    "params": {
        "value": {
            "Power": "on",
            "WF": "2"
        },
        "time": 1524448722000
    },
    "method": "thing.event.${tsl.event.identifier}.post"
}

Contoh respons dalam format JSON Alink:

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "method": "thing.event.${tsl.event.identifier}.post",
    "version": "1.0"
}

Jika permintaan gagal, {} dikembalikan.

Modul kustom

Topik permintaan: /sys/${productKey}/${deviceName}/thing/event/${tsl.functionBlockId}:${tsl.event.identifier}/post
Topik respons: /sys/${productKey}/${deviceName}/thing/event/${tsl.functionBlockId}:${tsl.event.identifier}/post_reply

Parameter:

Tabel 5. Parameter Permintaan
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat.
version	String	Nomor versi protokol. Tetapkan nilainya menjadi 1.0.
sys	Object	Parameter untuk fitur tambahan. Nilainya berisi bidang untuk setiap fitur. Catatan Jika tidak ada fitur tambahan yang dikonfigurasikan saat Anda menggunakan SDK perangkat untuk mengembangkan fitur perangkat, parameter ini tidak tersedia. Fitur tambahan menggunakan konfigurasi default.
ack	Integer	Bidang fitur tambahan dalam parameter sys. Bidang ini menentukan apakah IoT Platform mengembalikan data respons untuk permintaan pendaftaran. Nilai valid: 1: IoT Platform mengembalikan data respons. 0: IoT Platform tidak mengembalikan data respons. Penting Untuk informasi lebih lanjut tentang parameter ini, lihat Contoh penggunaan model TSL. Jika fitur tidak dikonfigurasikan, parameter ini tidak tersedia. Secara default, IoT Platform mengembalikan data respons untuk permintaan pendaftaran.
method	String	Metode permintaan. Modul default Tetapkan nilainya menjadi `thing.event.${tsl.event.identifier}.post`. Modul kustom Tetapkan nilainya menjadi `thing.event.${tsl.functionBlockId}:${tsl.event.identifier}.post`. Catatan `${tsl.event.identifier}` menentukan pengenal peristiwa yang didefinisikan dalam model TSL, dan `${tsl.functionBlockId}` menentukan pengenal modul kustom. Untuk informasi lebih lanjut, lihat Tambahkan fitur TSL.
params	Object	Parameter peristiwa.
value	Object	Nilai parameter peristiwa. Contoh sebelumnya menunjukkan informasi tentang parameter Power (catu daya) dan WF (arus kerja). `{ "Power": "on", "WF": "2" }`
time	Long	Timestamp UTC ketika peristiwa dikirimkan. Unit: milidetik. Parameter ini opsional. Anda dapat menentukan apakah akan menentukan timestamp dalam permintaan berdasarkan kebutuhan bisnis Anda. Jika perangkat sering mengirimkan pesan ke IoT Platform, kami sarankan Anda menentukan parameter time dalam permintaan untuk membantu mengidentifikasi urutan pesan. Jika permintaan berisi parameter time, IoT Platform menyimpan nilai parameter tersebut sebagai titik waktu ketika peristiwa dikirimkan. Jika permintaan tidak berisi parameter time, IoT Platform secara otomatis menghasilkan timestamp untuk mencatat titik waktu ketika peristiwa dikirimkan.

Tabel 6. Parameter Respons
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat tersebut.
code	Bilangan Bulat	Kode status. Untuk informasi lebih lanjut, lihat Kode umum pada perangkat. Catatan IoT Platform memverifikasi semua peristiwa yang dikirimkan oleh perangkat. IoT Platform memeriksa apakah format data setiap peristiwa sesuai dengan format yang didefinisikan dalam model TSL. Jika suatu peristiwa tidak valid, IoT Platform akan membuangnya dan mengembalikan kode kesalahan.
data	Objek	Jika permintaan berhasil, parameter ini dibiarkan kosong.
pesan	String	Pesan respons. Jika permintaan berhasil, pesan "success" akan ditampilkan.
method	String	Metode permintaan dalam respons. Nilai parameter ini sama dengan nilai parameter method dalam permintaan.
version	String	Nomor versi protokol. Nilai parameter ini sama dengan nilai parameter version dalam permintaan.

Contoh dalam Format JSON Alink: Sebuah peristiwa alarm didefinisikan dalam model TSL. Untuk informasi lebih lanjut, lihat Apa itu Model TSL?

{
    "schema": "https://iot-tsl.oss-cn-shanghai.aliyuncs.com/schema.json",
    "link": "/sys/${productKey}/airCondition/thing/",
    "profile": {
        "productKey": "${productKey}",
        "deviceName": "airCondition"
    },
    "events": [
        {
            "identifier": "alarm",
            "name": "alarm",
            "desc": "Peringatan kipas",
            "type": "alert",
            "required": true,
            "outputData": [
                {
                    "identifier": "errorCode",
                    "name": "Kode kesalahan",
                    "dataType":{
                        "type": "text",
                        "specs": {
                            "length": "255"
                        }
                    }
            ],
            "method": "thing.event.alarm.post"
        }
    ]
}

Perangkat mengirimkan peristiwa dalam permintaan format JSON Alink berikut.

{
    "id": "123",
    "version": "1.0",
    "params": {
        "value": {
            "errorCode": "error"
        },
        "time": 1524448722000
    },
    "method": "thing.event.alarm.post"
}

Kode Kesalahan: IoT Platform mungkin mengembalikan kode kesalahan ke perangkat. Untuk informasi lebih lanjut, lihat Kode Kesalahan untuk Perangkat.

Penerusan Data: IoT Platform dapat meneruskan informasi peristiwa yang dikirimkan oleh perangkat ke server Anda atau layanan Alibaba Cloud lainnya dengan menggunakan langganan sisi server atau fitur penerusan data. Untuk informasi lebih lanjut tentang topik dan format data terkait, lihat Format Data.

Panggil layanan perangkat dalam mode asinkron

IoT Platform memungkinkan Anda memanggil layanan dalam mode sinkron atau asinkron. Saat mendefinisikan layanan dalam model TSL, Anda harus menentukan mode pemanggilan layanan tersebut. Untuk detail lebih lanjut tentang cara mendefinisikan layanan, lihat Tambahkan Fitur TSL. Informasi lebih lanjut tentang cara memanggil layanan perangkat dapat ditemukan di Memanggil Layanan Perangkat atau Mengonfigurasi Properti Perangkat.

Mode Sinkron: Anda dapat menggunakan operasi InvokeThingService atau InvokeThingsService untuk memanggil layanan perangkat. IoT Platform menggunakan mekanisme komunikasi sinkron Revert-Remote Procedure Call (RRPC) untuk mengirim permintaan ke perangkat. Jika layanan dipanggil dalam mode sinkron, IoT Platform akan berlangganan topik RRPC. Untuk informasi lebih lanjut, lihat Apa itu RRPC?
Mode Asinkron: Anda dapat menggunakan operasi InvokeThingService atau InvokeThingsService untuk memanggil layanan perangkat. IoT Platform mengirim permintaan secara asinkron ke perangkat, dan perangkat mengembalikan respons secara asinkron. Jika layanan dipanggil dalam mode asinkron, IoT Platform akan berlangganan topik respons asinkron.

Topik dan format data yang digunakan untuk mengirim data dari IoT Platform ke perangkat:

Format data (dari IoT Platform ke perangkat)	Topik permintaan dan respons
Kustom	Topik permintaan: `/sys/${productKey}/${deviceName}/thing/model/down_raw` Topik respons: `/sys/${productKey}/${deviceName}/thing/model/down_raw_reply`
JSON Alink	Modul TSL default Topik permintaan: `/sys/${productKey}/${deviceName}/thing/service/${tsl.service.identifier}` Topik respons: `/sys/${productKey}/${deviceName}/thing/service/${tsl.service.identifier}_reply` Modul kustom Topik permintaan: `/sys/${productKey}/${deviceName}/thing/service/${tsl.functionBlockId}:${tsl.service.identifier}` Topik respons: `/sys/${productKey}/${deviceName}/thing/service/${tsl.functionBlockId}:${tsl.service.identifier}_reply`

Contoh Permintaan dalam Format JSON Alink:

{
    "id": "123",
    "version": "1.0",
    "params": {
        "Power": "on",
        "WF": "2"
    },
    "method": "thing.service.${tsl.service.identifier}"
}

Contoh Respons:

Contoh Respons Sukses

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "version": "1.0"
}

Contoh Respons Gagal

{
    "code": 9201,
    "data": {},
    "id": "123",
    "message": "perangkat offLine",
    "version": "1.0"
}

Parameter:

Tabel 7. Parameter Permintaan
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat.
version	String	Nomor versi protokol. Tetapkan nilainya menjadi 1.0.
params	Object	Parameter yang digunakan untuk memanggil layanan. Setiap parameter terdiri dari pengenal layanan dan nilai layanan. Contoh sebelumnya berisi parameter Power (catu daya) dan WF (arus kerja). `{ "Power": "on", "WF": "2" }`
method	String	Metode permintaan. Modul default Tetapkan nilainya menjadi `thing.service.${tsl.service.identifier}`. Modul kustom Tetapkan nilainya menjadi `thing.service.${tsl.functionBlockId}:${tsl.service.identifier}`. Catatan `${tsl.service.identifier}` menentukan pengenal layanan yang didefinisikan dalam model TSL, dan `${tsl.functionBlockId}` menentukan pengenal modul kustom. Untuk informasi lebih lanjut, lihat Tambahkan fitur TSL.

Tabel 8. Parameter Respons
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat.
code	Integer	Kode status. Untuk informasi lebih lanjut, lihat Kode umum pada perangkat.
data	Object	Pesan respons. Nilai parameter ini bervariasi berdasarkan model TSL. Jika layanan tidak mengembalikan respons, parameter ini dibiarkan kosong. Jika layanan mengembalikan respons, data yang dikembalikan sesuai dengan format layanan yang didefinisikan dalam model TSL.
message	String	Pesan respons. Jika permintaan berhasil, pesan "sukses" ditampilkan.
version	String	Nomor versi protokol. Nilai parameter ini sama dengan nilai parameter version dalam permintaan.

Contoh dalam Format JSON Alink: Layanan SetWeight didefinisikan dalam model TSL berikut.

{
    "schema": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json",
    "profile": {
        "productKey": "testProduct01"
    },
    "services": [
        {
            "outputData": [
                {
                    "identifier": "OldWeight",
                    "dataType": {
                        "specs": {
                            "unit": "kg",
                            "min": "0",
                            "max": "200",
                            "step": "1"
                        },
                        "type": "double"
                    },
                    "name": "OldWeight"
                },
                {
                    "identifier": "CollectTime",
                    "dataType": {
                        "specs": {
                            "length": "2048"
                        },
                        "type": "text"
                    },
                    "name": "CollectTime"
                }
            ],
            "identifier": "SetWeight",
            "inputData": [
                {
                    "identifier": "NewWeight",
                    "dataType": {
                        "specs": {
                            "unit": "kg",
                            "min": "0",
                            "max": "200",
                            "step": "1"
                        },
                        "type": "double"
                    },
                    "name": "NewWeight"
                }
            ],
            "method": "thing.service.SetWeight",
            "name": "Set weight",
            "required": false,
            "callType": "async"
        }
    ]
}

Contoh Permintaan dalam Format JSON Alink:

{
    "method": "thing.service.SetWeight",
    "id": "105917531",
    "params": {
        "NewWeight": 100.8
    },
    "version": "1.0"
}

Contoh Respons dalam Format JSON Alink:

{
    "id": "105917531",
    "code": 200,
    "data": {
        "CollectTime": "1536228947682",
        "OldWeight": 100.101
    },
    "message": "success",
    "version": "1.0"
}

Kode Kesalahan: IoT Platform dapat mengembalikan kode kesalahan ke perangkat. Untuk informasi lebih lanjut, lihat Kode Kesalahan untuk Perangkat.

Penerusan Data: IoT Platform dapat meneruskan hasil panggilan asinkron ke server Anda atau layanan lainnya di Alibaba Cloud dengan menggunakan fitur Langganan Sisi Server atau Penerusan Data. Untuk informasi lebih lanjut tentang topik dan format data terkait, lihat Kirim Respons ke Permintaan Downstream.

Gateway mengirimkan beberapa properti dan peristiwa ke IoT Platform secara bersamaan

Sebuah gateway dapat mengirim beberapa properti dan peristiwa ke IoT Platform secara bersamaan. Gateway dapat mengirimkan properti dan peristiwa miliknya sendiri atau milik perangkat sub-yang terhubung ke gateway.

Catatan

Sebuah gateway dapat mengirimkan hingga 200 properti dan 20 peristiwa secara bersamaan.
Sebuah gateway dapat mengirimkan data untuk maksimal 20 perangkat sub-secara bersamaan.

Topik dan format data yang digunakan untuk mengirim data dari gateway ke IoT Platform:

Kustom

Topik

Format data

Topik permintaan: /sys/${productKey}/${deviceName}/thing/model/up_raw

Permintaan berisi data mentah yang harus dikirimkan gateway ke IoT Platform.

Catatan

Contoh:

0xff0000007b00

Topik respons: /sys/${productKey}/${deviceName}/thing/model/up_raw_reply

Contoh respons:

Contoh respons sukses

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "version": "1.0"
}

Contoh respons gagal

{
    "code": 6813,
    "data": {},
    "id": "123",
    "message": "topik ilegal",
    "version": "1.0"
}

JSON Alink

Topik permintaan dan respons

Data permintaan dan data respons

Topik permintaan: /sys/${productKey}/${deviceName}/thing/event/property/pack/post

Contoh permintaan dalam format JSON Alink:

{
    "id": "123",
    "version": "1.0",
    "sys":{
        "ack":0
    },
    "params": {
        "properties": {
            "Power": {
                "value": "on",
                "time": 1524448722000
            },
            "WF": {
                "value": { },
                "time": 1524448722000
            }
        },
        "events": {
            "alarmEvent1": {
                "value": {
                    "param1": "on",
                    "param2": "2"
                },
                "time": 1524448722000
            },
            "alertEvent2": {
                "value": {
                    "param1": "on",
                    "param2": "2"
                },
                "time": 1524448722000
            }
        },
        "subDevices": [
            {
                "identity": {
                    "productKey": "",
                    "deviceName": ""
                },
                "properties": {
                    "Power": {
                        "value": "on",
                        "time": 1524448722000
                    },
                    "WF": {
                        "value": { },
                        "time": 1524448722000
                    }
                },
                "events": {
                    "alarmEvent1": {
                        "value": {
                            "param1": "on",
                            "param2": "2"
                        },
                        "time": 1524448722000
                    },
                    "alertEvent2": {
                        "value": {
                            "param1": "on",
                            "param2": "2"
                        },
                        "time": 1524448722000
                    }
                }
            }
        ]
    },
    "method": "thing.event.property.pack.post"
}

Topik respons: /sys/${productKey}/${deviceName}/thing/event/property/pack/post_reply

Contoh respons dalam format Alink JSON:

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "method": "thing.event.property.pack.post",
    "version": "1.0"
}

Jika permintaan gagal, {} dikembalikan.

Parameter:

Tabel 9. Parameter Permintaan
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat.
version	String	Nomor versi protokol. Atur nilai menjadi 1,0.
sys	Objek	Parameter untuk fitur tambahan. Nilai tersebut mencakup bidang untuk setiap fitur. Catatan Jika tidak ada fitur tambahan yang dikonfigurasikan saat Anda menggunakan device SDK untuk mengembangkan fitur perangkat, parameter ini tidak tersedia. Fitur tambahan menggunakan konfigurasi default.
ack	Integer	Bidang fitur tambahan dalam parameter sys. Bidang ini menentukan apakah IoT Platform mengembalikan data respons untuk permintaan pendaftaran. Nilai valid: 1: IoT Platform mengembalikan data respons. 0: IoT Platform tidak mengembalikan data respons. Penting Untuk informasi lebih lanjut tentang parameter ini, lihat Contoh penggunaan model TSL. Jika fitur tidak dikonfigurasikan, parameter ini tidak tersedia. Secara default, IoT Platform mengembalikan data respons untuk permintaan pendaftaran.
params	Object	Data properti dan data peristiwa yang harus dikirimkan gateway dalam permintaan.
properties	Object	Properti yang akan dikirimkan. Anda dapat menentukan pengenal, value, dan time dari setiap properti. Parameter time bersifat opsional. Anda dapat menentukan apakah akan menentukan parameter time dalam permintaan berdasarkan kebutuhan bisnis Anda. Jika gateway sering mengirimkan pesan ke IoT Platform, kami sarankan Anda menentukan parameter time dalam permintaan untuk membantu mengidentifikasi urutan pesan. Dalam contoh sebelumnya, gateway mengirimkan informasi tentang properti Power (catu daya) dan WF (arus kerja). Jika Anda menggunakan properti modul kustom, pengenal setiap properti berada dalam format ${Pengenal Modul}:${Pengenal Properti}. Titik dua (:) digunakan untuk menghubungkan kedua bagian ekspresi ini. Contoh: `"test:Power": { "value": "on", "time": 1524448722000 }`
events	Object	Peristiwa yang akan dikirimkan. Anda dapat menentukan pengenal, value, dan time dari setiap peristiwa. Parameter time bersifat opsional. Anda dapat menentukan apakah akan menentukan parameter time dalam permintaan berdasarkan kebutuhan bisnis Anda. Jika gateway sering mengirimkan pesan ke IoT Platform, kami sarankan Anda menentukan parameter time dalam permintaan. Ini membantu Anda mengidentifikasi urutan pesan. Dalam contoh sebelumnya, alarmEvent1 (Peristiwa Alarm 1) dan alertEvent2 (Peristiwa Peringatan 2) dikirimkan. Parameter peristiwa tersebut adalah param1 dan param2. Jika Anda menggunakan peristiwa modul kustom, pengenal setiap peristiwa berada dalam format ${Pengenal Modul}:${Pengenal Peristiwa}. Titik dua (:) digunakan untuk menghubungkan kedua bagian ekspresi ini. Contoh: `"test:alarmEvent1": { "value": { "param1": "on", "param2": "2" }, "time": 1524448722000 }`
subDevices	Object	Informasi tentang perangkat sub-yang terpasang.
productKey	String	ProductKey produk tempat perangkat terpasang milik.
deviceName	String	Nama perangkat sub-.
method	String	Metode permintaan. Tetapkan nilainya menjadi thing.event.property.pack.post.

Tabel 10. Parameter Respons
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk sebuah perangkat.
code	Bilangan Bulat	Kode status. Nilai 200 menunjukkan permintaan berhasil. Catatan IoT Platform memeriksa apakah perangkat, hubungan topologi, serta properti dan kejadian yang dikirimkan sesuai dengan format yang didefinisikan dalam model TSL. Jika format salah satu item sebelumnya tidak valid, permintaan gagal.
data	Objek	Jika permintaan berhasil, parameter ini dibiarkan kosong.
pesan	String	Pesan respons. Jika permintaan berhasil, pesan "success" akan ditampilkan.
method	String	Metode permintaan dalam respons. Nilai parameter ini sama dengan nilai parameter method dalam permintaan.
version	String	Nomor versi protokol. Nilai parameter ini sama dengan nilai parameter version dalam permintaan.

Kode Kesalahan: IoT Platform dapat mengembalikan kode kesalahan ke perangkat. Untuk informasi lebih lanjut, lihat Kode Kesalahan untuk Perangkat.

Penerusan Data: IoT Platform dapat meneruskan sekumpulan data TSL yang dilaporkan oleh gateway ke server Anda atau layanan lain di Alibaba Cloud menggunakan fitur langganan sisi server atau penerusan data. Sistem kemudian memisahkan data TSL menjadi pesan-pesan dan meneruskannya secara berurutan. Pesan-pesan tersebut mencakup data properti dan peristiwa gateway serta perangkat sub-yang terpasang pada gateway. Untuk informasi lebih lanjut tentang topik dan format data terkait, lihat Kirim Properti Perangkat dan Kirim Peristiwa Perangkat.

Perangkat mengirimkan data TSL historis ke IoT Platform

Topik dan format data yang digunakan untuk mengirim data dari perangkat ke IoT Platform:

Topik permintaan: /sys/${productKey}/${deviceName}/thing/event/property/history/post
Topik respons: /sys/${productKey}/${deviceName}/thing/event/property/history/post_reply

Contoh permintaan dalam format JSON Alink:

{
    "id": "123", 
    "version": "1.0",
    "sys":{
        "ack":0
    }, 
    "method": "thing.event.property.history.post", 
    "params": [
        {
            "identity": {
                "productKey": "", 
                "deviceName": ""
            }, 
            "properties": [
                {
                    "Power": {
                        "value": "on", 
                        "time": 1524448722000
                    }, 
                    "WF": {
                        "value": "3", 
                        "time": 1524448722000
                    }
                }, 
                {
                    "Power": {
                        "value": "on", 
                        "time": 1524448722000
                    }, 
                    "WF": {
                        "value": "3", 
                        "time": 1524448722000
                    }
                }
            ], 
            "events": [
                {
                    "alarmEvent": {
                        "value": {
                            "Power": "on", 
                            "WF": "2"
                        }, 
                        "time": 1524448722000
                    }, 
                    "alertEvent": {
                        "value": {
                            "Power": "off", 
                            "WF": "3"
                        }, 
                        "time": 1524448722000
                    }
                }
            ]
        }, 
        {
            "identity": {
                "productKey": "", 
                "deviceName": ""
            }, 
            "properties": [
                {
                    "Power": {
                        "value": "on", 
                        "time": 1524448722000
                    }, 
                    "WF": {
                        "value": "3", 
                        "time": 1524448722000
                    }
                }
            ], 
            "events": [
                {
                    "alarmEvent": {
                        "value": {
                            "Power": "on", 
                            "WF": "2"
                        }, 
                        "time": 1524448722000
                    }, 
                    "alertEvent": {
                        "value": {
                            "Power": "off", 
                            "WF": "3"
                        }, 
                        "time": 1524448722000
                    }
                }
            ]
        }
    ]
}

Contoh respons dalam format JSON Alink:

Contoh respons sukses:

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "method": "thing.event.property.history.post",
    "version": "1.0"
}

Contoh respons gagal:

{
    "code": 5092,
    "data": {},
    "id": "123",
    "message": "properti tidak ditemukan",
    "method": "thing.event.property.history.post",
    "version": "1.0"
}

Parameter:

Tabel 11. Parameter Permintaan
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat.
version	String	Nomor versi protokol. Tetapkan nilainya menjadi 1.0.
sys	Objek	Parameter untuk fitur tambahan. Nilai tersebut mencakup bidang untuk setiap fitur. Catatan Jika tidak ada fitur tambahan yang dikonfigurasikan saat Anda menggunakan device SDK untuk mengembangkan fitur perangkat, parameter ini tidak tersedia. Fitur tambahan menggunakan konfigurasi default.
ack	Bilangan Bulat	Bidang fitur tambahan dalam parameter sys. Bidang ini menentukan apakah IoT Platform mengembalikan data respons untuk permintaan pendaftaran. Nilai valid: 1: IoT Platform mengembalikan data respons. 0: IoT Platform tidak mengembalikan data respons. Penting Untuk informasi lebih lanjut tentang parameter ini, lihat Contoh penggunaan model TSL. Jika fitur tidak dikonfigurasikan, parameter ini tidak tersedia. Secara default, IoT Platform mengembalikan data respons untuk permintaan pendaftaran.
method	String	Metode permintaan. Tetapkan nilainya menjadi thing.event.property.history.post.
params	Object	Data properti dan data peristiwa yang harus dikirimkan perangkat dalam permintaan.
identity	String	Informasi sertifikat tentang perangkat tempat data tersebut berasal. Anda harus menentukan parameter productKey dan deviceName. Catatan Perangkat yang terhubung langsung hanya dapat mengirimkan data TSL historis miliknya sendiri. Sebuah gateway dapat mengirimkan data TSL historis dari perangkat sub-yang terpasang pada gateway. Jika gateway mengirimkan data historis dari perangkat sub-yang terpasang, parameter identity berisi informasi tentang perangkat sub-yang terpasang.
properties	Object	Properti yang akan dikirimkan. Anda dapat menentukan pengenal, value, dan time dari setiap properti. Dalam contoh sebelumnya, perangkat mengirimkan data historis tentang properti Power (catu daya) dan WF (arus kerja). Jika Anda menggunakan properti modul kustom, pengenal setiap properti berada dalam format ${Pengenal Modul}:${Pengenal Properti}. Titik dua (:) digunakan untuk menghubungkan kedua bagian ekspresi ini. Contoh: `"test:Power": { "value": "on", "time": 1524448722000 }`
events	Object	Peristiwa yang perlu dikirimkan oleh perangkat. Anda dapat menentukan pengenal, value, dan time dari setiap peristiwa. Dalam contoh sebelumnya, data historis tentang peristiwa alarmEvent1 (peristiwa alarm), properti Power (catu daya), dan properti WF (arus kerja) dikirimkan. Jika Anda menggunakan peristiwa modul kustom, pengenal setiap peristiwa berada dalam format ${Pengenal Modul}:${Pengenal Peristiwa}. Titik dua (:) digunakan untuk menghubungkan kedua bagian ekspresi ini. Contoh: `"test:alarmEvent": { "value": { "Power": "on", "WF": "2" }, "time": 1.524.448.722.000 }`

Tabel 12. Parameter Respons
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat tersebut.
kode	Bilangan Bulat	Kode status. Untuk informasi lebih lanjut, lihat Kode umum pada perangkat.
data	Objek	Jika permintaan berhasil, parameter ini dibiarkan kosong.
pesan	String	Pesan respons. Jika permintaan berhasil, pesan "success" akan ditampilkan.
method	String	Metode permintaan dalam respons. Nilai parameter ini sama dengan nilai parameter method dalam permintaan.
version	String	Nomor versi protokol. Nilai parameter ini sama dengan nilai parameter version dalam permintaan.

Kode Kesalahan: IoT Platform dapat mengembalikan kode kesalahan ke perangkat. Untuk informasi lebih lanjut, lihat Kode Kesalahan untuk Perangkat.

Penerusan Data: IoT Platform dapat meneruskan data TSL historis yang dikirim oleh perangkat ke server Anda atau layanan Alibaba Cloud lainnya menggunakan langganan sisi server atau fitur penerusan data. Untuk informasi lebih lanjut tentang topik dan format data terkait, lihat Kirim Properti Historis dan Kirim Peristiwa Historis.

Penting

Ketika IoT Platform meneruskan data TSL historis, platform ini membuat pesan untuk setiap properti dalam nilai parameter properties atau setiap peristiwa dalam nilai parameter events. Pesan-pesan tersebut digunakan untuk meneruskan data historis dari properti dan peristiwa tersebut.

Perangkat mengirimkan beberapa properti dan kejadian ke IoT Platform secara bersamaan

Topik dan format data yang digunakan untuk mengirim data dari perangkat ke IoT Platform:

Topik permintaan: /sys/${productKey}/${deviceName}/thing/event/property/batch/post
Topik respons: /sys/${productKey}/${deviceName}/thing/event/property/batch/post_reply

Contoh permintaan dalam format Alink JSON:

{
    "id": "123", 
    "version": "1.0",
    "sys":{
        "ack":0
    }, 
    "method": "thing.event.property.batch.post", 
    "params": {
        "properties": {
            "Power": [
                {
                    "value": "on", 
                    "time": 1524448722000
                },
                {
                    "value": "off", 
                    "time": 1524448722001
                }
            ], 
            "WF": [
                {
                    "value": 3, 
                    "time": 1524448722000
                },
                {
                    "value": 4, 
                    "time": 1524448722009
                }
            ]
        }, 
        "events": {
            "alarmEvent": [
                {
                    "value": {
                        "Power": "on", 
                        "WF": "2"
                    }, 
                    "time": 1524448722000
                },
                {
                    "value": {
                        "Power": "on", 
                        "WF": "2"
                    }, 
                    "time": 1524448722000
                }
            ]
        }
    }
}

Contoh respons dalam format Alink JSON:

Contoh respons sukses:

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "method": "thing.event.property.batch.post",
    "version": "1.0"
}

Contoh respons gagal:

{
    "code": 9201,
    "data": {},
    "id": "123",
    "message": "device offLine",
    "method": "thing.event.property.batch.post",
    "version": "1.0"
}

Parameter:

Tabel 13. Parameter Permintaan
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat.
version	String	Nomor versi protokol. Atur nilai menjadi 1.0.
sys	Object	Parameter untuk fitur tambahan. Nilainya berisi bidang untuk setiap fitur. Catatan Jika tidak ada fitur tambahan yang dikonfigurasikan saat menggunakan SDK perangkat untuk mengembangkan fitur perangkat, parameter ini tidak tersedia. Fitur tambahan menggunakan konfigurasi default.
ack	Integer	Bidang fitur tambahan dalam parameter sys. Bidang ini menentukan apakah IoT Platform mengembalikan data respons untuk permintaan pendaftaran. Nilai valid: 1: IoT Platform mengembalikan data respons. 0: IoT Platform tidak mengembalikan data respons. Penting Untuk informasi lebih lanjut tentang parameter ini, lihat Contoh penggunaan model TSL. Jika fitur ini tidak dikonfigurasikan, parameter ini tidak tersedia. Secara default, IoT Platform mengembalikan data respons untuk permintaan pendaftaran.
method	String	Metode permintaan. Atur nilainya menjadi thing.event.property.batch.post.
params	Object	Data properti dan data kejadian yang harus diserahkan oleh perangkat dalam permintaan.
properties	Object	Properti yang akan diserahkan. Anda dapat menentukan pengenal, value, dan time untuk setiap properti. Dalam contoh sebelumnya, perangkat mengirimkan properti Power (catu daya) dan WF (arus kerja) secara bersamaan. Jika Anda menggunakan properti modul kustom, pengenal setiap properti berada dalam format ${Pengenal Modul}:${Pengenal Properti}. Titik dua (:) digunakan untuk menghubungkan kedua bagian ekspresi ini. Contoh: `"test:Power": { "value": "on", "time": 1524448722000 }`
events	Object	Kejadian yang perlu diserahkan oleh perangkat. Anda dapat menentukan pengenal, value, dan time untuk setiap kejadian. Dalam contoh sebelumnya, perangkat mengirimkan alarmEvent (kejadian peringatan), properti Power (catu daya), dan properti WF (arus kerja) secara bersamaan. Jika Anda menggunakan kejadian modul kustom, pengenal setiap kejadian berada dalam format ${Pengenal Modul}:${Pengenal Kejadian}. Titik dua (:) digunakan untuk menghubungkan kedua bagian ekspresi ini. Contoh: `"test:alarmEvent": { "value": { "Power": "on", "WF": "2" }, "time": 1524448722000 }`

Tabel 14. Parameter Respons
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat.
code	Integer	Kode status. Untuk informasi lebih lanjut, lihat Kode umum pada perangkat.
data	Object	Jika permintaan berhasil, parameter ini dibiarkan kosong.
message	String	Pesan respons. Jika permintaan berhasil, pesan "success" ditampilkan.
method	String	Metode permintaan dalam respons. Nilai parameter ini sama dengan nilai parameter method dalam permintaan.
version	String	Nomor versi protokol. Nilai parameter ini sama dengan nilai parameter version dalam permintaan.

Kode Kesalahan: IoT Platform dapat mengembalikan kode kesalahan ke perangkat. Untuk informasi lebih lanjut, lihat Kode Kesalahan untuk Perangkat.

Penerusan Data: IoT Platform dapat meneruskan sekelompok data TSL yang dikirim oleh perangkat ke server Anda menggunakan fitur langganan sisi server. Properti dan kejadian diteruskan dalam dua pesan terpisah. Untuk informasi lebih lanjut tentang topik dan format data spesifik, lihat Kirim Properti Perangkat dalam Batch dan Kirim Kejadian Perangkat dalam Batch.

Referensi

Apa perbedaan antara mengirim data properti, mengirim data historis, dan mengirim beberapa nilai properti secara bersamaan?