View a markdown version of this page

Pekerjaan perangkat operasi MQTT API - AWS IoT Core

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Pekerjaan perangkat operasi MQTT API

Anda dapat mengeluarkan perintah perangkat pekerjaan dengan menerbitkan pesan MQTT ke topik Cad angan yang digunakan untuk perintah Pekerjaan.

Klien sisi perangkat Anda harus berlangganan topik pesan respons dari perintah ini. Jika Anda menggunakan Kli AWS IoT en Perangkat, perangkat Anda akan secara otomatis berlangganan topik respons. Ini berarti bahwa broker pesan akan mempublikasikan topik pesan respons kepada klien yang menerbitkan pesan perintah, terlepas dari apakah klien Anda telah berlangganan topik pesan respons atau tidak. Pesan respons ini tidak melewati broker pesan dan tidak dapat berlangganan oleh klien atau aturan lain.

Saat berlangganan topik pekerjaan dan jobExecution acara untuk solusi pemantauan armada Anda, pertama-tama aktifkan acara pekerjaan dan eksekusi pekerjaan untuk menerima acara apa pun di sisi cloud. Pesan kemajuan pekerjaan yang diproses melalui broker pesan dan dapat digunakan oleh AWS IoT aturan dipublikasikan sebagaiPeristiwa tugas. Karena broker pesan menerbitkan pesan respons, bahkan tanpa langganan eksplisit, klien Anda harus dikonfigurasi untuk menerima dan mengidentifikasi pesan yang diterimanya. Klien Anda juga harus mengkonfirmasi bahwa topik thingName dalam pesan masuk berlaku untuk nama barang klien sebelum klien bertindak atas pesan tersebut.

catatan

Pesan yang dikirim AWS IoT sebagai respons terhadap pesan perintah API MQTT Jobs akan dibebankan ke akun Anda, terlepas dari apakah Anda berlangganan pesan tersebut secara eksplisit atau tidak.

Berikut ini menunjukkan operasi API MQTT dan sintaks permintaan dan respons mereka. Semua operasi API MQTT memiliki parameter berikut:

ClientToken

Token klien opsional yang digunakan untuk menghubungkan permintaan dan tanggapan. Masukkan nilai arbitrer di sini dan itu tercermin dalam respons.

timestamp

Waktu dalam detik sejak zaman, ketika pesan dikirim.

Mendapat daftar semua pekerjaan yang tidak dalam status terminal, untuk hal yang ditentukan.

Untuk memanggil API ini, publikasikan pesan di$aws/things/thingName/jobs/get.

Minta muatan:

{ "clientToken": "string" }

Pialang pesan akan menerbitkan $aws/things/thingName/jobs/get/accepted dan $aws/things/thingName/jobs/get/rejected bahkan tanpa berlangganan khusus untuk mereka. Namun, agar klien Anda menerima pesan, ia harus mendengarkan mereka. Untuk informasi selengkapnya, lihat catatan tentang pesan Jobs API.

Muatan respons:

{
"inProgressJobs" : [ JobExecutionSummary ... ], 
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}

Dim inProgressJobs ana dan queuedJobs mengembalikan daftar JobExecutionSummary objek yang memiliki status IN_PROGRESS atauQUEUED.

Mendapat dan memulai eksekusi pekerjaan tertunda berikutnya untuk suatu hal (status IN_PROGRESS atauQUEUED).

  • Setiap eksekusi pekerjaan dengan status IN_PROGRESS dikembalikan terlebih dahulu.

  • Eksekusi pekerjaan dikembalikan dalam urutan di mana mereka mengantri. Ketika sesuatu ditambahkan atau dihapus dari grup target untuk pekerjaan Anda, konfirmasikan urutan peluncuran setiap eksekusi pekerjaan baru dibandingkan dengan eksekusi pekerjaan yang ada.

  • Jika eksekusi pekerjaan tertunda berikutnya adalahQUEUED, statusnya berubah menjadi IN_PROGRESS dan detail status eksekusi pekerjaan ditetapkan seperti yang ditentukan.

  • Jika eksekusi tugas tertunda berikutnya sudah IN_PROGRESS ada, detail statusnya tidak berubah.

  • Jika tidak ada eksekusi pekerjaan yang tertunda, respons tidak menyertakan execution bidang tersebut.

  • Secara opsional, Anda dapat membuat timer langkah dengan mengatur nilai untuk stepTimeoutInMinutes properti. Jika Anda tidak memperbarui nilai properti ini dengan menjalankanUpdateJobExecution, waktu eksekusi pekerjaan habis saat penghitung waktu langkah berakhir.

Untuk memanggil API ini, publikasikan pesan di$aws/things/thingName/jobs/start-next.

Minta muatan:

{ 
"statusDetails": {
    "string": "job-execution-state"
    ...
},
"stepTimeoutInMinutes": long,
"clientToken": "string"
}
statusDetails

Kumpulan pasangan nama-nilai yang menggambarkan status eksekusi pekerjaan. Jika tidak ditentukan, statusDetails tidak berubah.

stepTimeOutInMinutes

Menentukan jumlah waktu yang dimiliki perangkat ini untuk menyelesaikan eksekusi pekerjaan ini. Jika status eksekusi pekerjaan tidak disetel ke status terminal sebelum pengatur waktu ini berakhir, atau sebelum pengatur waktu diatur ulang, (dengan memanggilUpdateJobExecution, menyetel status ke IN_PROGRESS dan menentukan nilai batas waktu baru di bidangstepTimeoutInMinutes) status eksekusi pekerjaan disetel keTIMED_OUT. Menyetel batas waktu ini tidak berpengaruh pada batas waktu eksekusi pekerjaan yang mungkin telah ditentukan saat pekerjaan dibuat (CreateJobmenggunakan timeoutConfig bidang).

Nilai yang valid untuk parameter ini berkisar dari 1 hingga 10080 (1 menit hingga 7 hari). Nilai -1 juga valid dan akan membatalkan pengatur waktu langkah saat ini (dibuat oleh penggunaan sebelumnya UpdateJobExecutionRequest).

Pialang pesan akan menerbitkan $aws/things/thingName/jobs/start-next/accepted dan $aws/things/thingName/jobs/start-next/rejected bahkan tanpa berlangganan khusus untuk mereka. Namun, agar klien Anda menerima pesan, ia harus mendengarkan mereka. Untuk informasi selengkapnya, lihat catatan tentang pesan Jobs API.

Muatan respons:

{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}

Dim execution ana JobExecution objek. Contoh:

{
"execution" : {
    "jobId" : "022",
    "thingName" : "MyThing",
    "jobDocument" : "< contents of job document >",
    "status" : "IN_PROGRESS",
    "queuedAt" : 1489096123309,
    "lastUpdatedAt" : 1489096123309,
    "versionNumber" : 1,
    "executionNumber" : 1234567890
},
"clientToken" : "client-1",
"timestamp" : 1489088524284,
}

Mendapatkan informasi terperinci tentang eksekusi pekerjaan.

Anda dapat mengatur jobId ke $next untuk mengembalikan eksekusi pekerjaan tertunda berikutnya untuk suatu hal (dengan status IN_PROGRESS atauQUEUED).

Untuk memanggil API ini, publikasikan pesan di$aws/things/thingName/jobs/jobId/get.

Minta muatan:

{ 
"jobId" : "022",
"thingName" : "MyThing",
"executionNumber": long,
"includeJobDocument": boolean,
"clientToken": "string" 
}
thingName

Nama hal yang terkait dengan perangkat.

jobId

Pengidentifikasi unik yang ditetapkan untuk pekerjaan ini saat dibuat.

Atau gunakan $next untuk mengembalikan eksekusi pekerjaan tertunda berikutnya untuk suatu hal (dengan status IN_PROGRESS atauQUEUED). Dalam hal ini, setiap eksekusi pekerjaan dengan status IN_PROGRESS dikembalikan terlebih dahulu. Eksekusi pekerjaan dikembalikan dalam urutan pembuatannya.

executionNumber

(Opsional) Nomor yang mengidentifikasi eksekusi pekerjaan pada perangkat. Jika tidak ditentukan, eksekusi pekerjaan terbaru dikembalikan.

includeJobDocument

(Opsional) Kecuali false disetel ke, respons berisi dokumen pekerjaan. Nilai default-nya true.

Pialang pesan akan menerbitkan $aws/things/thingName/jobs/jobId/get/accepted dan $aws/things/thingName/jobs/jobId/get/rejected bahkan tanpa berlangganan khusus untuk mereka. Namun, agar klien Anda menerima pesan, ia harus mendengarkan mereka. Untuk informasi selengkapnya, lihat catatan tentang pesan Jobs API.

Muatan respons:

{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}

Dim execution ana JobExecution objek.

Memperbarui status eksekusi pekerjaan. Anda dapat secara opsional membuat timer langkah dengan mengatur nilai untuk stepTimeoutInMinutes properti. Jika Anda tidak memperbarui nilai properti ini dengan menjalankannya UpdateJobExecution lagi, waktu eksekusi pekerjaan habis saat penghitung waktu langkah berakhir.

Untuk memanggil API ini, publikasikan pesan di$aws/things/thingName/jobs/jobId/update.

Minta muatan:

{
"status": "job-execution-state",
"statusDetails": { 
    "string": "string"
    ...
},
"expectedVersion": "number",
"executionNumber": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"clientToken": "string"
}
status

Status baru untuk eksekusi pekerjaan (IN_PROGRESS,FAILED,SUCCEEDED, atauREJECTED). Ini harus ditentukan pada setiap pembaruan.

statusDetails

Kumpulan pasangan nama-nilai yang menggambarkan status eksekusi pekerjaan. Jika tidak ditentukan, statusDetails tidak berubah.

expectedVersion

Versi eksekusi pekerjaan saat ini yang diharapkan. Setiap kali Anda memperbarui eksekusi pekerjaan, versinya bertambah. Jika versi eksekusi pekerjaan yang disimpan di layanan AWS IoT Jobs tidak cocok, pembaruan ditolak dengan VersionMismatch kesalahan. Sebuah ErrorResponse yang berisi data status eksekusi pekerjaan saat ini juga dikembalikan. (Ini membuat tidak perlu melakukan DescribeJobExecution permintaan terpisah untuk mendapatkan data status eksekusi pekerjaan.)

executionNumber

(Opsional) Nomor yang mengidentifikasi eksekusi pekerjaan pada perangkat. Jika tidak ditentukan, eksekusi pekerjaan terbaru digunakan.

includeJobExecutionState

(Opsional) Ketika disertakan dan dis true etel ke, respons berisi JobExecutionState bidang. Nilai default-nya false.

includeJobDocument

(Opsional) Ketika disertakan dan dis true etel ke, respons berisiJobDocument. Nilai default-nya false.

stepTimeoutInMinutes

Menentukan jumlah waktu yang dimiliki perangkat ini untuk menyelesaikan eksekusi pekerjaan ini. Jika status eksekusi pekerjaan tidak disetel ke status terminal sebelum pengatur waktu ini berakhir, atau sebelum pengatur waktu diatur ulang, status eksekusi pekerjaan disetel keTIMED_OUT. Menyetel atau mengatur ulang batas waktu ini tidak berpengaruh pada batas waktu eksekusi pekerjaan yang mungkin telah ditentukan saat pekerjaan dibuat.

Pialang pesan akan menerbitkan $aws/things/thingName/jobs/jobId/update/accepted dan $aws/things/thingName/jobs/jobId/update/rejected bahkan tanpa berlangganan khusus untuk mereka. Namun, agar klien Anda menerima pesan, ia harus mendengarkan mereka. Untuk informasi selengkapnya, lihat catatan tentang pesan Jobs API.

Muatan respons:

{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}
executionState

Sebuah objek JobExecutionState.

jobDocument

Ob Konsep kunci pekerjaan jek dokumen pekerjaan.

catatan

Dalam respons MQTT, jobDocument bidang adalah objek JSON. Dalam respons HTTP, ini adalah representasi string dari objek JSON.

timestamp

Waktu dalam detik sejak zaman, ketika pesan dikirim.

clientToken

Token klien yang digunakan untuk menghubungkan permintaan dan tanggapan.

Saat Anda menggunakan protokol MQTT, Anda juga dapat melakukan pembaruan berikut:

Dikirim setiap kali eksekusi pekerjaan ditambahkan ke atau dihapus dari daftar eksekusi pekerjaan yang tertunda untuk suatu hal.

Gunakan topik:

$aws/things/thingName/jobs/notify

Muatan pesan:

{
"jobs" : {
    "JobExecutionState": [ JobExecutionSummary ... ]
         },
    "timestamp": timestamp
}

Dikirim setiap kali ada perubahan eksekusi pekerjaan berikutnya pada daftar eksekusi pekerjaan yang tertunda untuk suatu hal, seperti yang didefinisikan untuk DescribeJobExecution dengan jobId$next. Pesan ini tidak dikirim ketika detail eksekusi pekerjaan berikutnya berubah, hanya ketika pekerjaan berikutnya yang akan dikembalikan oleh DescribeJobExecution dengan jobId $next telah berubah. Pertimbangkan eksekusi pekerjaan J1 dan J2 dengan status. QUEUED J1 adalah yang berikutnya dalam daftar eksekusi pekerjaan yang tertunda. Jika status J2 diubah menjadi IN_PROGRESS sementara status J1 tetap tidak berubah, maka pemberitahuan ini dikirim dan berisi rincian J2.

Gunakan topik:

$aws/things/thingName/jobs/notify-next

Muatan pesan:

{
"execution" : JobExecution,
"timestamp": timestamp,
}