Povratne informacije Uredi

How to use the IoT Central REST API to create and manage jobs

  • Članak
  • 6 min. za čitanje

The IoT Central REST API lets you develop client applications that integrate with IoT Central applications. You can use the REST API to create and manage jobs in your IoT Central application. The REST API lets you:

  • List jobs and view job details in your application.
  • Create jobs in your application.
  • Stop, resume, and rerun jobs in your application.

Important

The jobs API is currently in preview. All The REST API calls described in this article should include ?api-version=1.2-preview.

This article describes how to use the /jobs/{job_id} API to control devices in bulk. You can also control devices individually.

Every IoT Central REST API call requires an authorization header. To learn more, see How to authenticate and authorize IoT Central REST API calls.

For the reference documentation for the IoT Central REST API, see Azure IoT Central REST API reference.

To learn how to create and manage jobs in the UI, see Manage devices in bulk in your Azure IoT Central application.

Tip

You can use Postman to try out the REST API calls described in this article. Download the IoT Central Postman collection and import it into Postman. In the collection, you'll need to set variables such as your app subdomain and admin token.

To learn how to manage jobs by using the IoT Central UI, see Manage devices in bulk in your Azure IoT Central application.

Job payloads

Many of the APIs described in this article include a definition that looks like the following JSON snippet:

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

The following table describes the fields in the previous JSON snippet:

Field Description
id A unique ID for the job in your application.
displayName The display name for the job in your application.
description A description of the job.
group The ID of the device group that the job applies to. Use the deviceGroups preview REST API to get a list of the device groups in your application.
status The status of the job. One of complete, cancelled, failed, pending, running, stopped.
batch If present, this section defines how to batch the devices in the job.
batch/type The size of each batch is either a percentage of the total devices in the group or a number of devices.
batch/value Either the percentage of devices or the number of devices in each batch.
cancellationThreshold If present, this section defines the cancellation threshold for the job.
cancellationThreshold/batch true or false. If true, the cancellation threshold is set for each batch. If false, the cancellation threshold applies to the whole job.
cancellationThreshold/type The cancellation threshold for the job is either a percentage or a number of devices.
cancellationThreshold/value Either the percentage of devices or the number of devices that define the cancellation threshold.
data An array of operations the job performs.
data/type One of PropertyJobData, CommandJobData, or CloudPropertyJobData
data/target The model ID of the target devices.
data/path The name of the property, command, or cloud property.
data/value The property value to set or the command parameter to send.

Get job information

Use the following request to retrieve the list of the jobs in your application:

GET https://{your app subdomain}.azureiotcentral.com/api/jobs?api-version=1.2-preview

The response to this request looks like the following example:

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

Use the following request to retrieve an individual job by ID:

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

The response to this request looks like the following example:

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

Use the following request to retrieve the details of the devices in a job:

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

The response to this request looks like the following example:

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

Create a job

Use the following request to create a job:

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

The group field in the request body identifies a device group in your IoT Central application. A job uses a device group to identify the set of devices the job operates on.

If you don't already have a suitable device group, you can create one with REST API call. The following example creates a device group with group1 as the group ID:

PUT https://{subdomain}.{baseDomain}/api/deviceGroups/group1?api-version=1.2-preview

When you create a device group, you define a filter that selects the devices to include in the group. A filter identifies a device template and any properties to match. The following example creates device group that contains all devices associated with the "dtmi:modelDefinition:dtdlv2" device template where the provisioned property is true.

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

The response to this request looks like the following example:

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

You can now use the id value from the response to create a new job.

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

The response to this request looks like the following example. The initial job status is 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"
}

Stop, resume, and rerun jobs

Use the following request to stop a running job:

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

If the request succeeds, it returns a 204 - No Content response.

Use the following request to resume a stopped job:

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

If the request succeeds, it returns a 204 - No Content response.

Use the following command to rerun an existing job on any failed devices:

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

Next steps

Now that you've learned how to manage jobs with the REST API, a suggested next step is to learn how to Manage IoT Central applications with the REST API.