IoT Central REST API gebruiken om taken te maken en te beheren

Artikel
10/27/2023

Met de REST API van IoT Central kunt u clienttoepassingen ontwikkelen die kunnen worden geïntegreerd met IoT Central-toepassingen. U kunt de REST API gebruiken om taken te maken en te beheren in uw IoT Central-toepassing. Met de REST API kunt u het volgende doen:

Taken weergeven en taakgegevens weergeven in uw toepassing.
Taken maken in uw toepassing.
Taken stoppen, hervatten en opnieuw uitvoeren in uw toepassing.
Plan taken en bekijk de details van geplande taken in uw toepassing.

Geplande taken worden gemaakt om op een later tijdstip te worden uitgevoerd. U kunt een begindatum en -tijd instellen voor een geplande taak om eenmalig, dagelijks of wekelijks uit te voeren. Niet-geplande taken worden slechts eenmalig uitgevoerd.

In dit artikel wordt beschreven hoe u de /jobs/{job_id} API gebruikt om apparaten bulksgewijs te beheren. U kunt apparaten ook afzonderlijk beheren.

Elke IoT Central REST API-aanroep vereist een autorisatieheader. Zie IoT Central REST API-aanroepen verifiëren en autoriseren voor meer informatie.

Zie de naslaginformatie voor de REST API van IoT Central voor Azure IoT Central.

Zie Apparaten bulksgewijs beheren in uw Azure IoT Central-toepassing voor meer informatie over het maken en beheren van taken in de gebruikersinterface.

Fooi

U kunt Postman gebruiken om de REST API-aanroepen uit te proberen die in dit artikel worden beschreven. Download de IoT Central Postman-verzameling en importeer deze in Postman. In de verzameling moet u variabelen instellen, zoals uw app-subdomein en het beheertoken.

Nettoladingen van taken

Veel van de API's die in dit artikel worden beschreven, bevatten een definitie die eruitziet als het volgende JSON-fragment:

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

In de volgende tabel worden de velden in het vorige JSON-fragment beschreven:

Veld	Beschrijving
`id`	Een unieke id voor de taak in uw toepassing.
`displayName`	De weergavenaam voor de taak in uw toepassing.
`description`	Een beschrijving van de taak.
`group`	De id van de apparaatgroep waarop de taak van toepassing is. Gebruik de `deviceGroups` PREVIEW REST API om een lijst op te halen met de apparaatgroepen in uw toepassing.
`status`	De status van de taak. Een van `complete`, `cancelled`, , `failed`, `pending`, , , `running`, . `stopped`
`batch`	Indien aanwezig, definieert deze sectie hoe de apparaten in de taak in batch worden gebatched .
`batch/type`	De grootte van elke batch is een `percentage` van de totale apparaten in de groep of een van de `number` apparaten.
`batch/value`	Het percentage apparaten of het aantal apparaten in elke batch.
`cancellationThreshold`	Indien aanwezig, definieert deze sectie de annuleringsdrempel voor de taak.
`cancellationThreshold/batch`	`true` of `false`. Indien waar, wordt de annuleringsdrempel ingesteld voor elke batch. Indien `false`, is de annuleringsdrempel van toepassing op de hele taak.
`cancellationThreshold/type`	De annuleringsdrempel voor de taak is een `percentage` of een van de `number` apparaten.
`cancellationThreshold/value`	Het percentage apparaten of het aantal apparaten dat de annuleringsdrempel definieert.
`data`	Een matrix met bewerkingen die de taak uitvoert.
`data/type`	Een van`PropertyJobData`, `CommandJobData`, of `CloudPropertyJobDataDeviceTemplateMigrationJobData`. De preview-versie van de API bevat `DeviceManifestMigrationJobData`.
`data/target`	De model-id van de doelapparaten.
`data/path`	De naam van de eigenschap, opdracht of cloudeigenschap.
`data/value`	De eigenschapswaarde die moet worden ingesteld of de opdrachtparameter die moet worden verzonden.

Taakgegevens ophalen

Gebruik de volgende aanvraag om de lijst met taken in uw toepassing op te halen:

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

Gebruik de volgende aanvraag om een afzonderlijke taak op id op te halen:

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

Gebruik de volgende aanvraag om de details van de apparaten in een taak op te halen:

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

Een taak maken

Gebruik de volgende aanvraag om een taak te maken:

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

Het group veld in de aanvraagbody identificeert een apparaatgroep in uw IoT Central-toepassing. Een taak maakt gebruik van een apparaatgroep om de set apparaten te identificeren waarop de taak werkt.

Als u nog geen geschikte apparaatgroep hebt, kunt u er een maken met een REST API-aanroep. In het volgende voorbeeld wordt een apparaatgroep gemaakt met group1 als groeps-id:

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

Wanneer u een apparaatgroep maakt, definieert u een filter groep die de apparaten selecteert die in de groep moeten worden opgenomen. Een filter identificeert een apparaatsjabloon en eventuele eigenschappen die overeenkomen. In het volgende voorbeeld wordt een apparaatgroep gemaakt die alle apparaten bevat die zijn gekoppeld aan de apparaatsjabloon 'dtmi:modelDefinition:dtdlv2', waarin de provisioned eigenschap zich bevindt true.

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

U kunt nu de id waarde uit het antwoord gebruiken om een nieuwe taak te maken.

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld. De initiële taakstatus 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"
}

Taken stoppen, hervatten en opnieuw uitvoeren

Gebruik de volgende aanvraag om een actieve taak te stoppen:

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

Als de aanvraag slaagt, wordt er een 204 - No Content antwoord geretourneerd.

Gebruik de volgende aanvraag om een gestopte taak te hervatten:

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

Als de aanvraag slaagt, wordt er een 204 - No Content antwoord geretourneerd.

Gebruik de volgende opdracht om een bestaande taak opnieuw uit te voeren op mislukte apparaten:

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

Een geplande taak maken

De nettolading voor een geplande taak is vergelijkbaar met een standaardtaak, maar bevat de volgende extra velden:

Veld	Beschrijving
planning/start	De begindatum en -tijd voor de taak in ISO 8601-indeling
schema/terugkeerpatroon	Een van `daily`, `monthlyyearly \|`
planning/einde	Een optioneel veld dat het aantal exemplaren voor de taak of een einddatum in ISO 8601-indeling aangeeft

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

In het volgende voorbeeld ziet u een aanvraagbody waarmee een geplande taak wordt gemaakt.

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

Een geplande taak ophalen

Gebruik de volgende aanvraag om een geplande taak op te halen:

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

Geplande taken weergeven

Gebruik de volgende aanvraag om een lijst met geplande taken op te halen:

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

Een geplande taak bijwerken

Gebruik de volgende aanvraag om een geplande taak bij te werken:

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

In het volgende voorbeeld ziet u een aanvraagbody waarmee een geplande taak wordt bijgewerkt.

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

Een geplande taak verwijderen

Gebruik de volgende aanvraag om een geplande taak te verwijderen

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

Volgende stappen

Nu u hebt geleerd hoe u taken beheert met de REST API, is er een voorgestelde volgende stap om te leren hoe u zelfstudie leert: De REST API gebruiken om een Azure IoT Central-toepassing te beheren.

IoT Central REST API gebruiken om taken te maken en te beheren

Nettoladingen van taken

Taakgegevens ophalen

Een taak maken

Taken stoppen, hervatten en opnieuw uitvoeren

Een geplande taak maken

Een geplande taak ophalen

Geplande taken weergeven

Een geplande taak bijwerken

Een geplande taak verwijderen

Volgende stappen

Aanvullende resources