FAQ dan solusi model TSL - IoT Platform - Alibaba Cloud Documentation Center

Topik ini menjawab pertanyaan umum (FAQ) tentang penggunaan model TSL untuk komunikasi perangkat dan menyediakan solusinya.

Tambahkan fitur model TSL

Properti, event, dan layanan model TSL harus ditambahkan dan dikonfigurasikan pada Produk yang berisi perangkat tersebut. Anda dapat mendefinisikan model TSL dengan cara berikut:

Panggil API CreateThingModel untuk menambahkan fitur model TSL ke Produk tertentu.
Tambahkan fitur model TSL di Konsol IoT Platform. Untuk informasi selengkapnya, lihat Tambahkan satu model TSL dan Tambahkan model TSL secara batch.

Kegagalan verifikasi TSL saat impor batch

Gejala

Saat Anda mengimpor model TSL untuk suatu Produk di Konsol IoT Platform, salah satu dari dua jenis kegagalan verifikasi berikut dapat terjadi dalam dialog Import TSL Model: pesan error langsung, The file content is not in a valid JSON format, atau pengecualian verifikasi dengan tautan Download and View untuk mengambil informasi error detail.

Solusi

Solusi berikut sesuai dengan dua jenis kegagalan verifikasi tersebut:

Periksa file model TSL, perbaiki kesalahan format JSON, lalu unggah ulang file tersebut.

Klik Download and View untuk mendapatkan file errors.txt. Gunakan file tersebut untuk mengidentifikasi dan menyelesaikan masalahnya.

Untuk informasi lebih lanjut tentang file errors.txt, lihat contoh berikut.

Contoh file model TSL:

{
    "schema":"https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json",
    "profile":{
        "productKey":"a1Jk***"
    },
    "services":[],
    "properties": 1,
    "events": [],
    "functionBlockId": "modulemtest",
    "functionBlockName": "Custom Module 1"
}

File errors.txt yang diunduh:

[
  {
    "path": [
      "properties"
    ],
    "property": "instance.properties",
    "message": "is not of a type(s) array",
    "schema": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/propertyDefinition"
      }
    },
    "instance": 1,
    "name": "type",
    "argument": [
      "array"
    ],
    "stack": "instance.properties is not of a type(s) array"
  },
  {
    "path": [
      "functionBlockId"
    ],
    "property": "instance.functionBlockId",
    "message": "does not match pattern \"^[_a-zA-Z0-9]{1,30}$\"",
    "schema": {
      "type": "string",
      "pattern": "^[_a-zA-Z0-9]{1,30}$"
    },
    "instance": "module-test",
    "name": "pattern",
    "argument": "^[_a-zA-Z0-9]{1,30}$",
    "stack": "instance.functionBlockId does not match pattern \"^[_a-zA-Z0-9]{1,30}$\""
  }
]

Parameter	Deskripsi
path	Jalur menuju elemen yang menyebabkan error verifikasi. Dalam contoh ini, ditemukan dua error: `// Parameter properties dikonfigurasi salah. Nilainya bukan array. "path": [ "properties" ] // Nilai functionBlockId mengandung tanda hubung, yang tidak valid. "path": [ "functionBlockId" ]`
property	Objek spesifik di bawah jalur tersebut yang melanggar aturan. Misalnya, properti untuk `"path": ["functionBlockId" ]` adalah `instance.functionBlockId`.
message	Pesan error spesifik. Misalnya, untuk `"path": ["functionBlockId" ]`, pesan error untuk properti tersebut adalah `does not match pattern \"^[_a-zA-Z0-9]{1,30}$\"`.
schema	Nama dan isi aturan verifikasi. Misalnya, untuk `"path": ["functionBlockId" ]`, aturannya adalah `type` dan `pattern`. Untuk informasi lebih lanjut tentang definisi aturan, lihat JSON Schema.
instance	Objek spesifik yang diverifikasi. Misalnya, untuk `"path": ["functionBlockId" ]`, konten `"functionBlockId": "module-test"` dalam file model TSL diverifikasi.
name	Nama aturan yang gagal diverifikasi. Misalnya, untuk `"path": ["functionBlockId" ]`, objek `module-test` tidak memenuhi aturan `pattern`.
argument	Definisi aturan yang dilanggar. Misalnya, untuk `"path": ["functionBlockId" ]`, aturan `pattern` yang tidak terpenuhi didefinisikan sebagai `^[_a-zA-Z0-9]{1,30}$`.
stack	Pesan error lengkap yang menggabungkan field property dan message.

Untuk informasi lebih lanjut, lihat dokumentasi jsonschema.

Perbedaan metode pelaporan data

Perbedaan fungsional

Fitur	Perbedaan
Property reporting	Melaporkan snapshot data properti perangkat. Timestamp bersifat opsional: Jika timestamp disertakan, IoT Platform menyimpannya sebagai waktu pelaporan properti. Satu laporan data hanya dapat berisi data untuk satu titik waktu. Jika tidak ada timestamp, IoT Platform secara otomatis menghasilkan timestamp berdasarkan waktu saat ini dan menyimpannya sebagai waktu pelaporan properti.
Historical data reporting	Melaporkan nilai properti berbeda pada titik waktu yang sama. Fitur ini berbasis waktu. Timestamp wajib disertakan. Satu laporan data dapat mencakup data untuk beberapa titik waktu.
Batch property reporting	Melaporkan nilai properti yang sama pada titik waktu berbeda. Fitur ini berbasis properti. Timestamp wajib disertakan. Satu laporan data dapat mencakup data untuk beberapa properti pada beberapa titik waktu.

Setelah data properti, data historis, atau data properti batch dilaporkan ke IoT Platform, platform akan menghasilkan catatan data historis berdasarkan timestamp.

Perbedaan topik komunikasi dan format data

Topik dan format data berbeda untuk setiap metode. Untuk informasi selengkapnya, lihat Device reports properties, Report historical TSL model data, dan Device reports properties in batches.

Contoh

Contoh ini menggunakan perangkat yang melaporkan data suhu.

Property reporting:
1. Perangkat melaporkan data snapshot dengan timestamp secara berurutan dari kiri ke kanan, seperti pada tabel berikut.
  
  13:00
  
  14:00
  
  15:00
  
  15:10
  
  60
  
  70
  
  80
  
  90
2. Kemudian, perangkat melaporkan nilai snapshot lain sebesar 100. Data diperbarui secara berbeda tergantung apakah timestamp disertakan:
  - Tanpa timestamp: Waktu default mengikuti waktu saat ini (misalnya, 15:30). Dalam kasus ini, nilai snapshot yang ditampilkan di Konsol IoT Platform adalah 100 pada pukul 15:30, dan entri terbaru dalam daftar data historis juga 100 pada pukul 15:30.
  - Dengan timestamp: Jika timestamp adalah 15:00, data untuk pukul 15:00 diperbarui menjadi 100. Nilai snapshot yang ditampilkan di Konsol IoT Platform menjadi 100 pada pukul 15:00, tetapi entri terbaru dalam daftar data historis tetap 90 pada pukul 15:10.
Historical data reporting:
1. Perangkat melaporkan data historis berikut secara bersamaan.
  
  13:00
  
  14:00
  
  15:00
  
  15:10
  
  60
  
  70
  
  80
  
  90
2. Kemudian, perangkat melaporkan data historis berikut secara bersamaan.
  
  13:10
  
  14:10
  
  100
  
  200
  
  Dalam kasus ini, nilai snapshot yang ditampilkan di Konsol IoT Platform adalah 100 pada pukul 13:10 atau 200 pada pukul 14:10, tergantung nilai mana yang terakhir ditulis ke database. Entri terbaru dalam daftar data historis tetap 90 pada pukul 15:10.

Data TSL tidak diperbarui dengan topik kustom

Anda harus melaporkan data model TSL perangkat menggunakan topik komunikasi model TSL. Untuk informasi selengkapnya, lihat Topic categories and communication.

Ambil data model TSL

Anda dapat mengambil data model TSL perangkat dengan cara berikut:

Langganan sisi server: Gunakan fitur langganan sisi server IoT Platform untuk berlangganan pesan Device Upstream Notification. IoT Platform kemudian meneruskan pesan-pesan ini dari semua perangkat dalam Produk ke server Anda berdasarkan pengaturan langganan Anda. Dua metode langganan sisi server berikut didukung:
- AMQP server-side subscription: Gunakan SDK AMQP untuk menerima pesan perangkat yang diteruskan oleh IoT Platform.
- Message Service (MNS) server-side subscription: Gunakan SDK Simple Message Queue (formerly MNS) untuk menerima pesan perangkat yang diteruskan IoT Platform ke Simple Message Queue (formerly MNS).
Data Forwarding: Gunakan fitur Data Forwarding dari Mesin aturan untuk membuat aturan yang meneruskan data perangkat tertentu ke layanan cloud lain, seperti Simple Message Queue (formerly MNS), ApsaraDB for RDS, Tablestore, Function Compute, Time Series Database (TSDB), Lindorm, DataHub, dan Message Queue for Apache RocketMQ. Untuk informasi selengkapnya, lihat Data Forwarding (Legacy) dan Data Forwarding (New).

Cloud API:

API	Deskripsi
QueryDevicePropertyStatus	Menanyakan semua snapshot properti perangkat tertentu.
QueryDeviceOriginalPropertyStatus	Menanyakan snapshot properti asli yang dilaporkan oleh perangkat tertentu. Ini mencakup semua properti, terlepas dari apakah telah lolos verifikasi model TSL atau tidak.
QueryDeviceOriginalPropertyData	Menanyakan catatan properti asli yang dilaporkan oleh perangkat tertentu. Ini mencakup semua properti, terlepas dari apakah telah lolos verifikasi model TSL atau tidak.
QueryDeviceOriginalEventData	Menanyakan catatan event asli yang dilaporkan oleh perangkat tertentu. Ini mencakup semua event, terlepas dari apakah telah lolos verifikasi model TSL atau tidak.
QueryDeviceOriginalServiceData	Menanyakan catatan panggilan layanan asli dari perangkat tertentu. Ini mencakup semua layanan, terlepas dari apakah telah lolos verifikasi model TSL atau tidak.
QueryDeviceDesiredProperty	Menanyakan nilai properti yang diinginkan dari perangkat tertentu.
QueryDevicePropertyData	Menanyakan data satu properti untuk perangkat tertentu dalam rentang waktu tertentu.
QueryDevicePropertiesData	Menanyakan data beberapa properti untuk perangkat tertentu dalam rentang waktu tertentu.
QueryDeviceEventData	Menanyakan catatan event perangkat tertentu.
QueryDeviceServiceData	Menanyakan catatan panggilan layanan perangkat tertentu.

Data model TSL tidak muncul di konsol

Saat perangkat melaporkan data model TSL, IoT Platform memverifikasi data tersebut berdasarkan model TSL yang telah didefinisikan dan metode validasi data yang dikonfigurasi. Data yang gagal diverifikasi atau dilewati validasinya tidak akan ditampilkan di tab TSL Model Data pada halaman Device Details perangkat di Konsol IoT Platform. Untuk informasi selengkapnya, lihat Validate TSL model data.

Anda harus mengatur metode validasi data saat membuat Produk. Untuk informasi selengkapnya, lihat Create a product.

Status data TSL tidak diperbarui setelah perintah

Untuk memecahkan masalah ini, periksa aspek-aspek berikut:

Sisi perangkat: Pastikan perangkat terhubung dengan benar ke IoT Platform. Untuk informasi tentang cara menghubungkan perangkat, lihat Download device SDKs.

Penting
Perintah yang berhasil dari IoT Platform hanya mengonfirmasi bahwa permintaan 'set' telah dikirim dari cloud; tidak menjamin eksekusi oleh perangkat. Agar properti dianggap berhasil di-set, perangkat harus menerapkan nilai baru tersebut dan melaporkannya kembali ke platform.

Anda dapat menggunakan emulator perangkat atau tool MQTT.fx untuk mensimulasikan perangkat online, lalu gunakan fitur debugging online untuk menguji kemampuan komunikasi perangkat. Untuk informasi selengkapnya, lihat:
Sisi cloud IoT Platform:
- Pastikan properti yang ingin Anda set nilainya atau desired value-nya memiliki akses read/write.
- Pastikan pesan model TSL diurai dengan benar.
  
  Data hanya ditampilkan dalam status running model TSL jika pesan model TSL diurai dengan benar. Untuk informasi selengkapnya, lihat TSL models dan Parse TSL model messages.
Masuk ke Konsol IoT Platform. Di instans tersebut, buka halaman Maintenance > Device Log > Cloud run log untuk melihat log dan memeriksa apakah perangkat berhasil menerima pesan tersebut. Untuk informasi selengkapnya, lihat Cloud run log.

Data suhu tidak muncul di konsol

Data model TSL tidak dapat ditampilkan jika properti model TSL tidak didefinisikan atau format data yang dilaporkan salah.

Ikuti langkah-langkah berikut agar data ditampilkan dengan benar:

Definisikan properti model TSL bernama Temperature untuk Produk yang berisi perangkat tersebut. Untuk informasi selengkapnya, lihat Add TSL model features.
Perangkat harus melaporkan data properti menggunakan topik komunikasi model TSL dan format data yang benar. Untuk informasi lebih lanjut tentang pengembangan sisi perangkat, lihat Device connection.
- Jika Anda memilih ICA Standard Data Format (Alink JSON) sebagai format data saat membuat Produk, perangkat harus menggunakan topik /sys/${productKey}/${deviceName}/thing/event/property/post dan melaporkan data dalam format berikut:
```
{
    "id": "123",
    "version": "1.0",
    "sys":{
        "ack":0
    },
    "params": {
        "temperature": {
            "value": 35,
            "time": 1524448722000
        }
    },
    "method": "thing.event.property.post"
}
```
  Untuk informasi lebih lanjut tentang bidang-bidang tersebut, lihat Device reports properties.
- Jika Anda memilih Passthrough/Custom sebagai format data saat membuat Produk, Anda harus mengonfigurasi skrip untuk mengurai pesan model TSL.
  
  Perangkat harus menggunakan topik /sys/${productKey}/${deviceName}/thing/model/up_raw untuk mentransmisikan data dalam format heksadesimal. Untuk informasi selengkapnya, lihat Device reports properties dan Parse TSL model messages.

Impor fitur model TSL dengan cepat

Ya. IoT Platform menyediakan metode berikut untuk menambahkan fitur model TSL secara batch:

Add TSL models in batches: Di Konsol IoT Platform, Anda dapat menyalin fitur model TSL dari Produk lain secara batch atau mengimpor file TSL.
CreateThingModel: Gunakan SDK sisi server untuk memanggil API cloud ini dan tambahkan fitur model TSL menggunakan parameter ThingModelJson. Untuk informasi lebih lanjut tentang format data ThingModelJson, lihat ThingModelJson data format.

13:00	14:00	15:00	15:10
60	70	80	90

13:00	14:00	15:00	15:10
60	70	80	90

13:10	14:10
100	200