Cara menggunakan REST API IoT Central untuk membuat dan mengelola pekerjaan

  • Artikel

IoT Central REST API memungkinkan Anda mengembangkan aplikasi klien yang terintegrasi dengan aplikasi IoT Central. Anda dapat menggunakan REST API untuk membuat mengelola pekerjaan di aplikasi IoT Central Anda. REST API memungkinkan Anda:

  • Cantumkan pekerjaan dan tampilan detail pekerjaan dalam aplikasi Anda.
  • Membuat pekerjaan di aplikasi Anda.
  • Hentikan, lanjutkan, dan jalankan kembali pekerjaan di aplikasi Anda.
  • Jadwalkan pekerjaan dan lihat detail pekerjaan terjadwal di aplikasi Anda.

Pekerjaan terjadwal dibuat untuk dijalankan pada waktu mendatang. Anda dapat mengatur tanggal dan waktu mulai untuk pekerjaan terjadwal agar berjalan satu kali, harian, atau mingguan. Pekerjaan yang tidak terjadwal hanya berjalan satu kali.

Artikel ini menjelaskan cara menggunakan API /jobs/{job_id} untuk mengontrol perangkat secara massal. Anda juga dapat mengontrol perangkat secara individual.

Setiap panggilan IoT Central REST API memerlukan header otorisasi. Untuk mempelajari selengkapnya, lihat Cara mengautentikasi dan mengotorisasi panggilan IoT Central REST API.

Untuk dokumentasi referensi untuk IoT Central REST API, lihat Referensi IoT Central REST API.

Untuk mempelajari cara membuat dan mengelola pekerjaan di UI, lihat Mengelola perangkat dalam jumlah besar di aplikasi Azure IoT Central Anda.

Tip

Anda dapat menggunakan Postman untuk mencoba panggilan REST API yang dijelaskan dalam artikel ini. Unduh koleksi IoT Central Postman dan impor ke Postman. Dalam koleksi, Anda harus mengatur variabel seperti subdomain aplikasi dan token admin.

{i>Payload

Sejumlah API yang dijelaskan dalam artikel ini menyertakan definisi yang terlihat seperti cuplikan JSON berikut:

{
  "id": "job-014",
  "displayName": "Set target temperature",
  "description": "Set target temperature for all thermostat devices",
  "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "56"
    }
  ],
  "status": "complete"
}

Tabel berikut ini menjelaskan bidang dalam cuplikan JSON sebelumnya:

Bidang Deskripsi
id ID unik untuk pekerjaan di aplikasi Anda.
displayName Nama tampilan untuk pekerjaan di aplikasi Anda.
description Deskripsi dari pekerjaan.
group ID grup perangkat di mana pekerjaan diterapkan. Gunakan pratinjau deviceGroups REST API untuk mendapatkan daftar grup perangkat di aplikasi Anda.
status Status pekerjaan. Salah satu dari complete, cancelled, failed, pending, running, stopped.
batch Jika ada, bagian ini menentukan cara membuat batch perangkat dalam pekerjaan.
batch/type Ukuran setiap batch adalah salah satu percentage dari total perangkat dalam grup atau number perangkat.
batch/value Baik persentase perangkat atau jumlah perangkat di setiap {i>batch
cancellationThreshold Jika tersedia, bagian ini menentukan ambang pembatalan untuk pekerjaan.
cancellationThreshold/batch true atau false. Jika benar, ambang pembatalan ditetapkan untuk setiap {i>batchfalse, ambang pembatalan berlaku untuk seluruh pekerjaan.
cancellationThreshold/type Ambang pembatalan untuk pekerjaan berupa percentage atau number perangkat.
cancellationThreshold/value Baik persentase perangkat atau jumlah perangkat yang menentukan ambang pembatalan.
data {i>Array
data/type Salah satu dari PropertyJobData, CommandJobData, CloudPropertyJobData, atau DeviceTemplateMigrationJobData. Versi pratinjau API mencakup DeviceManifestMigrationJobData.
data/target ID model dari perangkat target.
data/path Nama properti, perintah, atau properti {i>cloud
data/value Nilai properti yang akan ditetapkan atau parameter perintah yang akan dikirim.

Dapatkan informasi pekerjaan

Gunakan permintaan berikut untuk mengambil daftar pekerjaan di aplikasi Anda:

GET https://{your app subdomain}.azureiotcentral.com/api/jobs?api-version=2022-07-31

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "value": [
    {
      "id": "job-006",
      "displayName": "Set customer name",
      "description": "Set the customer name cloud property",
      "group": "4fcbec3b-5ee8-4324-855d-0f03b56bcf7f",
      "data": [
        {
          "type": "CloudPropertyJobData",
          "target": "dtmi:modelDefinition:bojo9tfju:yfvu5gv2vl",
          "path": "CustomerName",
          "value": "Contoso"
        }
      ],
      "status": "complete"
    },
    {
      "id": "job-005",
      "displayName": "Set target temperature",
      "description": "Set target temperature device property",
      "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
      "data": [
        {
          "type": "PropertyJobData",
          "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
          "path": "targetTemperature",
          "value": 56
        }
      ],
      "status": "complete"
    },
    {
      "id": "job-004",
      "displayName": "Run device report",
      "description": "Call command to run the device reports",
      "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
      "batch": {
        "type": "percentage",
        "value": 25
      },
      "cancellationThreshold": {
        "type": "percentage",
        "value": 10,
        "batch": false
      },
      "data": [
        {
          "type": "CommandJobData",
          "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
          "path": "getMaxMinReport",
          "value": "2021-06-15T05:00:00.000Z"
        }
      ],
      "status": "complete"
    }
  ]
}

Gunakan permintaan berikut untuk mengambil pekerjaan individu berdasarkan ID:

GET https://{your app subdomain}.azureiotcentral.com/api/jobs/job-004?api-version=2022-07-31

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "job-004",
  "displayName": "Run device report",
  "description": "Call command to run the device reports",
  "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "CommandJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "getMaxMinReport",
      "value": "2021-06-15T05:00:00.000Z"
    }
  ],
  "status": "complete"
}

Gunakan permintaan berikut untuk mengambil detail perangkat dalam suatu pekerjaan:

GET https://{your app subdomain}.azureiotcentral.com/api/jobs/job-004/devices?api-version=2022-07-31

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "value": [
    {
      "id": "therm-01",
      "status": "completed"
    },
    {
      "id": "therm-02",
      "status": "completed"
    },
    {
      "id": "therm-03",
      "status": "completed"
    },
    {
      "id": "therm-04",
      "status": "completed"
    }
  ]
}

Membuat pekerjaan

Gunakan permintaan berikut untuk membuat pekerjaan:

PUT https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006?api-version=2022-07-31

Bidang group dalam isi permintaan mengidentifikasi grup perangkat di aplikasi IoT Central Anda. Pekerjaan menggunakan grup perangkat untuk mengidentifikasi kumpulan perangkat tempat pekerjaan beroperasi.

Jika Anda belum memiliki grup perangkat yang sesuai, Anda dapat membuatnya dengan panggilan REST API. Contoh berikut membuat grup perangkat dengan group1 sebagai ID grup:

PUT https://{your app subdomain}/api/deviceGroups/group1?api-version=2022-07-31

Saat membuat grup perangkat, Anda menentukan filter yang memilih perangkat untuk disertakan dalam grup. Filter mengidentifikasi templat perangkat dan properti apa pun yang cocok. Contoh berikut membuat grup perangkat yang berisi semua perangkat yang terkait dengan templat perangkat "dtmi:modelDefinition:dtdlv2" di mana provisioned properti adalah true.

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true"
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true"
}

Anda sekarang dapat menggunakan id nilai dari respons untuk membuat pekerjaan baru.

{
  "displayName": "Set target temperature",
  "description": "Set target temperature device property",
  "group": "group1",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "55"
    }
  ]
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut. Status pekerjaan awal pending adalah:

{
  "id": "job-006",
  "displayName": "Set target temperature",
  "description": "Set target temperature device property",
  "group": "group1",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "55"
    }
  ],
  "status": "pending"
}

Hentikan, lanjutkan, dan jalankan kembali pekerjaan

Gunakan permintaan berikut untuk menghentikan pekerjaan yang sedang berjalan:

POST https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/stop?api-version=2022-07-31

Jika permintaan berhasil, maka Anda akan mendapatkan respons 204 - No Content.

Gunakan permintaan berikut untuk melanjutkan pekerjaan yang terhenti:

POST https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/resume?api-version=2022-07-31

Jika permintaan berhasil, maka Anda akan mendapatkan respons 204 - No Content.

Gunakan perintah berikut untuk menjalankan kembali pekerjaan yang ada di perangkat yang gagal:

PUT https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/rerun/rerun-001?api-version=2022-07-31

Membuat pekerjaan terjadwal

Payload untuk pekerjaan terjadwal mirip dengan pekerjaan standar tetapi mencakup bidang tambahan berikut:

Bidang Deskripsi
schedule/start Tanggal dan waktu mulai untuk pekerjaan dalam format ISO 8601
jadwal/pengulangan Salah satu dari daily, monthly, yearly |
schedule/end Bidang opsional yang menentukan jumlah kemunculan untuk pekerjaan atau tanggal akhir dalam format ISO 8601 
PUT https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

Contoh berikut menunjukkan isi permintaan yang membuat pekerjaan terjadwal.

{
    "displayName": "New Scheduled Job",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily",
        "end": {
            "type": "date",
            "date": "2022-12-30"
        }
    }
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily",
        "end": {
            "type": "date",
            "date": "2022-12-30"
        }
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

Mendapatkan pekerjaan terjadwal

Gunakan permintaan berikut untuk mendapatkan pekerjaan terjadwal:

GET https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily"
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

Mencantumkan pekerjaan terjadwal

Gunakan permintaan berikut untuk mendapatkan daftar pekerjaan terjadwal:

GET https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs?api-version=2022-07-31

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "value": [
        {
            "id": "scheduled-Job-001",
            "displayName": "New Scheduled Job",
            "description": "",
            "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
            "data": [
                {
                    "type": "cloudProperty",
                    "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
                    "path": "Company",
                    "value": "Contoso"
                }
            ],
            "schedule": {
                "start": "2022-10-24T22:29:01Z",
                "recurrence": "daily"
            },
            "enabled": false,
            "completed": false,
            "etag": "\"88003877-0000-0700-0000-631020670000\""
        },
        {
            "id": "46480dff-dc22-4542-924e-a5d45bf347aa",
            "displayName": "test",
            "description": "",
            "group": "cdd04344-bb55-425b-a55a-954d68383289",
            "data": [
                {
                    "type": "cloudProperty",
                    "target": "dtmi:rigado:evxfmi0xim",
                    "path": "test",
                    "value": 2
                }
            ],
            "schedule": {
                "start": "2022-09-01T03:00:00.000Z"
            },
            "enabled": true,
            "completed": true,
            "etag": "\"88000f76-0000-0700-0000-631020310000\""
        }
    ]
}

Memperbarui pekerjaan terjadwal

Gunakan permintaan berikut untuk memperbarui pekerjaan terjadwal:

PATCH https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

Contoh berikut menunjukkan isi permintaan yang memperbarui pekerjaan terjadwal.

{
  "schedule": {
    "start": "2022-10-24T22:29:01Z",
    "recurrence": "weekly"
  }
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "weekly"
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

Menghapus pekerjaan terjadwal

Gunakan permintaan berikut untuk menghapus pekerjaan terjadwal

GET https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

Langkah berikutnya

Sekarang setelah Anda mempelajari cara mengelola pekerjaan dengan REST API, langkah selanjutnya yang disarankan adalah mempelajari cara Tutorial: Menggunakan REST API untuk mengelola aplikasi Azure IoT Central.