Comment utiliser l’API REST IoT Central pour créer et gérer les travaux

Article
10/22/2024

L’API REST IoT Central vous permet de développer des applications clientes qui s’intègrent à des applications IoT Central. Vous pouvez utiliser l’API REST pour gérer et gérer les travaux dans votre application IoT Central. L’API REST vous permet de :

Répertorier les travaux et afficher les détails d’un travail dans votre application.
Créer des travaux dans votre application.
Arrêter, reprendre et réexécuter des travaux dans votre application.
Planifier les travaux et afficher le détail des travaux planifiés dans votre application.

Les travaux planifiés sont créés pour s’exécuter à un moment ultérieur. Vous pouvez définir une date et une heure de début pour qu’un travail planifié s’exécute une fois, tous les jours ou toutes les semaines. Les travaux non planifiés ne s’exécutent qu’une seule fois.

Cet article décrit comment utiliser l’API /jobs/{job_id} pour contrôler les appareils en bloc. Vous pouvez également contrôler les appareils individuellement.

Chaque appel d’API REST IoT Central nécessite un en-tête d’autorisation. Pour plus d’informations, consultez Comment authentifier et autoriser les appels d’API REST d’IoT Central.

Pour obtenir la documentation de référence sur l’API REST IoT Central, consultez Informations de référence sur l’API REST d’Azure IoT Central.

Pour savoir comment créer et gérer des travaux dans l’interface utilisateur, consultez Gérer des appareils en bloc dans votre application Azure IoT Central.

Charges utiles de travail

Nombre des API décrites dans cet article incluent une définition qui ressemble à l’extrait JSON suivant :

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

Le tableau suivant décrit les champs de l’extrait JSON précédent :

Champ	Description
`id`	ID unique du travail dans votre application.
`displayName`	Nom d’affichage du travail dans votre application.
`description`	Description du travail.
`group`	ID du groupe d’appareils auquel le travail s’applique. Utilisez l’API REST `deviceGroups` en préversion pour obtenir la liste des groupes d’appareils dans votre application.
`status`	État du travail. Valeurs possibles : `complete`, `cancelled`, `failed`, `pending`, `running`, `stopped`.
`batch`	Si elle est présente, cette section définit comment regrouper par lots les appareils dans le travail.
`batch/type`	La taille de chaque lot correspond au `percentage` du nombre total d’appareils dans le groupe ou au `number` d’appareils.
`batch/value`	Pourcentage d’appareils ou nombre d’appareils dans chaque lot.
`cancellationThreshold`	Si elle est présente, cette section définit le seuil d’annulation du travail.
`cancellationThreshold/batch`	`true` ou `false`. Si la valeur est true, le seuil d’annulation est défini pour chaque lot. Si la valeur est `false`, le seuil d’annulation s’applique à l’ensemble du travail.
`cancellationThreshold/type`	Le seuil d’annulation du travail est un `percentage` ou un `number` d’appareils.
`cancellationThreshold/value`	Pourcentage d’appareils ou nombre d’appareils qui définit le seuil d’annulation.
`data`	Tableau d’opérations effectuées par le travail.
`data/type`	Un de `PropertyJobData`, `CommandJobData`, `CloudPropertyJobData`, ou `DeviceTemplateMigrationJobData`. La version préliminaire de l’API inclut `DeviceManifestMigrationJobData`.
`data/target`	ID de modèle des appareils cibles.
`data/path`	Nom de la propriété, de la commande ou de la propriété cloud.
`data/value`	Valeur de propriété à définir ou paramètre de commande à envoyer.

Obtenir des informations sur un travail

Utilisez la requête suivante pour récupérer la liste des travaux dans votre application :

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

La réponse à cette demande ressemble à l’exemple suivant :

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

Utilisez la requête suivante pour récupérer un travail individuel par ID :

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

La réponse à cette demande ressemble à l’exemple suivant :

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

Utilisez la requête suivante pour récupérer les détails des appareils dans un travail :

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

La réponse à cette demande ressemble à l’exemple suivant :

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

Créer un travail

Utilisez la demande suivante pour créer un travail :

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

Le champ group du corps de la demande identifie un groupe d’appareils dans votre application IoT Central. Un travail utilise un groupe d’appareils pour identifier l’ensemble des appareils sur lesquels le travail fonctionne.

Si vous n’avez pas encore de groupe d’appareils approprié, vous pouvez en créer un avec l’appel d’API REST. L’exemple suivant crée un groupe d’appareils avec group1 comme ID de groupe :

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

Quand vous créez un groupe d’appareils, vous définissez un filter qui sélectionne les appareils à inclure dans le groupe. Un filtre identifie un modèle d’appareil et toutes les propriétés à mettre en correspondance. L’exemple suivant crée un groupe d’appareils qui contient tous les appareils associés au modèle d’appareil « dtmi:modelDefinition:dtdlv2 » où la propriété provisioned est true.

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

La réponse à cette demande ressemble à l’exemple suivant :

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

Vous pouvez maintenant utiliser la valeur id de la réponse pour créer un travail.

{
  "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 réponse à cette demande se présente comme dans l’exemple suivant. L’état initial du travail est 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"
}

Arrêter, reprendre et réexécuter des travaux

Utilisez la requête suivante pour arrêter un travail en cours d’exécution :

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

Si la requête réussit, elle retourne une réponse 204 - No Content.

Utilisez la requête suivante pour reprendre un travail arrêté :

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

Si la requête réussit, elle retourne une réponse 204 - No Content.

Utilisez la commande suivante pour réexécuter un travail existant sur les appareils défaillants :

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

Créer une tâche planifiée

La charge utile d’un travail planifié ressemble à celle d’une tâche standard, mais avec les champs supplémentaires suivants :

Champ	Description
schedule/start	Date et heure de début du travail au format ISO 8601.
schedule/recurrence	`daily`, `monthly` ou `yearly \|`
schedule/end	(Facultatif) Nombre d’occurrences du travail ou date de fin au format ISO 8601.

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

L’exemple suivant montre un corps de la demande qui crée un travail planifié.

{
    "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 réponse à cette demande ressemble à l’exemple suivant :

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

Récupération d’un travail planifié

Utilisez la demande suivante pour obtenir un travail planifié :

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

La réponse à cette demande ressemble à l’exemple suivant :

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

Affichage de la liste des travaux planifiés

Utilisez la demande suivante pour obtenir la liste des travaux planifiés :

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

La réponse à cette demande ressemble à l’exemple suivant :

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

Mise à jour d’un travail planifié

Utilisez la demande suivante pour mettre à jour un travail planifié :

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

L’exemple suivant montre un corps de la demande qui met à jour un travail planifié.

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

La réponse à cette demande ressemble à l’exemple suivant :

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

Supprimer une tâche planifiée

Utilisez la demande suivante pour supprimer un travail planifié :

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

Étapes suivantes

Maintenant que vous avez appris à gérer les travaux avec l’API REST, l’étape suivante suggérée consiste à découvrir comment Tutoriel : Utiliser l’API REST pour gérer une application Azure IoT Central.

Partager via

Comment utiliser l’API REST IoT Central pour créer et gérer les travaux

Charges utiles de travail

Obtenir des informations sur un travail

Créer un travail

Arrêter, reprendre et réexécuter des travaux

Créer une tâche planifiée

Récupération d’un travail planifié

Affichage de la liste des travaux planifiés

Mise à jour d’un travail planifié

Supprimer une tâche planifiée

Étapes suivantes

Commentaires

Ressources supplémentaires