Dela via

Använda IoT Central REST API till att skapa och hantera jobb

  • Artikel

Med REST API för IoT Central kan du utveckla klientprogram som integreras med IoT Central-program. Du kan använda REST-API:et för att skapa och hantera jobb i ditt IoT Central-program. Med REST-API:et kan du:

  • Visa jobb och visa jobbinformation i ditt program.
  • Skapa jobb i ditt program.
  • Stoppa, återuppta och kör jobb igen i programmet.
  • Schemalägg jobb och visa schemalagd jobbinformation i ditt program.

Schemalagda jobb skapas för körning vid en framtida tidpunkt. Du kan ange startdatum och tid för ett schemalagt jobb som ska köras en gång, varje dag eller varje vecka. Icke-schemalagda jobb körs bara en gång.

Den här artikeln beskriver hur du använder API:et /jobs/{job_id} för att styra enheter i grupp. Du kan också styra enheter individuellt.

Varje IoT Central REST API-anrop kräver ett auktoriseringshuvud. Mer information finns i Autentisera och auktorisera IoT Central REST API-anrop.

Referensdokumentationen för REST API:et för IoT Central finns i Referens för Rest API för Azure IoT Central.

Information om hur du skapar och hanterar jobb i användargränssnittet finns i Hantera enheter i grupp i ditt Azure IoT Central-program.

Nyttolaster för jobb

Många av API:erna som beskrivs i den här artikeln innehåller en definition som ser ut som följande JSON-kodfragment:

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

I följande tabell beskrivs fälten i föregående JSON-kodfragment:

Fält beskrivning
id Ett unikt ID för jobbet i ditt program.
displayName Visningsnamnet för jobbet i programmet.
description En beskrivning av jobbet.
group ID:t för den enhetsgrupp som jobbet gäller för. Använd rest-API:et deviceGroups för förhandsversion för att hämta en lista över enhetsgrupperna i ditt program.
status Jobbets status . En av complete, cancelled, failed, pending, running, . stopped
batch Om det finns definierar det här avsnittet hur du batchar enheterna i jobbet.
batch/type Storleken på varje batch är antingen en percentage av de totala enheterna i gruppen eller en number av enheterna.
batch/value Antingen procentandelen enheter eller antalet enheter i varje batch.
cancellationThreshold Om det finns definierar det här avsnittet tröskelvärdet för annullering för jobbet.
cancellationThreshold/batch true eller false. Om sant anges tröskelvärdet för annullering för varje batch. Om falsegäller tröskelvärdet för annullering för hela jobbet.
cancellationThreshold/type Annulleringströskeln för jobbet är antingen en percentage eller en number av enheterna.
cancellationThreshold/value Antingen procentandelen enheter eller antalet enheter som definierar tröskelvärdet för annullering.
data En matris med åtgärder som jobbet utför.
data/type En av PropertyJobData, CommandJobData, CloudPropertyJobDataeller DeviceTemplateMigrationJobData. Förhandsversionen av API:et innehåller DeviceManifestMigrationJobData.
data/target Modell-ID för målenheterna.
data/path Namnet på egenskapen, kommandot eller molnegenskapen.
data/value Egenskapsvärdet som ska anges eller kommandoparametern som ska skickas.

Hämta jobbinformation

Använd följande begäran för att hämta listan över jobben i ditt program:

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

Svaret på den här begäran ser ut som i följande exempel:

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

Använd följande begäran för att hämta ett enskilt jobb efter ID:

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

Svaret på den här begäran ser ut som i följande exempel:

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

Använd följande begäran för att hämta information om enheterna i ett jobb:

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

Svaret på den här begäran ser ut som i följande exempel:

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

Skapa ett jobb

Använd följande begäran för att skapa ett jobb:

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

Fältet group i begärandetexten identifierar en enhetsgrupp i ditt IoT Central-program. Ett jobb använder en enhetsgrupp för att identifiera vilken uppsättning enheter jobbet körs på.

Om du inte redan har en lämplig enhetsgrupp kan du skapa en med REST API-anrop. I följande exempel skapas en enhetsgrupp med group1 som grupp-ID:

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

När du skapar en enhetsgrupp definierar du en filter som väljer vilka enheter som ska ingå i gruppen. Ett filter identifierar en enhetsmall och eventuella egenskaper som ska matchas. I följande exempel skapas en enhetsgrupp som innehåller alla enheter som är associerade med enhetsmallen "dtmi:modelDefinition:dtdlv2" där provisioned egenskapen är true.

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

Svaret på den här begäran ser ut som i följande exempel:

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

Du kan nu använda id värdet från svaret för att skapa ett nytt jobb.

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

Svaret på den här begäran ser ut som i följande exempel. Den inledande jobbstatusen är 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"
}

Stoppa, återuppta och köra jobb igen

Använd följande begäran för att stoppa ett jobb som körs:

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

Om begäran lyckas returnerar den ett 204 - No Content svar.

Använd följande begäran för att återuppta ett stoppat jobb:

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

Om begäran lyckas returnerar den ett 204 - No Content svar.

Använd följande kommando för att köra ett befintligt jobb på alla misslyckade enheter:

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

Skapa ett schemalagt jobb

Nyttolasten för ett schemalagt jobb liknar ett standardjobb men innehåller följande extra fält:

Fält beskrivning
schema/start Startdatum och tid för jobbet i ISO 8601-format
schema/upprepning En av daily, monthly, yearly |
schema/slut Ett valfritt fält som antingen anger antalet förekomster för jobbet eller ett slutdatum i ISO 8601-format 
PUT https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

I följande exempel visas en begärandetext som skapar ett schemalagt jobb.

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

Svaret på den här begäran ser ut som i följande exempel:

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

Hämta ett schemalagt jobb

Använd följande begäran för att hämta ett schemalagt jobb:

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

Svaret på den här begäran ser ut som i följande exempel:

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

Lista schemalagda jobb

Använd följande begäran för att hämta en lista över schemalagda jobb:

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

Svaret på den här begäran ser ut som i följande exempel:

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

Uppdatera ett schemalagt jobb

Använd följande begäran för att uppdatera ett schemalagt jobb:

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

I följande exempel visas en begärandetext som uppdaterar ett schemalagt jobb.

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

Svaret på den här begäran ser ut som i följande exempel:

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

Ta bort ett schemalagt jobb

Använd följande begäran för att ta bort ett schemalagt jobb

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

Nästa steg

Nu när du har lärt dig hur du hanterar jobb med REST-API:et är ett föreslaget nästa steg att lära dig självstudie : Använda REST API för att hantera ett Azure IoT Central-program.