De Rest API van IoT Central gebruiken om apparaten te beheren

Artikel
03/05/2024

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.

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 Afzonderlijke apparaten beheren in uw Azure IoT Central-toepassing voor meer informatie over het beheren van apparaten met behulp van de gebruikersinterface van IoT Central.

REST API voor apparaten

Met behulp van de REST API van IoT Central kunt u:

Een apparaat toevoegen aan uw toepassing
Een apparaat in uw toepassing bijwerken
Een lijst met de apparaten in de toepassing ophalen
Een apparaat ophalen op basis van id
Een apparaatreferentie ophalen
Een apparaat in uw toepassing verwijderen
De lijst met apparaten in de toepassing filteren

Een apparaat toevoegen

Gebruik de volgende aanvraag om een nieuw apparaat te maken.

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

In het volgende voorbeeld ziet u een aanvraagbody waarmee een apparaat voor een apparaatsjabloon wordt toegevoegd. U kunt de template details ophalen op de pagina apparaatsjablonen in de gebruikersinterface van de IoT Central-toepassing.

{
  "displayName": "CheckoutThermostat",
  "template": "dtmi:contoso:Thermostat;1",
  "simulated": true,
  "enabled": true
}

De hoofdtekst van de aanvraag bevat enkele vereiste velden:

@displayName: Weergavenaam van het apparaat.
@enabled: declareert dat dit object een interface is.
@etag: ETag gebruikt om conflicten in apparaatupdates te voorkomen.
simulated: Wordt het apparaat gesimuleerd?
template : De apparaatsjabloondefinitie voor het apparaat.

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

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true
}

Een apparaat ophalen

Gebruik de volgende aanvraag om details van een apparaat op te halen uit uw toepassing:

GET https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Notitie

U kunt de gebruikersinterface van de deviceId IoT Central-toepassing ophalen door de muisaanwijzer op een apparaat te bewegen.

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

{
    "id": "5jcwskdwbm",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
    "displayName": "Thermostat - 5jcwskdwbm",
    "simulated": false,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true
}

In de volgende tabel ziet u hoe de statuswaarde voor een apparaat in de gebruikersinterface wordt toegewezen aan de waarden die door de REST API worden gebruikt om te communiceren met apparaten:

Apparaatstatus van gebruikersinterface	Opmerkingen	REST API ophalen
Wachten op goedkeuring	De optie voor automatisch goedkeuren is uitgeschakeld in de verbindingsgroep van het apparaat en het apparaat is niet toegevoegd via de gebruikersinterface. Een gebruiker moet het apparaat handmatig goedkeuren via de gebruikersinterface voordat het kan worden gebruikt.	`Provisioned: false` `Enabled: false`
Geregistreerd	Een apparaat is automatisch of handmatig goedgekeurd.	`Provisioned: false` `Enabled: true`
Ingericht	Het apparaat is ingericht en kan verbinding maken met uw IoT Central-toepassing.	`Provisioned: true` `Enabled: true`
Geblokkeerd	Het apparaat mag geen verbinding maken met uw IoT Central-toepassing. U kunt een apparaat blokkeren dat zich in een van de andere statussen bevindt.	`Provisioned:` Afhankelijk `Waiting for approval`/`Registered`/`Provisioned status` `Enabled: false`

Apparaatreferenties ophalen

Gebruik de volgende aanvraag om referenties van een apparaat op te halen uit uw toepassing:

GET https://{your app subdomain}/api/devices/{deviceId}/credentials?api-version=2022-07-31

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

{
    "idScope": "0ne003E64EF",
    "symmetricKey": {
        "primaryKey": "XUQvxGl6+Q1R0NKN5kOTmLOWsSKiuqs5N9unrjYCH4k=",
        "secondaryKey": "Qp/MTGHjn5MUTw4NVGhRfG+P+L1zh1gtAhO/KH8kn5c="
    }
}

Een apparaat bijwerken

PATCH https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

In de volgende voorbeeldtekst van de aanvraag wordt het enabled veld gewijzigd in false:

{
  "enabled": false
}

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

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": false
}

Een apparaat verwijderen

Gebruik de volgende aanvraag om een apparaat te verwijderen:

DELETE https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Apparaten vermelden

Gebruik de volgende aanvraag om een lijst met apparaten op te halen uit uw toepassing:

GET https://{your app subdomain}/api/devices?api-version=2022-07-31

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "CheckoutThermostat",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

Een implementatiemanifest toewijzen

Als u een IoT Edge-apparaat toevoegt, kunt u de API gebruiken om een IoT Edge-implementatiemanifest toe te wijzen aan het apparaat. Zie Een implementatiemanifest toewijzen aan een apparaat voor meer informatie.

ODATA-filters gebruiken

In de preview-versie van de API (api-version=2022-10-31-preview) kunt u ODATA-filters gebruiken om de resultaten te filteren en te sorteren die worden geretourneerd door de API voor lijstapparaten.

maxpagesize

Gebruik maxpagesize om de resultaatgrootte in te stellen. De maximaal geretourneerde resultaatgrootte is 100 en de standaardgrootte is 25.

Gebruik de volgende aanvraag om een top 10-apparaat op te halen uit uw toepassing:

GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&maxpagesize=10

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "5jcwskdgdwbm",
            "etag": "eyJoZWdhhZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "RS40 Occupancy Sensor - 5jcwskdgdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "urn:modelDefinition:aqlyr1ulfku:tz5rut2pvx",
            "enabled": true
        },
        ...
    ],
    "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-07-31&%24top=1&%24skiptoken=%257B%2522token%2522%253A%2522%252BRID%253A%7EJWYqAOis7THQbBQAAAAAAg%253D%253D%2523RT%253A1%2523TRC%253A1%2523ISV%253A2%2523IEO%253A65551%2523QCF%253A4%2522%252C%2522range%2522%253A%257B%2522min%2522%253A%2522%2522%252C%2522max%2522%253A%252205C1D7F7591D44%2522%257D%257D"
}

Het antwoord bevat een nextLink-waarde die u kunt gebruiken om de volgende pagina met resultaten op te halen.

filter

Gebruik filter om expressies te maken waarmee de lijst met apparaten wordt gefilterd. In de volgende tabel ziet u de vergelijkingsoperatoren die u kunt gebruiken:

Vergelijkingsoperator	Symbool	Opmerking
Is gelijk aan	eq	`id eq 'device1' and scopes eq 'redmond'`
Niet gelijk aan	ne	`Enabled ne true`
Kleiner dan of gelijk aan	le	`id le '26whl7mure6'`
Kleiner dan	lt	`id lt '26whl7mure6'`
Groter dan of gelijk aan	ge	`id ge '26whl7mure6'`
Groter dan	gt	`id gt '26whl7mure6'`

In de volgende tabel ziet u de logische operators die u kunt gebruiken in filterexpressies :

Logische operator	Symbool	Opmerking
EN	en	`id eq 'device1' and enabled eq true`
OF	or	`id eq 'device1' or simulated eq false`

Het filter werkt momenteel met de volgende apparaatvelden:

Veldnaam	Type	Omschrijving
`id`	tekenreeks	Apparaat-ID
`displayName`	tekenreeks	Weergavenaam van apparaat
`enabled`	boolean	Status apparaat ingeschakeld
`provisioned`	boolean	De ingerichte status van het apparaat
`simulated`	boolean	Gesimuleerd apparaatstatus
`template`	tekenreeks	Apparaatsjabloon-id
`scopes`	tekenreeks	organisatie-id

ondersteunde functies filteren:

Momenteel is de functie de contains enige ondersteunde filterfunctie voor apparaatlijsten:

filter=contains(displayName, 'device1')

In het volgende voorbeeld ziet u hoe u alle apparaten ophaalt waarin de weergavenaam de tekenreeks thermostatbevat:

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "thermostat1",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "thermostat2",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

Orderby

Gebruik orderby om de resultaten te sorteren. Op dit moment kunt u alleen sorteren op displayName. Orderby sorteert standaard in oplopende volgorde. Gebruik desc om in aflopende volgorde te sorteren, bijvoorbeeld:

orderby=displayName
orderby=displayName desc

In het volgende voorbeeld ziet u hoe u alle apparaatsjablonen ophaalt waarop het resultaat wordt gesorteerd displayName :

GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&orderby=displayName

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

{
    "value": [
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "CheckoutThermostat",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

U kunt ook twee of meer filters combineren.

In het volgende voorbeeld ziet u hoe u de drie belangrijkste apparaten ophaalt waarin de weergavenaam de tekenreeks Thermostatbevat.

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'Thermostat')&maxpagesize=3

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

{
  "value": [
    {
      "id": "1fpwlahp0zp",
      "displayName": "Thermostat - 1fpwlahp0zp",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiYTRjZGQyMjQtZjIxMi00MTI4LTkyMTMtZjcwMTBlZDhkOWQ0In0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    },
    {
      "id": "1yg0zvpz9un",
      "displayName": "Thermostat - 1yg0zvpz9un",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiZGQ1YTY4MDUtYzQxNS00ZTMxLTgxM2ItNTRiYjdiYWQ1MWQ2In0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    },
    {
      "id": "20cp9l96znn",
      "displayName": "Thermostat - 20cp9l96znn",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiNGUzNWM4OTItNDBmZi00OTcyLWExYjUtM2I4ZjU5NGZkODBmIn0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    }
  ],
  "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-10-31-preview&filter=contains%28displayName%2C+%27Thermostat%27%29&maxpagesize=3&$skiptoken=aHR0cHM6Ly9pb3RjLXByb2QtbG4taW5ma3YteWRtLnZhdWx0LmF6dXJlLm5ldC9zZWNyZXRzL2FwaS1lbmMta2V5LzY0MzZkOTY2ZWRjMjRmMDQ5YWM1NmYzMzFhYzIyZjZi%3AgWMDkfdpzBF0eYiYCGRdGQ%3D%3D%3ATVTgi5YVv%2FBfCd7Oos6ayrCIy9CaSUVu2ULktGQoHZDlaN7uPUa1OIuW0MCqT3spVXlSRQ9wgNFXsvb6mXMT3WWapcDB4QPynkI%2FE1Z8k7s3OWiBW3EQpdtit3JTCbj8qRNFkA%3D%3D%3Aq63Js0HL7OCq%2BkTQ19veqA%3D%3D"
}

Apparaatgroepen

U kunt apparaatgroepen maken in een IoT Central-toepassing voor het bewaken van geaggregeerde gegevens, voor gebruik met taken en voor het beheren van de toegang. Apparaatgroepen worden gedefinieerd door een filter waarmee de apparaten worden geselecteerd die aan de groep moeten worden toegevoegd. U kunt apparaatgroepen maken in de IoT Central-portal of met behulp van de API.

Een apparaatgroep toevoegen

Gebruik de volgende aanvraag om een nieuwe apparaatgroep te maken.

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

Wanneer u een apparaatgroep maakt, definieert u een filter apparaatgroep waarmee de apparaten worden geselecteerd die u aan de groep wilt toevoegen. A 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 sjabloon '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",
  "organizations": [
    "seattle"
  ]
}

De hoofdtekst van de aanvraag bevat enkele vereiste velden:

@displayName: Weergavenaam van de apparaatgroep.
@filter: Query definiëren welke apparaten zich in deze groep moeten bevinden.
@etag: ETag gebruikt om conflicten in apparaatupdates te voorkomen.
description: Korte samenvatting van apparaatgroep.

Het veld Organisaties wordt alleen gebruikt wanneer een toepassing een organisatiehiërarchie heeft gedefinieerd. Zie IoT Central-organisaties beheren voor meer informatie over organisaties.

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",
  "organizations": [
    "seattle"
  ]
}

Een apparaatgroep ophalen

Gebruik de volgende aanvraag om details van een apparaatgroep op te halen uit uw toepassing:

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

deviceGroupId : unieke id voor de apparaatgroep.

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

{
  "id": "475cad48-b7ff-4a09-b51e-1a9021385453",
  "displayName": "DeviceGroupEntry1",
  "description": "This is a default device group containing all the devices for this particular Device Template.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Een apparaatgroep bijwerken

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

De hoofdtekst van de voorbeeldaanvraag ziet eruit als in het volgende voorbeeld waarmee de displayName apparaatgroep wordt bijgewerkt:

{
  "displayName": "New group name"
}

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

{
  "id": "group1",
  "displayName": "New group name",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Een apparaatgroep verwijderen

Gebruik de volgende aanvraag om een apparaatgroep te verwijderen:

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

Apparaatgroepen weergeven

Gebruik de volgende aanvraag om een lijst met apparaatgroepen op te halen uit uw toepassing:

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

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

{
  "value": [
    {
      "id": "475cad48-b7ff-4a09-b51e-1a9021385453",
      "displayName": "DeviceGroupEntry1",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
      "organizations": [
        "seattle"
      ]
    },
    {
      "id": "c2d5ae1d-2cb7-4f58-bf44-5e816aba0a0e",
      "displayName": "DeviceGroupEntry2",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model1\"",
      "organizations": [
        "redmond"
      ]
    },
    {
      "id": "241ad72b-32aa-4216-aabe-91b240582c8d",
      "displayName": "DeviceGroupEntry3",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model2\" AND $simulated = true"
    },
    {
      "id": "group4",
      "displayName": "DeviceGroupEntry4",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model3\""
    }
  ]
}

Inschrijvingsgroepen

Inschrijvingsgroepen worden gebruikt voor het beheren van de opties voor apparaatverificatie in uw IoT Central-toepassing. Zie Apparaatverificatieconcepten in IoT Central voor meer informatie.

Zie Apparaten verbinden met X.509-certificaten met IoT Central-toepassing voor meer informatie over het maken en beheren van inschrijvingsgroepen in de gebruikersinterface.

Wanneer u een inschrijvingsgroep maakt voor apparaten die X.509-certificaten gebruiken, moet u eerst het basis- of tussencertificaat uploaden naar uw IoT Central-toepassing.

Basis- en apparaatcertificaten genereren

In deze sectie genereert u de X.509-certificaten die u nodig hebt om een apparaat te verbinden met IoT Central.

Waarschuwing

Deze manier om X.509-certificaten te genereren, is alleen bedoeld voor testen. Voor een productieomgeving moet u uw officiële, veilige mechanisme gebruiken voor het genereren van certificaten.

Navigeer naar het script voor de certificaatgenerator in de Microsoft Azure IoT SDK voor Node.js u hebt gedownload. Installeer de vereiste pakketten:
```
cd azure-iot-sdk-node/provisioning/tools
npm install
```
Maak een basiscertificaat en leid vervolgens een apparaatcertificaat af door het script uit te voeren:
```
node create_test_cert.js root mytestrootcert
node create_test_cert.js device sample-device-01 mytestrootcert
```
Tip

Een apparaat-id mag alleen letters, cijfers en het teken - bevatten.

Met deze opdrachten worden de volgende basis- en apparaatcertificaten geproduceerd:

filename	Inhoud
mytestrootcert_cert.pem	Het openbare gedeelte van het X.509-basiscertificaat
mytestrootcert_key.pem	De persoonlijke sleutel voor het X.509-basiscertificaat
mytestrootcert_fullchain.pem	De hele sleutelhanger voor het X.509-basiscertificaat.
mytestrootcert.pfx	Het PFX-bestand voor het X.509-basiscertificaat.
sampleDevice01_cert.pem	Het openbare gedeelte van het X.509-certificaat van het apparaat
sampleDevice01_key.pem	De persoonlijke sleutel voor het X.509-certificaat van het apparaat
sampleDevice01_fullchain.pem	De hele sleutelhanger voor het X.509-certificaat van het apparaat.
sampleDevice01.pfx	Het PFX-bestand voor het X.509-certificaat van het apparaat.

Noteer de locatie van deze bestanden. U hebt het later nodig.

Genereer de base-64 gecodeerde versie van het basiscertificaat

Maak in de map op uw lokale computer met de certificaten die u hebt gegenereerd een bestand met de naam convert.js en voeg de volgende JavaScript-inhoud toe:

const fs = require('fs')
const fileContents = fs.readFileSync(process.argv[2]).toString('base64');
console.log(fileContents);

Voer de volgende opdracht uit om een base-64-coderingsversie van het certificaat te genereren:

node convert.js mytestrootcert_cert.pem

Noteer de base-64 gecodeerde versie van het certificaat. U hebt het later nodig.

Een X.509-inschrijvingsgroep toevoegen

Gebruik de volgende aanvraag om een nieuwe inschrijvingsgroep te maken met myx509eg als id:

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

In het volgende voorbeeld ziet u een aanvraagbody waarmee een nieuwe X.509-inschrijvingsgroep wordt toegevoegd:

{
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "x509"
  }
}

De hoofdtekst van de aanvraag bevat enkele vereiste velden:

@displayName: Weergavenaam van de inschrijvingsgroep.
@enabled: Of de apparaten die de groep gebruiken, verbinding mogen maken met IoT Central.
@type: Type apparaten die verbinding maken via de groep, iot of iotEdge.
attestation: het attestation-mechanisme voor de inschrijvingsgroep, symmetricKey of x509.

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

{
    "id": "myEnrollmentGroupId",
    "displayName": "My group",
    "enabled": true,
    "type": "iot",
    "attestation": {
        "type": "x509",
        "x509": {
            "signingCertificates": {}
        }
    },
    "etag": "IjdiMDcxZWQ5LTAwMDAtMDcwMC0wMDAwLTYzMWI3MWQ4MDAwMCI="
}

Een X.509-certificaat toevoegen aan een inschrijvingsgroep

Gebruik de volgende aanvraag om het primaire X.509-certificaat van de myx509eg-inschrijvingsgroep in te stellen:

PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

Gebruik deze aanvraag om een primair of secundair X.509-certificaat toe te voegen aan de inschrijvingsgroep.

In het volgende voorbeeld ziet u een aanvraagbody waarmee een X.509-certificaat wordt toegevoegd aan een inschrijvingsgroep:

{
  "verified": false,
  "certificate": "<base64-certificate>"
}

certificaat: de base-64-versie van het certificaat dat u eerder hebt genoteerd.
geverifieerd: true als u bevestigt dat het certificaat geldig is, false als u de geldigheid van het certificaat wilt bewijzen.

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

{
  "verified": false,
  "info": {
    "sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
  },
  "etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
}

Verificatiecode genereren voor een X.509-certificaat

Gebruik de volgende aanvraag om een verificatiecode te genereren voor het primaire of secundaire X.509-certificaat van een inschrijvingsgroep.

Als u in de vorige aanvraag instelt verifiedfalse , gebruikt u de volgende aanvraag om een verificatiecode te genereren voor het primaire X.509-certificaat in de myx509eg inschrijvingsgroep:

POST https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/generateVerificationCode?api-version=2022-07-31

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

{
  "verificationCode": "<certificate-verification-code>"
}

Noteer de verificatiecode. U hebt deze in de volgende stap nodig.

Het verificatiecertificaat genereren

Gebruik de volgende opdracht om een verificatiecertificaat te genereren op basis van de verificatiecode in de vorige stap:

node create_test_cert.js verification --ca mytestrootcert_cert.pem --key mytestrootcert_key.pem --nonce  {verification-code}

Voer de volgende opdracht uit om een met base 64 gecodeerde versie van het certificaat te genereren:

node convert.js verification_cert.pem

Noteer de base-64 gecodeerde versie van het certificaat. U hebt het later nodig.

X.509-certificaat van een inschrijvingsgroep controleren

Gebruik de volgende aanvraag om het primaire X.509-certificaat van de myx509eg inschrijvingsgroep te verifiëren door het certificaat met de ondertekende verificatiecode op te geven:

POST PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/verify?api-version=2022-07-31

In het volgende voorbeeld ziet u een aanvraagbody waarmee een X.509-certificaat wordt geverifieerd:

{
  "certificate": "base64-verification-certificate"
}

X.509-certificaat van een inschrijvingsgroep ophalen

Gebruik de volgende aanvraag om details van het X.509-certificaat van een inschrijvingsgroep op te halen uit uw toepassing:

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

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

{
  "verified": true,
  "info": {
    "sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
  },
  "etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
}

Een X.509-certificaat verwijderen uit een inschrijvingsgroep

Gebruik de volgende aanvraag om het primaire X.509-certificaat te verwijderen uit een inschrijvingsgroep met id myx509eg:

DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

Een inschrijvingsgroep met symmetrische sleutels toevoegen

Gebruik de volgende aanvraag om een nieuwe inschrijvingsgroep te maken met mysymmetric als id:

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

In het volgende voorbeeld ziet u een aanvraagbody waarmee een nieuwe inschrijvingsgroep wordt toegevoegd:

{
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey"
  }
}

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

{
  "id": "mysymmetric",
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

IoT Central genereert de primaire en secundaire symmetrische sleutels wanneer u deze API-aanroep uitvoert.

Een inschrijvingsgroep ophalen

Gebruik de volgende aanvraag om details van een inschrijvingsgroep op te halen met mysymmetric als id:

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

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

{
  "id": "mysymmetric",
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

Een inschrijvingsgroep bijwerken

Gebruik de volgende aanvraag om een inschrijvingsgroep bij te werken.

PATCH https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31

In het volgende voorbeeld ziet u een aanvraagbody waarmee de weergavenaam van een inschrijvingsgroep wordt bijgewerkt:

{
  "displayName": "My new group name",
}

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

{
  "id": "myEnrollmentGroupId",
  "displayName": "My new group name",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

Een inschrijvingsgroep verwijderen

Gebruik de volgende aanvraag om een inschrijvingsgroep met id myx509egte verwijderen:

DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31

Inschrijvingsgroepen vermelden

Gebruik de volgende aanvraag om een lijst met inschrijvingsgroepen op te halen uit uw toepassing:

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

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

{
    "value": [
        {
            "id": "myEnrollmentGroupId",
            "displayName": "My group",
            "enabled": true,
            "type": "iot",
            "attestation": {
                "type": "symmetricKey",
                "symmetricKey": {
                    "primaryKey": "primaryKey",
                    "secondaryKey": "secondarykey"
                }
            },
            "etag": "IjZkMDc1YTgzLTAwMDAtMDcwMC0wMDAwLTYzMTc5ZjA4MDAwMCI="
        },
        {
            "id": "enrollmentGroupId2",
            "displayName": "My group",
            "enabled": true,
            "type": "iot",
            "attestation": {
                "type": "x509",
                "x509": {
                    "signingCertificates": {}
                }
            },
            "etag": "IjZkMDdjNjkyLTAwMDAtMDcwMC0wMDAwLTYzMTdhMDY1MDAwMCI="
        }
    ]
}

Delen via

De Rest API van IoT Central gebruiken om apparaten te beheren

REST API voor apparaten

Een apparaat toevoegen

Een apparaat ophalen

Apparaatreferenties ophalen

Een apparaat bijwerken

Een apparaat verwijderen

Apparaten vermelden

Een implementatiemanifest toewijzen

ODATA-filters gebruiken

maxpagesize

filter

Orderby

Apparaatgroepen

Een apparaatgroep toevoegen

Een apparaatgroep ophalen

Een apparaatgroep bijwerken

Een apparaatgroep verwijderen

Apparaatgroepen weergeven

Inschrijvingsgroepen

Een inschrijvingsgroep maken

Basis- en apparaatcertificaten genereren

Genereer de base-64 gecodeerde versie van het basiscertificaat

Een X.509-inschrijvingsgroep toevoegen

Een X.509-certificaat toevoegen aan een inschrijvingsgroep

Verificatiecode genereren voor een X.509-certificaat

Het verificatiecertificaat genereren

X.509-certificaat van een inschrijvingsgroep controleren

X.509-certificaat van een inschrijvingsgroep ophalen

Een X.509-certificaat verwijderen uit een inschrijvingsgroep

Een inschrijvingsgroep met symmetrische sleutels toevoegen

Een inschrijvingsgroep ophalen

Een inschrijvingsgroep bijwerken

Een inschrijvingsgroep verwijderen

Inschrijvingsgroepen vermelden

Aanvullende resources