Manage custom device jobs dengan protokol Alink - IoT Platform

Platform IoT Alibaba Cloud menyediakan layanan konfigurasi dan manajemen tugas perangkat. Platform ini menggunakan protokol Alink untuk menangani tugas pemanggilan layanan batch perangkat maupun tugas pengaturan properti batch perangkat. Topik ini menjelaskan penyesuaian topik pesan pembaruan tugas dan format data Alink, mencakup pembaruan status tugas perangkat, permintaan perangkat untuk informasi tugas terbaru, serta pembaruan status subtugas.

Informasi latar belakang

Untuk mengimplementasikan tugas kustom, Anda harus mengembangkan kemampuan manajemen tugas di sisi perangkat. Untuk langkah-langkah lengkapnya, lihat Tugas Perangkat.
Untuk tugas pemanggilan layanan batch perangkat dan tugas pengaturan properti batch perangkat, jika SDK Link di sisi perangkat telah mengintegrasikan fungsi pemanggilan layanan dan pengaturan properti, tidak diperlukan pengembangan tambahan kemampuan manajemen tugas untuk menjalankan tugas perangkat.
Untuk metode mengintegrasikan fungsi pemanggilan layanan dan pengaturan properti ke dalam SDK Link di sisi perangkat, lihat dokumentasi pengembangan Thing Specification Language untuk SDK Link yang bersangkutan dalam Ikhtisar Akses Perangkat.
Untuk penjelasan mengenai protokol Alink yang digunakan dalam pemanggilan layanan dan pengaturan properti, lihat Properti, Peristiwa, dan Layanan Perangkat.

Notifikasi pembaruan status tugas perangkat

Catatan

Notifikasi hanya dikirim ke perangkat ketika status tugas berubah menjadi sedang berlangsung (in progress), dibatalkan (canceled), atau dihapus (deleted).

Hilir.

Topik: /sys/${productKey}/${deviceName}/thing/job/notify.

Contoh permintaan dalam format JSON Alink:

{
    "id": "7542940",
    "version": "1.0",
    "params": {
        "task": {
            "taskId": "i5Ks6***pF010101",
            "status": "SENT",
            "jobDocument": {},
            "jobFile":{
                "signMethod":"Md5",
                "sign":"wssxff56dhdsd***",
                "fileUrl": "https://iotx-***.oss-cn-shanghai.aliyuncs.com/***.zip"
            }
        }
    }
}

Tabel 1. Deskripsi Parameter Permintaan

Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat saat ini.
version	String	Versi protokol. Tetapkan parameter ini ke 1.0.
params	Object	Daftar parameter permintaan.
task	Object	Parameter subtugas.
taskId	String	ID subtugas, yang merupakan pengidentifikasi unik global.
status	String	Status subtugas. SENT: Dijadwalkan. REMOVED: Dihapus. CANCELLED: Dibatalkan.
jobDocument	Object	Dokumen tugas yang menjelaskan aturan eksekusi tugas. Catatan Jika status bernilai REMOVED atau CANCELLED, bidang ini kosong.
jobFile	Object	Informasi file yang diunggah saat membuat tugas kustom. signMethod: Metode tanda tangan. Saat ini mendukung `Md5` dan `Sha256`. sign: Parameter tanda tangan yang dihasilkan sesuai dengan metode tanda tangan yang bersangkutan. fileUrl: URL unduh file tugas, berlaku selama 1 jam. Catatan ```html Jika status bernilai REMOVED atau CANCELLED, bidang ini kosong.

Contoh tanggapan dalam format JSON Alink:

{
    "id": "7542940",
    "code": 200,
    "data": {}
}

Tabel 2. Deskripsi Parameter Tanggapan

Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat saat ini.
code	Integer	Kode status HTTP dalam tanggapan. Nilai 200 menunjukkan bahwa permintaan berhasil. Nilai lain menunjukkan permintaan gagal. Untuk informasi selengkapnya, lihat Kode umum yang dikembalikan oleh perangkat.
data	Object	Data yang dikembalikan oleh perangkat. Data hasil yang dikembalikan oleh notifikasi pembaruan tugas perangkat kosong.

Mendapatkan detail tugas perangkat

Hulu.

Topik permintaan: /sys/${productKey}/${deviceName}/thing/job/get.
Topik tanggapan: /sys/${productKey}/${deviceName}/thing/job/get_reply.

Contoh permintaan dalam format JSON Alink:

{
    "id": "123",
    "version": "1.0",
    "params": {
        "taskId": "i5Ks***F010101"
    }
}

Tabel 3. Deskripsi Parameter Permintaan

Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat saat ini.
version	String	Versi protokol. Tetapkan parameter ini ke 1.0.
params	Object	Daftar parameter permintaan.
taskId	String	Tiga metode nilai dapat mengembalikan informasi tugas dengan status berbeda. ID subtugas: Mengembalikan informasi detail tentang tugas yang sesuai dengan ID tugas. `$next`: Mengembalikan informasi tentang tugas yang dapat dieksekusi. `$list`: Mengembalikan daftar tugas yang dapat dieksekusi, maksimal 10 secara default.

Nilai taskId berbeda, sehingga format data tanggapan Alink juga berbeda.

taskId adalah ID subtugas:

{
    "id": "1234",
    "code": 200,
    "data": {
        "statusDetails":{"devs":"test","status":"init"},
        "taskId": "i5Ks***F010101",
        "task":{
            "taskId": "i5Ks***F010101",
            "status": "IN_PROGRESS",
            "jobDocument": {},
            "jobFile":{
                "signMethod":"Md5",
                "sign":"wssxff56dhdsd***",
                "fileUrl": "https://iotx-***.oss-cn-shanghai.aliyuncs.com/***.zip"
            }
        }
    }
}

taskId adalah $next:

{
    "id": "1234",
    "code": 200,
    "data": {
        "statusDetails":{"devs":"test","status":"init"},
        "taskId": "$next",
        "task":{
            "taskId": "i5Ks***F010101",
            "status": "IN_PROGRESS",
            "jobDocument": {},
            "jobFile":{
                "signMethod":"Md5",
                "sign":"wssxff56dhdsd***",
                "fileUrl": "https://iotx-***.oss-cn-shanghai.aliyuncs.com/***.zip"
            }
        }
    }
}

taskId adalah $list:

{
    "id": "1234",
    "code": 200,
    "data": {
        "statusDetails":{"devs":"test","status":"init"},
        "taskId": "$list",
        "task":[
            {
                "taskId": "i5Ks***",
                "status": "IN_PROGRESS"
            },
            {
                "taskId": "i61s***",
                "status": "IN_PROGRESS"
            }
        ]
    }
}

Tabel 4. Deskripsi Parameter Tanggapan

Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat saat ini.
code	Integer	Kode status HTTP dalam tanggapan. Nilai 200 menunjukkan bahwa permintaan berhasil. Nilai lain menunjukkan permintaan gagal. Untuk informasi selengkapnya, lihat Kode umum yang dikembalikan oleh perangkat.
data	Object	Data yang dikembalikan oleh perangkat.
task	Object	Parameter subtugas.
taskId	String	ID subtugas, yang merupakan pengidentifikasi unik global.
status	String	Status subtugas. QUEUED: Dalam antrean. SENT: Dijadwalkan. IN_PROGRESS: Sedang berlangsung. TIMED_OUT: Melebihi batas waktu. FAILED: Gagal. SUCCEEDED: Berhasil. CANCELLED: Dibatalkan. REJECTED: Ditolak.
statusDetails	JSON	Konfigurasi yang ditentukan pengguna saat membuat tugas pada perangkat.
jobDocument	Object	Dokumen tugas yang menjelaskan aturan eksekusi tugas.
jobFile	Object	Informasi file yang diunggah saat membuat tugas kustom. signMethod: Metode tanda tangan. Saat ini mendukung `Md5` dan `Sha256`. sign: Parameter tanda tangan yang dihasilkan sesuai dengan metode tanda tangan yang bersangkutan. fileUrl: URL unduh file tugas, berlaku selama 1 jam.

Memperbarui status subtugas

Hulu.

Topik permintaan: /sys/${productKey}/${deviceName}/thing/job/update.
Topik tanggapan: /sys/${productKey}/${deviceName}/thing/job/update_reply.

Contoh permintaan dalam format JSON Alink:

{
    "id": "123",
    "version": "1.0",
    "params": {
        "taskId": "i5Ks***F010101",
        "status": "IN_PROGRESS",
        "statusDetails": {
            "key": "value"
        },
        "progress": 50
    }
}

Tabel 5. Deskripsi Parameter Permintaan

Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat saat ini.
version	String	Versi protokol. Tetapkan parameter ini ke 1.0.
params	Object	Daftar parameter permintaan.
taskId	String	ID subtugas, yang merupakan pengidentifikasi unik global.
status	String	Status subtugas. Nilai yang valid: SUCCEEDED: Berhasil diselesaikan. FAILED: Eksekusi gagal. IN_PROGRESS: Sedang dieksekusi. REJECTED: Eksekusi ditolak.
statusDetails	Object	Detail status yang dapat disesuaikan oleh pengguna. Detail ini dapat dilihat pada halaman Device Management > Tasks > Task Details di Konsol Platform IoT.
progress	Integer	Persentase progres eksekusi subtugas.

Contoh tanggapan dalam format JSON Alink:

{
    "id":"123",
    "code":200,
    "data":{
        "taskId":"i5Ks***F010101"
    }
}

Tabel 6. Deskripsi Parameter Tanggapan

Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat saat ini.
code	Integer	Kode status HTTP dalam tanggapan. Nilai 200 menunjukkan bahwa permintaan berhasil. Nilai lain menunjukkan permintaan gagal. Untuk informasi selengkapnya, lihat Kode umum yang dikembalikan oleh perangkat.
data	Object	Data yang dikembalikan oleh perangkat.
taskId	String	ID subtugas, yang merupakan pengidentifikasi unik global.