如何使用 IoT Central REST API 來建立和管理作業

文章
05/10/2024

IoT Central REST API 可讓您開發與 IoT Central 應用程式整合的用戶端應用程式。您可以使用 REST API 在 IoT Central 應用程式中建立和管理作業。 REST API 可讓您：

在應用程式中列出作業以及檢視作業詳細資料。
在應用程式中建立作業。
停止、繼續及重新執行應用程式中的作業。
在應用程式中排程作業，以及檢視排程作業詳細資料。

建立的排程作業會在未來的某個時間執行。您可以設定排程作業的開始日期和時間，以執行一次、或是每日或每週執行。非排程作業只會執行一次。

本文說明如何使用 /jobs/{job_id} API 大量控制裝置。您也可以個別控制裝置。

每個 IoT Central REST API 呼叫都需要授權標頭。若要深入了解，請參閱如何驗證和授權 IoT Central REST API 呼叫。

如需 IoT Central REST API 的參考文件，請參閱 Azure IoT Central REST API 參考。

若要了解如何在 UI 中建立和管理作業，請參閱在 Azure IoT Central 應用程式中大量管理裝置。

提示

您可以使用 Postman 來試用本文中所述的 REST API 呼叫。下載 IoT Central Postman 集合，並將其匯入 Postman 中。在該集合中，您必須設定變數，例如應用程式子網域和管理員權杖。

作業承載

本文說明的許多 API 都包含類似於下列 JSON 程式碼片段的定義：

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

下表說明前述 JSON 程式碼片段中的欄位：

欄位	描述
`id`	應用程式中作業的唯一識別碼。
`displayName`	應用程式中作業的顯示名稱。
`description`	作業的描述。
`group`	適用作業之裝置群組的識別碼。使用 `deviceGroups` 預覽 REST API 取得應用程式中的裝置群組清單。
`status`	作業的狀態。 `complete`、`cancelled`、`failed`、`pending`、`running`、`stopped` 的其中之一。
`batch`	如果有的話，此區段會定義如何批次處理作業中的裝置。
`batch/type`	每個批次的大小是群組中裝置總數的 `percentage` 或裝置的 `number`。
`batch/value`	每個批次中的裝置百分比或裝置數目。
`cancellationThreshold`	如果有的話，此區段會定義作業的取消閾值。
`cancellationThreshold/batch`	`true` 或 `false`。若為 true，則會設定每個批次的取消閾值。若為 `false`，則取消閾值會套用至整個作業。
`cancellationThreshold/type`	作業的取消閾值為裝置的 `percentage` 或 `number`。
`cancellationThreshold/value`	定義取消閾值的裝置百分比或裝置數目。
`data`	作業執行的作業陣列。
`data/type`	`PropertyJobData`、`CommandJobData`、`CloudPropertyJobData` 或 `DeviceTemplateMigrationJobData` 的其中之一。。 API 的預覽版本包含 `DeviceManifestMigrationJobData`。
`data/target`	目標裝置的型號識別碼。
`data/path`	屬性、命令或雲端屬性的名稱。
`data/value`	要設定的屬性值，或要傳送的命令參數。

取得作業資訊

使用下列要求來擷取應用程式中的作業清單：

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

此要求的回應如下列範例所示：

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

使用下列要求，依識別碼擷取個別作業：

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

此要求的回應如下列範例所示：

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

使用下列要求來擷取作業中裝置的詳細資料：

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

此要求的回應如下列範例所示：

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

建立作業

使用下列要求來建立作業：

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

要求本文中的 group 欄位會識別 IoT Central 應用程式中的裝置群組。作業會使用裝置群組來識別作業所操作的一組裝置。

如果您還沒有適當的裝置群組，可以使用 REST API 呼叫建立一個。下列範例會以群組識別碼 group1 建立裝置群組：

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

當您建立裝置群組時，您會定義 filter 以選取要納入群組中的裝置。篩選條件會識別裝置範本和要比對的任何屬性。下列範例會建立裝置群組，其中包含與 "dtmi:modelDefinition:dtdlv2" 裝置範本相關聯且 provisioned 屬性為 true 的所有裝置。

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

此要求的回應如下列範例所示：

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

現在，您可以使用回應中的 id 值來建立新作業。

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

此要求的回應看起來會如同下列範例。初始作業狀態為 pending：

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

停止、繼續及重新執行作業

使用下列要求來停止執行中的作業：

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

如果要求成功，則會傳回 204 - No Content 回應。

使用下列要求來繼續先前停止的作業：

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

如果要求成功，則會傳回 204 - No Content 回應。

使用下列命令，在任何失敗的裝置上重新執行現有的作業：

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

建立排程工作

排程作業的承載類似於標準作業，但包含下列額外的欄位：

欄位	描述
排程/開始	作業的開始日期和時間，格式為 ISO 8601
排程/週期	`daily`、`monthly`、`yearly \|` 的其中之一
排程/結束	選擇性欄位，指定作業的執行次數或 ISO 8601 格式的結束日期

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

下列範例顯示會建立排程作業的要求本文。

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

此要求的回應如下列範例所示：

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

取得排程作業

使用下列要求來取得排程作業：

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

此要求的回應如下列範例所示：

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

列出排程作業

使用下列要求來取得排程作業的清單：

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

此要求的回應如下列範例所示：

{
    "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\""
        }
    ]
}

更新排程作業

使用下列要求來更新排程作業：

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

下列範例顯示會更新排程作業的要求本文。

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

此要求的回應如下列範例所示：

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

刪除排程工作

使用下列要求來刪除排程作業

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

下一步

現在您已了解如何使用 REST API 來管理作業，建議您接著了解如何使用 REST API 管理 Azure IoT Central 應用程式。

分享方式：

如何使用 IoT Central REST API 來建立和管理作業

作業承載

取得作業資訊

建立作業

停止、繼續及重新執行作業

建立排程工作

取得排程作業

列出排程作業

更新排程作業

刪除排程工作

下一步

意見反映

意見反映

更多資源