Delen via

IoT Central REST API gebruiken om apparaten te beheren

  • Artikel

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 apparaten in uw IoT Central-toepassing te beheren. Met de REST API kunt u het volgende doen:

  • Lees de laatst bekende telemetriewaarde van een apparaat.
  • Eigenschapswaarden van een apparaat lezen.
  • Schrijfbare eigenschappen instellen op een apparaat.
  • Roep opdrachten op een apparaat aan.

In dit artikel wordt beschreven hoe u de /devices/{device_id} API gebruikt om afzonderlijke apparaten te beheren. U kunt taken ook gebruiken om apparaten bulksgewijs te beheren.

Een apparaat kan de eigenschappen, telemetrie en opdrachten groeperen die worden ondersteund in onderdelen en modules.

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.

Tip

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.

Zie voor meer informatie over het beheren van apparaten met behulp van de IoT Central-gebruikersinterface

Onderdelen en modules

Met onderdelen kunt u apparaatmogelijkheden groeperen en opnieuw gebruiken. Zie de IoT Plug en Play modelleringshandleiding voor meer informatie over onderdelen en apparaatmodellen.

Niet alle apparaatsjablonen maken gebruik van onderdelen. In de volgende schermopname ziet u de apparaatsjabloon voor een eenvoudige thermostaat waarin alle mogelijkheden zijn gedefinieerd in één interface, het hoofdonderdeel genoemd:

Screenshot that shows a simple no component thermostat device.

In de volgende schermopname ziet u een apparaatsjabloon voor een temperatuurcontroller die gebruikmaakt van onderdelen. De temperatuurregelaar heeft twee thermostaatonderdelen en een apparaatinformatieonderdeel:

Screenshot that shows a temperature controller device with two thermostat components and a device information component.

In IoT Central verwijst een module naar een IoT Edge-module die wordt uitgevoerd op een verbonden IoT Edge-apparaat. Een module kan een eenvoudig model hebben, zoals de thermostaat die geen onderdelen gebruikt. Een module kan ook onderdelen gebruiken om een complexere set mogelijkheden te organiseren. In de volgende schermopname ziet u een voorbeeld van een apparaatsjabloon die gebruikmaakt van modules. Het omgevingssensorapparaat heeft een module aangeroepen SimulatedTemperatureSensor en een overgenomen interface met de naam management:

Screenshot that shows an environmental sensor device with a module.

Een apparaatonderdeel ophalen

Gebruik de volgende aanvraag om de onderdelen op te halen van een apparaat met de naam temperature-controller-01:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components?api-version=2022-07-31

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld. De value matrix bevat details van elk apparaatonderdeel:

{
  "value": [
    {
      "@type": "Component",
      "name": "thermostat1",
      "displayName": "Thermostat One",
      "description": "Thermostat One of Two."
    },
    {
      "@type": "Component",
      "name": "thermostat2",
      "displayName": "Thermostat Two",
      "description": "Thermostat Two of Two."
    },
    {
      "@type": "Component",
      "name": "deviceInformation",
      "displayName": "Device Information interface",
      "description": "Optional interface with basic device hardware information."
    }
  ]
}

Een apparaatmodule ophalen

Gebruik de volgende aanvraag om een lijst met modules op te halen die worden uitgevoerd op een verbonden IoT Edge-apparaat met de naam environmental-sensor-01:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules?api-version=2022-07-31

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld. De matrix van modules bevat alleen aangepaste modules die worden uitgevoerd op het IoT Edge-apparaat, niet de ingebouwde $edgeAgent modules en $edgeHub modules:

{
  "value": [
    {
      "@type": [
        "Relationship",
        "EdgeModule"
      ],
      "name": "SimulatedTemperatureSensor",
      "displayName": "SimulatedTemperatureSensor"
    }
  ]
}

Gebruik de volgende aanvraag om een lijst met de onderdelen op te halen in een module met de naam SimulatedTemperatureSensor:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules?api-version=2022-07-31

Telemetrie lezen

Gebruik de volgende aanvraag om de laatst bekende telemetriewaarde op te halen van een apparaat dat geen onderdelen gebruikt. In dit voorbeeld wordt het apparaat aangeroepen thermostat-01 en wordt de telemetrie aangeroepen temperature:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/telemetry/temperature?api-version=2022-07-31

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

{
  "timestamp": "2021-03-24T12:33:15.223Z",
  "value": 40.10993804456927
}

Gebruik de volgende aanvraag om de laatst bekende telemetriewaarde op te halen van een apparaat dat onderdelen gebruikt. In dit voorbeeld wordt het apparaat aangeroepentemperature-controller-01, wordt het onderdeel aangeroepen en wordt de telemetrie aangeroepenthermostat2temperature:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/telemetry/temperature?api-version=2022-07-31

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

{
  "timestamp": "2021-03-24T12:43:44.968Z",
  "value": 70.29168040339141
}

Als het apparaat een IoT Edge-apparaat is, gebruikt u de volgende aanvraag om de laatst bekende telemetriewaarde op te halen uit een module. In dit voorbeeld wordt een apparaat gebruikt dat wordt aangeroepen environmental-sensor-01 met een module met de naam SimulatedTemperatureSensorambienten telemetrie. Het ambient telemetrietype heeft temperatuur- en vochtigheidswaarden:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/telemetry/ambient?api-version=2022-07-31

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

{
  "timestamp": "2021-03-25T15:44:34.955Z",
  "value": {
    "temperature": 21.18032378129676,
    "humidity": 25
  }
}

Tip

Als u toegang wilt krijgen tot de telemetrie van een onderdeel in een module, gebruikt u /api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/telemetry/{telemetryName}.

Leeseigenschappen

Gebruik de volgende aanvraag om de eigenschapswaarden op te halen van een apparaat dat geen onderdelen gebruikt. In dit voorbeeld wordt het apparaat het volgende aangeroepen thermostat-01:

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld. Hier ziet u dat het apparaat één eigenschapswaarde rapporteert:

{
  "maxTempSinceLastReboot": 93.95907131817654,
  "$metadata": {
    "maxTempSinceLastReboot": {
      "lastUpdateTime": "2021-03-24T12:47:46.7571438Z"
    }
  }
}

Gebruik de volgende aanvraag om eigenschapswaarden op te halen uit alle onderdelen. In dit voorbeeld wordt het apparaat het volgende aangeroepen temperature-controller-01:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/properties?api-version=2022-07-31

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

{
  "serialNumber": "Explicabo animi nihil qui facere sit explicabo nisi.",
  "$metadata": {
    "serialNumber": {
      "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
    }
  },
  "thermostat1": {
    "maxTempSinceLastReboot": 79.7290121339184,
    "$metadata": {
      "maxTempSinceLastReboot": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      }
    }
  },
  "thermostat2": {
    "maxTempSinceLastReboot": 54.214860556320424,
    "$metadata": {
      "maxTempSinceLastReboot": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      }
    }
  },
  "deviceInformation": {
    "manufacturer": "Eveniet culpa sed sit omnis.",
    "$metadata": {
      "manufacturer": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "model": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "swVersion": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "osName": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "processorArchitecture": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "processorManufacturer": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "totalStorage": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "totalMemory": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      }
    },
    "model": "Necessitatibus id ab dolores vel eligendi fuga.",
    "swVersion": "Ut minus ipsum ut omnis est asperiores harum.",
    "osName": "Atque sit omnis eum sapiente eum tenetur est dolor.",
    "processorArchitecture": "Ratione enim dolor iste iure.",
    "processorManufacturer": "Aliquam eligendi sit ipsa.",
    "totalStorage": 36.02825898541592,
    "totalMemory": 55.442695395750505
  }
}

Gebruik de volgende aanvraag om een eigenschapswaarde op te halen uit een afzonderlijk onderdeel. In dit voorbeeld wordt het apparaat aangeroepen temperature-controller-01 en wordt het onderdeel aangeroepen thermostat2:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/properties?api-version=2022-07-31

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

{
  "maxTempSinceLastReboot": 24.445128131004935,
  "$metadata": {
    "maxTempSinceLastReboot": {
      "lastUpdateTime": "2021-03-24T14:03:53.787491Z"
    }
  }
}

Als het apparaat een IoT Edge-apparaat is, gebruikt u de volgende aanvraag om eigenschapswaarden op te halen uit een module. In dit voorbeeld wordt een apparaat gebruikt dat wordt aangeroepen environmental-sensor-01 met een module met de naam SimulatedTemperatureSensor:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/properties?api-version=2022-07-31

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

{
  "$metadata": {
    "SendData": {
      "desiredValue": true,
      "desiredVersion": 1
    },
    "SendInterval": {
      "desiredValue": 10,
      "desiredVersion": 1
    }
  }
}

Tip

Als u toegang wilt tot de eigenschappen van een onderdeel in een module, gebruikt u /devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties.

Eigenschappen schrijven

Sommige eigenschappen zijn beschrijfbaar. In het voorbeeldthermostaatmodel is de targetTemperature eigenschap een beschrijfbare eigenschap.

Gebruik de volgende aanvraag om een afzonderlijke eigenschapswaarde naar een apparaat te schrijven dat geen onderdelen gebruikt. In dit voorbeeld wordt het apparaat het volgende aangeroepen thermostat-01:

PATCH https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/properties?api-version=2022-07-31

De hoofdtekst van de aanvraag ziet er als volgt uit:

{
  "targetTemperature": 65.5
}

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

{
  "$metadata": {
    "targetTemperature": {
      "desiredValue": 65.5
    }
  }
}

Tip

Als u alle eigenschappen op een apparaat wilt bijwerken, gebruikt PUT u in plaats van PATCH.

Gebruik de volgende aanvraag om een afzonderlijke eigenschapswaarde naar een apparaat te schrijven dat onderdelen gebruikt. In dit voorbeeld wordt het apparaat aangeroepen temperature-controller-01 en wordt het onderdeel aangeroepen thermostat2:

PATCH https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/properties?api-version=2022-07-31

De hoofdtekst van de aanvraag ziet er als volgt uit:

{
  "targetTemperature": 65.5
}

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

{
  "$metadata": {
    "targetTemperature": {
      "desiredValue": 65.5
    }
  }
}

Tip

Als u alle eigenschappen van een onderdeel wilt bijwerken, gebruikt PUT u in plaats van PATCH.

Als het apparaat een IoT Edge-apparaat is, gebruikt u de volgende aanvraag om een afzonderlijke eigenschapswaarde naar een module te schrijven. In dit voorbeeld wordt gebruikgemaakt van een apparaat met de naam environmental-sensor-01, een module genaamd SimulatedTemperatureSensoren een eigenschap met de naam SendInterval:

PUT https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/properties?api-version=2022-07-31

De hoofdtekst van de aanvraag ziet er als volgt uit:

{
  "SendInterval": 20
}

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

{
  "$metadata": {
    "SendInterval": {
      "desiredValue": 20
    }
  }
}

Tip

Als u alle eigenschappen van een module wilt bijwerken, gebruikt PUT u in plaats van PATCH.

Module-eigenschappen bijwerken

Als u een IoT Edge-apparaat gebruikt, gebruikt u de volgende aanvraag om eigenschapswaarden op te halen uit een module:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}/modules/{moduleName}/properties?api-version=2022-07-31

Als u een IoT Edge-apparaat gebruikt, gebruikt u de volgende aanvraag om eigenschapswaarden op te halen uit een onderdeel in een module:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties?api-version=2022-07-31

Opdrachten aanroepen

U kunt de REST API gebruiken om apparaatopdrachten aan te roepen en de opdrachtgeschiedenis op te halen.

Gebruik de volgende aanvraag om een opdracht aan te roepen op een apparaat dat geen onderdelen gebruikt. In dit voorbeeld wordt het apparaat aangeroepen thermostat-01 en wordt de opdracht aangeroepen getMaxMinReport:

POST https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/commands/getMaxMinReport?api-version=2022-07-31

De hoofdtekst van de aanvraag ziet er als volgt uit:

{
  "request": "2021-03-24T12:55:20.789Z"
}

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

{
  "response": {
    "maxTemp": 21.002000799562367,
    "minTemp": 73.09674605264892,
    "avgTemp": 59.54553991653756,
    "startTime": "2022-02-28T15:02:56.789Z",
    "endTime": "2021-05-05T03:50:56.412Z"
  },
  "responseCode": 200
}

Gebruik de volgende aanvraag om de geschiedenis voor deze opdracht weer te geven:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/commands/getMaxMinReport?api-version=2022-07-31

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

{
  "value": [
    {
      "response": {
        "maxTemp": 71.43744908819954,
        "minTemp": 51.29986610160005,
        "avgTemp": 39.577384387771744,
        "startTime": "2021-06-20T00:38:17.620Z",
        "endTime": "2022-01-07T22:30:41.104Z"
      },
      "responseCode": 200
    }
  ]
}

Gebruik de volgende aanvraag om een opdracht aan te roepen op een apparaat dat onderdelen gebruikt. In dit voorbeeld wordt het apparaat aangeroepentemperature-controller-01, wordt het onderdeel aangeroepen en wordt de opdracht aangeroepenthermostat2getMaxMinReport:

POST https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/commands/getMaxMinReport?api-version=2022-07-31

De indelingen van de nettolading en het antwoord van de aanvraag zijn hetzelfde als voor een apparaat dat geen onderdelen gebruikt.

Gebruik de volgende aanvraag om de geschiedenis voor deze opdracht weer te geven:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/commands/getMaxMinReport?api-version=2022-07-31

Tip

Als u opdrachten wilt aanroepen in een onderdeel in een module, gebruikt u /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}.

Volgende stappen

Nu u hebt geleerd hoe u apparaten beheert met de REST API, is een voorgestelde volgende stap om te leren hoe u de IoT Central REST API gebruikt om taken te maken en te beheren.