Share via

Uso de la API REST de IoT Central para crear y administrar trabajos

  • Artículo

La API de REST de IoT Central permite desarrollar aplicaciones cliente que se integran con aplicaciones de IoT Central. Puede usar la API REST para crear y administrar trabajos en la aplicación de IoT Central. La API de REST permite:

  • Mostrar los trabajos y ver los detalles en la aplicación.
  • Crear trabajos en la aplicación.
  • Detener, reanudar y volver a ejecutar trabajos en la aplicación.
  • Programar trabajos y ver los detalles del trabajo programado en la aplicación.

Los trabajos programados se crean para que se ejecuten en un momento futuro. Puede establecer una fecha y hora de inicio para que un trabajo programado se ejecute una vez, todos los días o todas las semanas. Los trabajos no programados solo se ejecutan una vez.

En este artículo se explica cómo usar la API /jobs/{job_id} para controlar dispositivos en masa. También puede controlar los dispositivos de forma individual.

Cada llamada a la API REST de IoT Central requiere un encabezado de autorización. Para obtener más información, vea los procedimientos de autenticación y autorización de llamadas a la API REST de IoT Central.

Para ver la documentación de referencia sobre la API REST de IoT Central, consulte Referencia de la API REST de Azure IoT Central.

Para obtener información sobre cómo crear y administrar trabajos en la interfaz de usuario, consulte Administración de dispositivos de forma masiva en Azure IoT Central.

Sugerencia

Puede usar Postman para probar las llamadas API REST que se describen en este artículo. Descargue la colección de Postman de IoT Central e impórtela en Postman. En la colección, deberá establecer variables como el subdominio de la aplicación y el token de administrador.

Cargas de trabajo

Muchas de las API que se describen en este artículo incluyen una definición similar al siguiente fragmento de código 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"
}

En la siguiente tabla se describen los campos del fragmento de código JSON anterior:

Campo Descripción
id Identificador único del trabajo en la aplicación.
displayName Nombre para mostrar del trabajo en la aplicación.
description Descripción del trabajo.
group Identificador del grupo de dispositivos al que se aplica el trabajo. Use la API REST en versión preliminar deviceGroups para obtener una lista de los grupos de dispositivos de la aplicación.
status El estado del trabajo. Uno de estos valores: complete, cancelled, failed, pending, running, stopped.
batch Si existe, en esta sección se define cómo procesar por lotes los dispositivos en el trabajo.
batch/type El tamaño de cada lote es un valor de percentage de los dispositivos totales del grupo o un valor de number de dispositivos.
batch/value El porcentaje de dispositivos o el número de dispositivos de cada lote.
cancellationThreshold Si existe, en esta sección se define el umbral de cancelación del trabajo.
cancellationThreshold/batch true o false. Si es true, se establece el umbral de cancelación de cada lote. Si es false, el umbral de cancelación se aplica a todo el trabajo.
cancellationThreshold/type El umbral de cancelación del trabajo es un valor de percentage o un valor de number de dispositivos.
cancellationThreshold/value El porcentaje de dispositivos o el número de dispositivos que definen el umbral de cancelación.
data Matriz de operaciones que realiza el trabajo.
data/type Uno de los siguientes: PropertyJobData, CommandJobData, CloudPropertyJobData o DeviceTemplateMigrationJobData. La versión preliminar de la API incluye DeviceManifestMigrationJobData.
data/target El identificador del modelo de los dispositivos de destino
data/path Nombre de la propiedad, comando o propiedad de nube.
data/value Valor de propiedad que se establece o el parámetro de comando que se envía.

Obtención de información del trabajo

Use la siguiente solicitud para recuperar la lista de trabajos de la aplicación:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "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 la siguiente solicitud para recuperar un trabajo individual por el identificador:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "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 la siguiente solicitud para recuperar los detalles de los dispositivos de un trabajo:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Creación de un trabajo

Use la siguiente solicitud para crear un trabajo.

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

El campo group del cuerpo de la solicitud identifica un grupo de dispositivos en la aplicación de IoT Central. Un trabajo usa un grupo de dispositivos para identificar el conjunto de dispositivos en los que opera.

Si aún no tiene un grupo de dispositivos adecuado, puede crear uno con la llamada a la API REST. En el ejemplo siguiente se crea un grupo de dispositivos con group1 como identificador de grupo:

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

Al crear un grupo de dispositivos, se define un objeto filter que selecciona los dispositivos que se incluirán en el grupo. Un filtro identifica una plantilla de dispositivo y cualquier propiedad que coincida. En el ejemplo siguiente se crea un grupo de dispositivos que contiene todos los dispositivos asociados a la plantilla "dtmi:modelDefinition:dtdlv2", donde la propiedad provisioned es true.

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Ahora puede usar el valor id de la respuesta para crear un nuevo trabajo.

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

La respuesta a esta solicitud es similar al ejemplo siguiente. El estado inicial del trabajo es 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"
}

Detener, reanudar y volver a ejecutar trabajos

Use la solicitud siguiente para detener un trabajo en ejecución:

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

Si la solicitud se realiza correctamente, devuelve una respuesta 204 - No Content.

Use la solicitud siguiente para reanudar un trabajo detenido:

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

Si la solicitud se realiza correctamente, devuelve una respuesta 204 - No Content.

Use el siguiente comando para volver a ejecutar un trabajo existente en los dispositivos con errores:

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

Creación de un trabajo programado

La carga de un trabajo programado es similar a un trabajo estándar, pero incluye los siguientes campos adicionales:

Campo Descripción
programación/inicio Fecha y hora de inicio del trabajo en formato ISO 8601.
programación/periodicidad Uno de estos valores: daily, monthly, yearly |
programación/fin Campo opcional que especifica el número de repeticiones del trabajo o una fecha de finalización en formato ISO 8601. 
PUT https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

En el ejemplo siguiente se muestra un cuerpo de solicitud que crea un trabajo programado.

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Obtención de un trabajo programado

Use la siguiente solicitud para obtener un trabajo programado:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Enumeración de trabajos programados

Use la siguiente solicitud para obtener una lista de trabajos programados:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Actualización de un trabajo programado

Use la siguiente solicitud para actualizar un trabajo programado:

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

En el ejemplo siguiente se muestra un cuerpo de solicitud que actualiza un trabajo programado.

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Eliminación de un trabajo programado

Use la siguiente solicitud para eliminar un trabajo programado.

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

Pasos siguientes

Ahora que ha aprendido a administrar trabajos con la API REST, el siguiente paso recomendado es consultar el tutorial de uso de API REST para administrar aplicaciones de Azure IoT Central.