Så här använder du IoT Central REST API för att hantera enheter

Artikel
03/01/2024

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 hantera enheter i ditt IoT Central-program.

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 hanterar enheter med hjälp av IoT Central-användargränssnittet finns i Hantera enskilda enheter i ditt Azure IoT Central-program.

REST API för enheter

I REST-API:et för IoT Central kan du göra följande:

Lägga till en enhet i ditt program
Uppdatera en enhet i ditt program
Hämta en lista med enheter i programmet
Hämta en enhet kopplad till ett ID
Hämta en enhetsautentiseringsuppgift
Ta bort en enhet i ditt program
Filtrera listan över enheter i programmet

Lägg till en enhet

Använd följande begäran för att skapa en ny enhet.

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

I följande exempel visas en begärandetext som lägger till en enhet för en enhetsmall. Du kan hämta template informationen från sidan med enhetsmallar i IoT Central-programgränssnittet.

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

Begärandetexten innehåller några obligatoriska fält:

@displayName: Enhetens visningsnamn.
@enabled: Deklarerar att det här objektet är ett gränssnitt.
@etag: ETag används för att förhindra konflikter i enhetsuppdateringar.
simulated: Simuleras enheten?
template : Enhetsmalldefinitionen för enheten.

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

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

Hämta en enhet

Använd följande begäran för att hämta information om en enhet från ditt program:

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

Kommentar

Du kan hämta användargränssnittet deviceId från IoT Central-programmet genom att hovra musen över en enhet.

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

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

I följande tabell visas hur statusvärdet för en enhet i användargränssnittet mappar till de värden som används av REST-API:et för att interagera med enheter:

Enhetsstatus för användargränssnittet	Kommentar	REST API Get
Väntar på godkännande	Alternativet för automatisk godkännande är inaktiverat i enhetsanslutningsgruppen och enheten lades inte till via användargränssnittet. En användare måste godkänna enheten manuellt via användargränssnittet innan den kan användas.	`Provisioned: false` `Enabled: false`
Registrerat	En enhet godkändes antingen automatiskt eller manuellt.	`Provisioned: false` `Enabled: true`
Etablerad	Enheten har etablerats och kan ansluta till ditt IoT Central-program.	`Provisioned: true` `Enabled: true`
Spärrad	Enheten får inte ansluta till ditt IoT Central-program. Du kan blockera en enhet som finns i något av de andra tillstånden.	`Provisioned:` beror på `Waiting for approval`/`Registered`/`Provisioned status` `Enabled: false`

Hämta enhetsautentiseringsuppgifter

Använd följande begäran för att hämta autentiseringsuppgifter för en enhet från ditt program:

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

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

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

Uppdatera en enhet

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

Följande brödtext för exempelbegäran ändrar fältet enabled till false:

{
  "enabled": false
}

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

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

Ta bort en enhet

Använd följande begäran för att ta bort en enhet:

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

Visa enheter

Använd följande begäran för att hämta en lista över enheter från ditt program:

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

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

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

Tilldela ett distributionsmanifest

Om du lägger till en IoT Edge-enhet kan du använda API:et för att tilldela ett IoT Edge-distributionsmanifest till enheten. Mer information finns i Tilldela ett distributionsmanifest till en enhet.

Använda ODATA-filter

I förhandsversionen av API:et (api-version=2022-10-31-preview) kan du använda ODATA-filter för att filtrera och sortera resultaten som returneras av API:et för listenheter.

maxpagesize

Använd maxpagesize för att ange resultatstorleken. Den maximala returnerade resultatstorleken är 100 och standardstorleken är 25.

Använd följande begäran för att hämta en topp 10-enhet från ditt program:

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

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

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

Svaret innehåller ett nextLink-värde som du kan använda för att hämta nästa sida med resultat.

filter

Använd filter för att skapa uttryck som filtrerar listan över enheter. I följande tabell visas de jämförelseoperatorer som du kan använda:

Jämförelseoperator	Symbol	Exempel
Lika med	eq	`id eq 'device1' and scopes eq 'redmond'`
Inte lika med	ne	`Enabled ne true`
Mindre än eller lika med	le	`id le '26whl7mure6'`
Mindre än	lt	`id lt '26whl7mure6'`
Större än eller lika med	ge	`id ge '26whl7mure6'`
Större än	gt	`id gt '26whl7mure6'`

I följande tabell visas de logikoperatorer som du kan använda i filteruttryck :

Logikoperator	Symbol	Exempel
OCH	och	`id eq 'device1' and enabled eq true`
ELLER	eller	`id eq 'device1' or simulated eq false`

För närvarande fungerar filtret med följande enhetsfält:

FieldName	Typ	Description
`id`	sträng	Enhets-ID
`displayName`	sträng	Enhetens visningsnamn
`enabled`	boolean	Status för enhetsaktiverad
`provisioned`	boolean	Enhetsetableringsstatus
`simulated`	boolean	Enhetens simulerade status
`template`	sträng	Enhetsmalls-ID
`scopes`	sträng	organisations-ID

filterfunktioner som stöds:

För närvarande är den enda filterfunktionen som stöds för enhetslistor funktionen contains :

filter=contains(displayName, 'device1')

I följande exempel visas hur du hämtar alla enheter där visningsnamnet innehåller strängen thermostat:

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

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

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

Använd orderby för att sortera resultatet. För närvarande kan du bara sortera i orderby på displayName. Som standard sorterar orderby i stigande ordning. Använd desc för att sortera i fallande ordning, till exempel:

orderby=displayName
orderby=displayName desc

I följande exempel visas hur du hämtar alla enhetsmallar där resultatet sorteras efter displayName :

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

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

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

Du kan också kombinera två eller flera filter.

I följande exempel visas hur du hämtar de tre översta enheterna där visningsnamnet innehåller strängen Thermostat.

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

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

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

Enhetsgrupper

Du kan skapa enhetsgrupper i ett IoT Central-program för att övervaka aggregerade data, använda med jobb och hantera åtkomst. Enhetsgrupper definieras av ett filter som väljer de enheter som ska läggas till i gruppen. Du kan skapa enhetsgrupper i IoT Central-portalen eller med hjälp av API:et.

Lägga till en enhetsgrupp

Använd följande begäran för att skapa en ny enhetsgrupp.

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

När du skapar en enhetsgrupp definierar du en filter som väljer de enheter som ska läggas till i gruppen. En 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 mallen "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",
  "organizations": [
    "seattle"
  ]
}

Begärandetexten innehåller några obligatoriska fält:

@displayName: Enhetsgruppens visningsnamn.
@filter: Fråga som definierar vilka enheter som ska finnas i den här gruppen.
@etag: ETag används för att förhindra konflikter i enhetsuppdateringar.
description: Kort sammanfattning av enhetsgrupp.

Organisationsfältet används endast när ett program har en definierad organisationshierarki. Mer information om organisationer finns i Hantera IoT Central-organisationer.

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

Hämta en enhetsgrupp

Använd följande begäran för att hämta information om en enhetsgrupp från ditt program:

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

deviceGroupId – unikt ID för enhetsgruppen.

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

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

Uppdatera en enhetsgrupp

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

Brödtexten för exempelbegäran ser ut som i följande exempel som uppdaterar displayName enhetsgruppens uppdatering:

{
  "displayName": "New group name"
}

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

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

Ta bort en enhetsgrupp

Använd följande begäran för att ta bort en enhetsgrupp:

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

Lista enhetsgrupper

Använd följande begäran för att hämta en lista över enhetsgrupper från ditt program:

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

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

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

Registreringsgrupper

Registreringsgrupper används för att hantera alternativen för enhetsautentisering i ditt IoT Central-program. Mer information finns i Begrepp för enhetsautentisering i IoT Central.

Information om hur du skapar och hanterar registreringsgrupper i användargränssnittet finns i Ansluta enheter med X.509-certifikat till IoT Central Application.

När du skapar en registreringsgrupp för enheter som använder X.509-certifikat måste du först ladda upp rotcertifikatet eller mellanliggande certifikatet till ditt IoT Central-program.

Generera rot- och enhetscertifikat

I det här avsnittet genererar du de X.509-certifikat som du behöver för att ansluta en enhet till IoT Central.

Varning

Det här sättet att generera X.509-certifikat är endast till för testning. För en produktionsmiljö bör du använda din officiella, säkra mekanism för certifikatgenerering.

Gå till certifikatgeneratorskriptet i Microsoft Azure IoT SDK för Node.js du laddade ned. Installera de paket som krävs:
```
cd azure-iot-sdk-node/provisioning/tools
npm install
```
Skapa ett rotcertifikat och härled sedan ett enhetscertifikat genom att köra skriptet:
```
node create_test_cert.js root mytestrootcert
node create_test_cert.js device sample-device-01 mytestrootcert
```
Dricks

Ett enhets-ID kan innehålla bokstäver, siffror och - tecknet.

Dessa kommandon skapar följande rot- och enhetscertifikat:

filename	innehåll
mytestrootcert_cert.pem	Den offentliga delen av rotcertifikatet X.509
mytestrootcert_key.pem	Den privata nyckeln för rotcertifikatet X.509
mytestrootcert_fullchain.pem	Hela nyckelringen för rotcertifikatet X.509.
mytestrootcert.pfx	PFX-filen för rotcertifikatet X.509.
sampleDevice01_cert.pem	Den offentliga delen av X.509-enhetscertifikatet
sampleDevice01_key.pem	Den privata nyckeln för X.509-enhetscertifikatet
sampleDevice01_fullchain.pem	Hela nyckelringen för enhetens X.509-certifikat.
sampleDevice01.pfx	PFX-filen för X.509-enhetens certifikat.

Anteckna platsen för dessa filer. Du behöver det senare.

Generera den base-64-kodade versionen av rotcertifikatet

I mappen på den lokala datorn som innehåller de certifikat som du genererade skapar du en fil med namnet convert.js och lägger till följande JavaScript-innehåll:

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

Kör följande kommando för att generera en base-64-kodad version av certifikatet:

node convert.js mytestrootcert_cert.pem

Anteckna den base-64-kodade versionen av certifikatet. Du behöver det senare.

Lägga till en X.509-registreringsgrupp

Använd följande begäran för att skapa en ny registreringsgrupp med myx509eg som ID:

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

I följande exempel visas en begärandetext som lägger till en ny X.509-registreringsgrupp:

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

Begärandetexten innehåller några obligatoriska fält:

@displayName: Visningsnamn för registreringsgruppen.
@enabled: Om enheterna som använder gruppen tillåts ansluta till IoT Central.
@type: Typ av enheter som ansluter via gruppen, antingen iot eller iotEdge.
attestation: Attesteringsmekanismen för registreringsgruppen, antingen symmetricKey eller x509.

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

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

Lägga till ett X.509-certifikat i en registreringsgrupp

Använd följande begäran för att ange det primära X.509-certifikatet för registreringsgruppen myx509eg:

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

Använd den här begäran om du vill lägga till antingen ett primärt eller sekundärt X.509-certifikat i registreringsgruppen.

I följande exempel visas en begärandetext som lägger till ett X.509-certifikat i en registreringsgrupp:

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

certificate – base-64-versionen av certifikatet som du antecknade tidigare.
verifierad – true om du intygar att certifikatet är giltigt, false om du behöver bevisa certifikatets giltighet.

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

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

Generera verifieringskod för ett X.509-certifikat

Använd följande begäran för att generera en verifieringskod för det primära eller sekundära X.509-certifikatet för en registreringsgrupp.

Om du anger verified till false i föregående begäran använder du följande begäran för att generera en verifieringskod för det primära X.509-certifikatet i myx509eg registreringsgruppen:

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

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

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

Anteckna verifieringskoden. Du behöver den i nästa steg.

Generera verifieringscertifikatet

Använd följande kommando för att generera ett verifieringscertifikat från verifieringskoden i föregående steg:

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

Kör följande kommando för att generera en base-64-kodad version av certifikatet:

node convert.js verification_cert.pem

Anteckna den base-64-kodade versionen av certifikatet. Du behöver det senare.

Verifiera X.509-certifikat för en registreringsgrupp

Använd följande begäran för att verifiera det primära X.509-certifikatet för myx509eg registreringsgruppen genom att ange certifikatet med den signerade verifieringskoden:

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

I följande exempel visas en begärandetext som verifierar ett X.509-certifikat:

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

Hämta X.509-certifikat för en registreringsgrupp

Använd följande begäran för att hämta information om X.509-certifikat för en registreringsgrupp från ditt program:

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

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

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

Ta bort ett X.509-certifikat från en registreringsgrupp

Använd följande begäran för att ta bort det primära X.509-certifikatet från en registreringsgrupp med ID myx509eg:

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

Lägga till en symmetrisk nyckelregistreringsgrupp

Använd följande begäran för att skapa en ny registreringsgrupp med mysymmetric som ID:

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

I följande exempel visas en begärandetext som lägger till en ny registreringsgrupp:

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

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

{
  "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 genererar de primära och sekundära symmetriska nycklarna när du gör det här API-anropet.

Hämta en registreringsgrupp

Använd följande begäran för att hämta information om en registreringsgrupp med mysymmetric som ID:

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

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

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

Uppdatera en registreringsgrupp

Använd följande begäran för att uppdatera en registreringsgrupp.

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

I följande exempel visas en begärandetext som uppdaterar visningsnamnet för en registreringsgrupp:

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

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

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

Ta bort en registreringsgrupp

Använd följande begäran för att ta bort en registreringsgrupp med ID myx509eg:

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

Lista registreringsgrupper

Använd följande begäran för att hämta en lista över registreringsgrupper från ditt program:

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

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

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

Dela via

Så här använder du IoT Central REST API för att hantera enheter

REST API för enheter

Lägg till en enhet

Hämta en enhet

Hämta enhetsautentiseringsuppgifter

Uppdatera en enhet

Ta bort en enhet

Visa enheter

Tilldela ett distributionsmanifest

Använda ODATA-filter

maxpagesize

filter

orderby

Enhetsgrupper

Lägga till en enhetsgrupp

Hämta en enhetsgrupp

Uppdatera en enhetsgrupp

Ta bort en enhetsgrupp

Lista enhetsgrupper

Registreringsgrupper

Skapa en registreringsgrupp

Generera rot- och enhetscertifikat

Generera den base-64-kodade versionen av rotcertifikatet

Lägga till en X.509-registreringsgrupp

Lägga till ett X.509-certifikat i en registreringsgrupp

Generera verifieringskod för ett X.509-certifikat

Generera verifieringscertifikatet

Verifiera X.509-certifikat för en registreringsgrupp

Hämta X.509-certifikat för en registreringsgrupp

Ta bort ett X.509-certifikat från en registreringsgrupp

Lägga till en symmetrisk nyckelregistreringsgrupp

Hämta en registreringsgrupp

Uppdatera en registreringsgrupp

Ta bort en registreringsgrupp

Lista registreringsgrupper

Feedback

Ytterligare resurser