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 keTopik cadangan yang digunakan untuk perintah Pekerjaan.

Klien sisi perangkat Anda harus berlangganan topik pesan respons dari perintah ini. Jika Anda menggunakanAWS IoTKlien 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, 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 pekerjaan danjobExecutiontopik acara untuk solusi pemantauan armada Anda, pertama-tama aktifkanpekerjaan dan pelaksanaan pekerjaanuntuk menerima acara apa pun di sisi cloud. Pesan kemajuan pekerjaan yang diproses melalui broker pesan dan dapat digunakan olehAWS IoTditerbitkan sebagaiAcara Lowongan. Karena broker pesan menerbitkan pesan respons, bahkan tanpa berlangganan eksplisit kepada mereka, klien Anda harus dikonfigurasi untuk menerima dan mengidentifikasi pesan yang diterimanya. Klien Anda juga harus mengkonfirmasi bahwaThingNamedalam topik pesan masuk berlaku untuk nama hal klien sebelum klien bertindak pada pesan.

catatan

Pesan ituAWS IoTmengirim dalam menanggapi pesan perintah MQTT Jobs API dibebankan ke akun Anda, apakah Anda berlangganan mereka secara eksplisit atau tidak.

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

ClientToken

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

timestamp

Waktu dalam hitungan detik sejak zaman, ketika pesan dikirim.

Mendapat daftar semua pekerjaan yang tidak dalam keadaan terminal, untuk hal tertentu.

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

Meminta muatan:

{ "clientToken": "string" }

Broker pesan akan menerbitkan$aws/things/thingName/jobs/get/accepteddan$aws/things/thingName/jobs/get/rejectedbahkan tanpa berlangganan khusus untuk mereka. Namun, bagi klien Anda untuk menerima pesan, itu harus mendengarkan mereka. Untuk informasi lebih lanjut, lihatcatatan tentang pesan Jobs API.

Muatan respons:

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

DimanainProgressJobsdanqueuedJobsmengembalikan daftarJobExecutionSummaryobjek yang memiliki statusIN_PROGRESSatauQUEUED.

Mendapat dan memulai eksekusi pekerjaan tertunda berikutnya untuk suatu hal (statusIN_PROGRESSatauQUEUED).

  • Setiap eksekusi pekerjaan dengan statusIN_PROGRESSdikembalikan terlebih dahulu.

  • Eksekusi pekerjaan dikembalikan sesuai urutan antrian. Ketika sesuatu ditambahkan atau dihapus dari grup target untuk pekerjaan Anda, konfirmasikan urutan peluncuran eksekusi pekerjaan baru apa pun dibandingkan dengan eksekusi pekerjaan yang ada.

  • Jika eksekusi pekerjaan tertunda berikutnya adalahQUEUED, kondisinya berubah menjadiIN_PROGRESSdan rincian status eksekusi pekerjaan ditetapkan seperti yang ditentukan.

  • Jika eksekusi pekerjaan tertunda berikutnya sudahIN_PROGRESS, Rincian statusnya tidak berubah.

  • Jika tidak ada eksekusi pekerjaan yang tertunda, respons tidak menyertakanexecutionbidang.

  • Opsional, Anda dapat membuat timer langkah dengan menetapkan nilai untukstepTimeoutInMinutesproperti. Jika Anda tidak memperbarui nilai properti ini dengan menjalankanUpdateJobExecution, eksekusi pekerjaan kali keluar ketika timer langkah berakhir.

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

Meminta muatan:

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

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

stepTimeOutInMinutes

Menentukan jumlah waktu perangkat ini harus menyelesaikan pelaksanaan pekerjaan ini. Jika status eksekusi pekerjaan tidak disetel ke status terminal sebelum timer ini berakhir, atau sebelum pengatur waktu disetel ulang, (dengan memanggilUpdateJobExecution, mengatur status keIN_PROGRESSdan menentukan nilai batas waktu baru di lapanganstepTimeoutInMinutes) status eksekusi pekerjaan diatur keTIMED_OUT. Menetapkan batas waktu ini tidak berpengaruh pada batas waktu eksekusi pekerjaan yang mungkin telah ditentukan saat pekerjaan dibuat (CreateJobmenggunakantimeoutConfigbidang).

Broker pesan akan menerbitkan$aws/things/thingName/jobs/start-next/accepteddan$aws/things/thingName/jobs/start-next/rejectedbahkan tanpa berlangganan khusus untuk mereka. Namun, bagi klien Anda untuk menerima pesan, itu harus mendengarkan mereka. Untuk informasi lebih lanjut, lihatcatatan tentang pesan Jobs API.

Muatan respons:

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

DimanaexecutionadalahJobExecutionobjek. Misalnya:

{
"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,
}

Mendapat informasi rinci tentang eksekusi pekerjaan.

Anda dapat mengaturjobIdkepada$nextuntuk mengembalikan eksekusi pekerjaan tertunda berikutnya untuk suatu hal (dengan statusIN_PROGRESSatauQUEUED).

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

Meminta muatan:

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

Nama hal yang terkait dengan perangkat.

jobId

Pengenal unik ditugaskan untuk pekerjaan ini ketika itu dibuat.

Atau gunakan$nextuntuk mengembalikan eksekusi pekerjaan tertunda berikutnya untuk suatu hal (dengan statusIN_PROGRESSatauQUEUED). Dalam hal ini, setiap eksekusi pekerjaan dengan statusIN_PROGRESSdikembalikan terlebih dahulu. Eksekusi pekerjaan dikembalikan dalam urutan di mana mereka diciptakan.

executionNumber

(Opsional) Angka yang mengidentifikasi eksekusi pekerjaan di perangkat. Jika tidak ditentukan, eksekusi pekerjaan terbaru dikembalikan.

includeJobDocument

(Opsional) Kecuali diatur kefalse, respon berisi dokumen pekerjaan. Defaultnya adalah true.

Broker pesan akan menerbitkan$aws/things/thingName/jobs/jobId/get/accepteddan$aws/things/thingName/jobs/jobId/get/rejectedbahkan tanpa berlangganan khusus untuk mereka. Namun, bagi klien Anda untuk menerima pesan, itu harus mendengarkan mereka. Untuk informasi lebih lanjut, lihatcatatan tentang pesan Jobs API.

Muatan respons:

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

DimanaexecutionadalahJobExecutionobjek.

Memperbarui status eksekusi pekerjaan. Anda opsional dapat membuat timer langkah dengan menetapkan nilai untukstepTimeoutInMinutesproperti. Jika Anda tidak memperbarui nilai properti ini dengan menjalankanUpdateJobExecutionsekali lagi, eksekusi pekerjaan kali keluar ketika timer langkah berakhir.

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

Meminta 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,statusDetailstidak berubah.

expectedVersion

Versi saat ini diharapkan dari eksekusi pekerjaan. Setiap kali Anda memperbarui eksekusi pekerjaan, versinya bertambah. Jika versi eksekusi pekerjaan disimpan dalamAWS IoTLayanan pekerjaan tidak cocok, pembaruan ditolak denganVersionMismatchkesalahan. SebuahErrorResponseyang berisi data status eksekusi pekerjaan saat ini juga dikembalikan. (Ini membuatnya tidak perlu untuk melakukan yang terpisahDescribeJobExecutionpermintaan untuk mendapatkan data status eksekusi pekerjaan.)

executionNumber

(Opsional) Angka yang mengidentifikasi eksekusi pekerjaan di perangkat. Jika tidak ditentukan, eksekusi pekerjaan terbaru digunakan.

includeJobExecutionState

(Opsional) Bila disertakan dan diatur ketrue, respon berisiJobExecutionStatebidang. Defaultnya adalah false.

includeJobDocument

(Opsional) Bila disertakan dan diatur ketrue, respon berisiJobDocument. Defaultnya adalah false.

stepTimeoutInMinutes

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

Broker pesan akan menerbitkan$aws/things/thingName/jobs/jobId/update/accepteddan$aws/things/thingName/jobs/jobId/update/rejectedbahkan tanpa berlangganan khusus untuk mereka. Namun, bagi klien Anda untuk menerima pesan, itu harus mendengarkan mereka. Untuk informasi lebih lanjut, lihatcatatan tentang pesan Jobs API.

Muatan respons:

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

Sebuah objek JobExecutionState.

jobDocument

SEBUAHdokumen pekerjaanobjek.

timestamp

Waktu dalam hitungan detik sejak zaman, ketika pesan dikirim.

clientToken

Token klien yang digunakan untuk mengkorelasikan permintaan dan tanggapan.

Ketika Anda menggunakan protokol MQTT, Anda juga dapat melakukan pemutakhiran 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 yang eksekusi pekerjaan berikutnya pada daftar eksekusi pekerjaan yang tertunda untuk suatu hal, sebagaimana didefinisikan untukDescribeJobExecutionbersamajobId $next. Pesan ini tidak dikirim ketika rincian eksekusi pekerjaan berikutnya berubah, hanya ketika pekerjaan berikutnya yang akan dikembalikan olehDescribeJobExecutionbersamajobId $nexttelah berubah. Pertimbangkan eksekusi pekerjaan J1 dan J2 dengan statusQUEUED. J1 adalah berikutnya pada daftar eksekusi pekerjaan yang tertunda. Jika status J2 diubah menjadiIN_PROGRESSsementara keadaan 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,
}