Menjadwalkan pekerjaan di beberapa perangkat

  • Artikel

Azure IoT Hub memungkinkan sejumlah blok gedung seperti properti dan tag kembar perangkat dan metode langsung. Biasanya, aplikasi back-end memungkinkan admin dan operator perangkat memperbarui dan berinteraksi dengan perangkat IoT secara massal dan pada waktu yang terjadwal. Jobs menjalankan pembaruan kembar perangkat dan metode langsung terhadap sekumpulan perangkat pada waktu yang dijadwalkan. Misalnya, operator akan menggunakan aplikasi back-end yang memulai dan melacak pekerjaan untuk me-reboot sekumpulan perangkat dalam gedung 43 dan lantai 3 pada waktu yang tidak akan mengganggu pengoperasian gedung.

Catatan

Fitur yang dijelaskan dalam artikel ini hanya tersedia di tingkat standar IoT Hub. Untuk informasi selengkapnya tentang tingkat IoT Hub dasar dan standar/gratis, lihat Memilih tingkat IoT Hub yang tepat untuk solusi Anda.

Pertimbangkan untuk menggunakan pekerjaan saat Anda perlu menjadwalkan dan melacak kemajuan salah satu aktivitas berikut di sekumpulan perangkat:

  • Memperbarui properti yang diinginkan
  • Memperbarui tag
  • Menggunakan metode langsung

Siklus hidup pekerjaan

Pekerjaan diinisiasi oleh back-end solusi dan dikelola oleh IoT Hub. Anda dapat memulai pekerjaan melalui URI yang dapat diakses dari layanan (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2021-04-12) dan mengkueri kemajuan tentang pekerjaan yang dieksekusi melalui URI dapat diakses dari layanan (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12). To me-refresh status pekerjaan yang berjalan setelah pekerjaan dimulai, jalankan kueri pekerjaan. Tidak ada pembersihan eksplisit riwayat pekerjaan, tetapi mereka memiliki TTL 30 hari. 

Catatan

Saat Anda memulai pekerjaan, nama dan nilai properti hanya bisa berisi alfanumerik yang dapat dicetak US-ASCII, kecuali jika ada dalam set berikut: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

Catatan

Bidang jobId harus memiliki 64 karakter atau kurang dan hanya dapat berisi huruf US-ASCII, angka, dan karakter dash (-).

Pekerjaan untuk menjalankan metode langsung

Cuplikan berikut menunjukkan detail permintaan HTTPS 1.1 untuk menjalankan metode langsung di sekumpulan perangkat menggunakan pekerjaan:

PUT /jobs/v2/<jobId>?api-version=2021-04-12

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

{
    "jobId": "<jobId>",
    "type": "scheduleDeviceMethod",
    "cloudToDeviceMethod": {
        "methodName": "<methodName>",
        "payload": <payload>,
        "responseTimeoutInSeconds": methodTimeoutInSeconds
    },
    "queryCondition": "<queryOrDevices>", // query condition
    "startTime": <jobStartTime>,          // as an ISO-8601 date string
    "maxExecutionTimeInSeconds": <maxExecutionTimeInSeconds>
}

Kondisi kueri juga bisa berada di satu ID perangkat atau di daftar ID perangkat seperti yang diperlihatkan dalam contoh berikut:

"queryCondition" = "deviceId = 'MyDevice1'"
"queryCondition" = "deviceId IN ['MyDevice1','MyDevice2']"
"queryCondition" = "deviceId IN ['MyDevice1']"

Bahasa Kueri IoT Hub mencakup bahasa kueri IoT Hub dalam detail tambahan.

Cuplikan berikut menunjukkan permintaan dan respons untuk pekerjaan yang dijadwalkan untuk memanggil metode langsung bernama testMethod di semua perangkat pada contoso-hub-1:

PUT https://contoso-hub-1.azure-devices.net/jobs/v2/job01?api-version=2021-04-12 HTTP/1.1
Authorization: SharedAccessSignature sr=contoso-hub-1.azure-devices.net&sig=68iv------------------------------------v8Hxalg%3D&se=1556849884&skn=iothubowner
Content-Type: application/json; charset=utf-8
Host: contoso-hub-1.azure-devices.net
Content-Length: 317

{
    "jobId": "job01",
    "type": "scheduleDeviceMethod",
    "cloudToDeviceMethod": {
        "methodName": "testMethod",
        "payload": {},
        "responseTimeoutInSeconds": 30
    },
    "queryCondition": "*",
    "startTime": "2019-05-04T15:53:00.077Z",
    "maxExecutionTimeInSeconds": 20
}

HTTP/1.1 200 OK
Content-Length: 65
Content-Type: application/json; charset=utf-8
Vary: Origin
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 03 May 2019 01:46:18 GMT

{"jobId":"job01","type":"scheduleDeviceMethod","status":"queued"}

Pekerjaan untuk memperbarui properti kembar perangkat

Cuplikan berikut menunjukkan detail permintaan HTTPS 1.1 untuk memperbarui properti kembar perangkat menggunakan pekerjaan:

PUT /jobs/v2/<jobId>?api-version=2021-04-12

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

{
    "jobId": "<jobId>",
    "type": "scheduleUpdateTwin",
    "updateTwin": <patch>                 // Valid JSON object
    "queryCondition": "<queryOrDevices>", // query condition
    "startTime": <jobStartTime>,          // as an ISO-8601 date string
    "maxExecutionTimeInSeconds": <maxExecutionTimeInSeconds>
}

Catatan

Properti updateTwin memerlukan pencocokan etag yang valid; misalnya, etag="*".

Cuplikan berikut menunjukkan permintaan dan respons untuk pekerjaan yang dijadwalkan untuk memperbarui properti kembar perangkat untuk perangkat uji pada contoso-hub-1:

PUT https://contoso-hub-1.azure-devices.net/jobs/v2/job02?api-version=2021-04-12 HTTP/1.1
Authorization: SharedAccessSignature sr=contoso-hub-1.azure-devices.net&sig=BN0U-------------------------------------RuA%3D&se=1556925787&skn=iothubowner
Content-Type: application/json; charset=utf-8
Host: contoso-hub-1.azure-devices.net
Content-Length: 339

{
    "jobId": "job02",
    "type": "scheduleUpdateTwin",
    "updateTwin": {
      "properties": {
        "desired": {
          "test1": "value1"
        }
      },
     "etag": "*"
     },
    "queryCondition": "deviceId = 'test-device'",
    "startTime": "2019-05-08T12:19:56.868Z",
    "maxExecutionTimeInSeconds": 20
}

HTTP/1.1 200 OK
Content-Length: 63
Content-Type: application/json; charset=utf-8
Vary: Origin
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 03 May 2019 22:45:13 GMT

{"jobId":"job02","type":"scheduleUpdateTwin","status":"queued"}

Kueri untuk kemajuan pekerjaan

Cuplikan berikut menunjukkan detail permintaan HTTPS 1.1 untuk mengkueri pekerjaan:

GET /jobs/v2/query?api-version=2021-04-12[&jobType=<jobType>][&jobStatus=<jobStatus>][&pageSize=<pageSize>][&continuationToken=<continuationToken>]

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

continuationToken diberikan dari respons.

Anda dapat mengkueri status eksekusi pekerjaan di setiap perangkat menggunakan bahasa kueri IoT Hub untuk twin perangkat, pekerjaan, dan perutean pesan.

Properti Pekerjaan

Daftar berikut memperlihatkan properti dan deskripsi terkait, yang dapat digunakan saat mengkueri pekerjaan atau hasil pekerjaan.

Properti Deskripsi
jobId ID yang disediakan aplikasi untuk pekerjaan.
startTime Waktu mulai yang disediakan aplikasi (ISO-8601) untuk pekerjaan.
endTime Tanggal yang disediakan IoT Hub (ISO-8601) untuk waktu saat pekerjaan selesai. Hanya diterapkan setelah pekerjaan mencapai status 'selesai'.
type Jenis pekerjaan:
scheduleUpdateTwin: Pekerjaan yang digunakan untuk memperbarui sekumpulan properti atau tag yang diinginkan.
scheduleDeviceMethod: Pekerjaan yang digunakan untuk memanggil metode perangkat di sekumpulan twin perangkat.
status Kondisi pekerjaan saat ini. Kemungkinan nilai untuk status:
tertunda: Dijadwalkan dan menunggu dijemput oleh layanan pekerjaan.
dijadwalkan: Dijadwalkan untuk waktu di masa depan.
dijalankan: Pekerjaan yang saat ini aktif.
dibatalkan: Pekerjaan telah dibatalkan.
gagal: Pekerjaan gagal.
selesai: Pekerjaan telah selesai.
deviceJobStatistics Statistik tentang eksekusi pekerjaan.
Properti deviceJobStatistics:
deviceJobStatistics.deviceCount: Jumlah perangkat dalam pekerjaan.
deviceJobStatistics.failedCount: Jumlah perangkat tempat pekerjaan gagal.
deviceJobStatistics.succeededCount: Jumlah perangkat tempat pekerjaan berhasil.
deviceJobStatistics.runningCount: Jumlah perangkat yang saat ini menjalankan pekerjaan.
deviceJobStatistics.pendingCount: Jumlah perangkat yang terlambat menjalankan pekerjaan.

Materi referensi tambahan

Topik referensi lain dalam panduan pengembang IoT Hub meliputi:

Langkah berikutnya

Untuk mencoba beberapa konsep yang dijelaskan dalam artikel ini, lihat tutorial IoT Hub berikut: