Dela via

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

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.

Skapa en registreringsgrupp

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.

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

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

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