Share via


De Rest API van IoT Central gebruiken om apparaten te beheren

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.

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:

FieldName 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.

Een inschrijvingsgroep maken

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.

  1. 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
    
  2. 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 verified false , 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 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="
        }
    ]
}