Az IoT Central REST API használata eszközök kezelésére

  • Cikk

Az IoT Central REST API lehetővé teszi az IoT Central-alkalmazásokkal integrálható ügyfélalkalmazások fejlesztését. A REST API-val kezelheti az IoT Central-alkalmazásban lévő eszközöket.

Minden IoT Central REST API-híváshoz szükség van egy engedélyezési fejlécre. További információ: IoT Central REST API-hívások hitelesítése és engedélyezése.

Az IoT Central REST API referenciadokumentációját az Azure IoT Central REST API-referenciájában találja.

Tipp.

A Postman használatával kipróbálhatja a cikkben ismertetett REST API-hívásokat. Töltse le az IoT Central Postman gyűjteményt , és importálja a Postmanbe. A gyűjteményben olyan változókat kell beállítania, mint az alkalmazás altartománya és a rendszergazdai jogkivonat.

Ha tudni szeretné, hogyan kezelheti az eszközöket az IoT Central felhasználói felületével, olvassa el az Egyes eszközök kezelése az Azure IoT Central-alkalmazásban című témakört .

Eszközök REST API

Az IoT Central REST API használatával a következőket teheti:

  • Eszköz hozzáadása az alkalmazáshoz
  • Eszköz frissítése az alkalmazásban
  • Az alkalmazásban található eszközök listájának beolvasása
  • Eszköz lekérése azonosító alapján
  • Eszköz hitelesítő adatainak lekérése
  • Eszköz törlése az alkalmazásban
  • Az alkalmazásban lévő eszközök listájának szűrése

Eszköz hozzáadása

Az alábbi kéréssel hozzon létre egy új eszközt.

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

Az alábbi példa egy olyan kéréstörzset mutat be, amely egy eszközsablonhoz ad hozzá eszközt. A részleteket az template IoT Central-alkalmazás felhasználói felületén található eszközsablonok oldaláról szerezheti be.

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

A kérelem törzse tartalmaz néhány kötelező mezőt:

  • @displayName: Az eszköz megjelenítendő neve.
  • @enabled: Deklarálja, hogy ez az objektum egy interfész.
  • @etag: Az eszközfrissítések ütközésének megelőzésére szolgáló ETag.
  • simulated: Az eszköz szimulálva van?
  • template : Az eszköz eszközsablon-definíciója.

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Eszköz lekérése

Az alábbi kéréssel kérheti le az eszköz adatait az alkalmazásból:

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

Feljegyzés

Az IoT Central-alkalmazás felhasználói felületét úgy szerezheti be deviceId , ha az egérmutatót egy eszközre viszi.

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Az alábbi táblázat azt mutatja be, hogy a felhasználói felületen lévő eszközök állapotértéke hogyan képezi le azokat az értékeket, amelyeket a REST API használ az eszközökkel való interakcióhoz:

Felhasználói felület eszközállapota Jegyzetek REST API lekérése
Várakozás jóváhagyásra Az automatikus jóváhagyás lehetőség le van tiltva az eszköz kapcsolatcsoportjában, és az eszköz nem lett hozzáadva a felhasználói felületen keresztül.
A felhasználónak manuálisan kell jóváhagynia az eszközt a felhasználói felületen keresztül, mielőtt használni lehetne.		 Provisioned: false
Enabled: false
Regisztrálva Az eszköz jóváhagyása automatikusan vagy manuálisan történt. Provisioned: false
Enabled: true
Kiépítve Az eszköz ki lett építve, és csatlakozhat az IoT Central-alkalmazáshoz. Provisioned: true
Enabled: true
Blokkolva Az eszköz nem csatlakozhat az IoT Central-alkalmazáshoz. Bármely más állapotban lévő eszközt letilthat. Provisioned: Függ Waiting for approval/Registered/Provisioned status
Enabled: false

Eszköz hitelesítő adatainak letöltése

Az eszköz hitelesítő adatainak az alkalmazásból való lekéréséhez használja a következő kérést:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Eszköz frissítése

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

A következő mintakérés törzse a mezőt a enabled következőre falsemódosítja:

{
  "enabled": false
}

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Eszköz törlése

Az eszköz törléséhez használja a következő kérést:

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

Eszközök listázása

Az alábbi kéréssel lekérheti az eszközök listáját az alkalmazásból:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Üzembehelyezési jegyzék hozzárendelése

Ha IoT Edge-eszközt ad hozzá, az API-val hozzárendelhet egy IoT Edge-telepítési jegyzékfájlt az eszközhöz. További információ: Üzembehelyezési jegyzék hozzárendelése eszközhöz.

ODATA-szűrők használata

Az APIapi-version=2022-10-31-preview () előzetes verziójában ODATA-szűrőkkel szűrheti és rendezheti a listaeszközök API által visszaadott eredményeket.

maxpagesize

Az eredmény méretének beállításához használja a maxpagesize értéket. A visszaadott eredmény maximális mérete 100, az alapértelmezett méret pedig 25.

A következő kéréssel lekérheti a 10 legjobb eszközt az alkalmazásból:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

A válasz tartalmaz egy nextLink értéket, amellyel lekérheti a következő találatoldalt.

szűrő

A szűrővel olyan kifejezéseket hozhat létre, amelyek szűrik az eszközök listáját. Az alábbi táblázat a használható összehasonlító operátorokat mutatja be:

Összehasonlító operátor Szimbólum Példa
Egyenlő eq id eq 'device1' and scopes eq 'redmond'
Nem egyenlő ne Enabled ne true
Kisebb vagy egyenlő le id le '26whl7mure6'
Kisebb mint Hadnagy id lt '26whl7mure6'
Nagyobb vagy egyenlő ge id ge '26whl7mure6'
Nagyobb mint Gt id gt '26whl7mure6'

Az alábbi táblázat a szűrőkifejezésekben használható logikai operátorokat mutatja be:

Logikai operátor Szimbólum Példa
ÉS és id eq 'device1' and enabled eq true
VAGY vagy id eq 'device1' or simulated eq false

A szűrés jelenleg a következő eszközmezőkkel működik:

Mezőnév Típus Leírás
id húr Eszközazonosító
displayName húr Eszközmegjelenítés neve
enabled Logikai Eszköz által engedélyezett állapot
provisioned Logikai Eszköz kiépített állapota
simulated Logikai Eszköz szimulált állapota
template húr Eszközsablon azonosítója
scopes húr szervezet azonosítója

támogatott függvények szűrése:

Jelenleg az eszközlisták egyetlen támogatott szűrőfüggvénye a contains függvény:

filter=contains(displayName, 'device1')

Az alábbi példa bemutatja, hogyan kérhető le az összes eszköz, ahol a megjelenítendő név tartalmazza a sztringet thermostat:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Az eredmények rendezéséhez használja az orderby parancsot . Az orderby jelenleg csak a displayName sorrendbe rendezését teszi lehetővé. Alapértelmezés szerint az orderby növekvő sorrendben rendez. A desc használatával csökkenő sorrendben rendezhet, például:

orderby=displayName
orderby=displayName desc

Az alábbi példa bemutatja, hogyan kérhető le az összes olyan eszközsablon, amelyben az eredmény a következő szerint displayName van rendezve:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Két vagy több szűrőt is kombinálhat.

Az alábbi példa bemutatja, hogyan lehet lekérni az első három eszközt, ahol a megjelenítendő név tartalmazza a sztringet Thermostat.

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Eszközcsoportok

Az IoT Central-alkalmazásokban eszközcsoportokat hozhat létre az összesített adatok figyeléséhez, a feladatokhoz való használathoz és a hozzáférés kezeléséhez. Az eszközcsoportokat egy szűrő határozza meg, amely kiválasztja a csoporthoz hozzáadni kívánt eszközöket. Eszközcsoportokat az IoT Central portálon vagy az API használatával hozhat létre.

Eszközcsoport hozzáadása

Az alábbi kéréssel hozzon létre egy új eszközcsoportot.

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

Amikor létrehoz egy eszközcsoportot, meghatároz egy filter olyan eszközt, amely kiválasztja a csoporthoz hozzáadni kívánt eszközöket. Az A filter azonosítja az eszközsablont és az egyező tulajdonságokat. Az alábbi példa olyan eszközcsoportot hoz létre, amely a tulajdonságot tartalmazó "dtmi:modelDefinition:dtdlv2" sablonhoz provisionedtruetársított összes eszközt tartalmazza.

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

A kérelem törzse tartalmaz néhány kötelező mezőt:

  • @displayName: Az eszközcsoport megjelenítendő neve.
  • @filter: Lekérdezés, amely meghatározza, hogy mely eszközök legyenek ebben a csoportban.
  • @etag: Az eszközfrissítések ütközésének megelőzésére szolgáló ETag.
  • description: Az eszközcsoport rövid összefoglalása.

A szervezetek mezőt csak akkor használja a rendszer, ha egy alkalmazás szervezeti hierarchiát definiált. A szervezetekről további információt az IoT Central-szervezetek kezelése című témakörben talál.

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Eszközcsoport lekérése

Az alábbi kéréssel lekérheti egy eszközcsoport adatait az alkalmazásból:

GET https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31
  • deviceGroupId – Az eszközcsoport egyedi azonosítója.

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Eszközcsoport frissítése

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

A mintakérés törzse a következő példához hasonlóan néz ki, amely frissíti az displayName eszközcsoportot:

{
  "displayName": "New group name"
}

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Eszközcsoport törlése

Eszközcsoport törléséhez használja a következő kérést:

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

Eszközcsoportok listázása

Az alábbi kéréssel lekérheti az eszközcsoportok listáját az alkalmazásból:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Regisztrációs csoportok

A regisztrációs csoportok az IoT Central-alkalmazás eszközhitelesítési beállításainak kezelésére szolgálnak. További információ: Eszközhitelesítési fogalmak az IoT Centralban.

Ha szeretné megtudni, hogyan hozhat létre és kezelhet regisztrációs csoportokat a felhasználói felületen, olvassa el az Eszközök csatlakoztatása X.509-tanúsítványokkal az IoT Central-alkalmazáshoz című témakört.

Regisztrációs csoport létrehozása

Amikor X.509-tanúsítványokat használó eszközökhöz hoz létre regisztrációs csoportot, először fel kell töltenie a főtanúsítványt vagy a köztes tanúsítványt az IoT Central-alkalmazásba.

Gyökér- és eszköztanúsítványok létrehozása

Ebben a szakaszban azokat az X.509-tanúsítványokat hozza létre, amelyekre egy eszköznek az IoT Centralhoz való csatlakoztatásához szüksége van.

Figyelmeztetés

Az X.509-tanúsítványok létrehozásának ez a módja csak tesztelésre használható. Éles környezetben a tanúsítványgenerálás hivatalos, biztonságos mechanizmusát kell használnia.

  1. A letöltött Node.js a Microsoft Azure IoT SDK-ban keresse meg a tanúsítványgenerátor szkriptjét. Telepítse a szükséges csomagokat:

    cd azure-iot-sdk-node/provisioning/tools
npm install

  2. Hozzon létre egy főtanúsítványt, majd hozzon létre egy eszköztanúsítványt a szkript futtatásával:

    node create_test_cert.js root mytestrootcert
node create_test_cert.js device sample-device-01 mytestrootcert

    Tipp.

    Az eszközazonosító tartalmazhat betűket, számokat és karaktereket - .

Ezek a parancsok a következő gyökér- és eszköztanúsítványokat állítják elő:

fájlnév Tartalmát
mytestrootcert_cert.pem A fő X.509-tanúsítvány nyilvános része
mytestrootcert_key.pem Az X.509 főtanúsítvány titkos kulcsa
mytestrootcert_fullchain.pem Az X.509 főtanúsítvány teljes kulcslánca.
mytestrootcert.pfx Az X.509 főtanúsítvány PFX-fájlja.
sampleDevice01_cert.pem Az eszköz X.509-tanúsítványának nyilvános része
sampleDevice01_key.pem Az X.509-tanúsítvány titkos kulcsa
sampleDevice01_fullchain.pem Az X.509-tanúsítvány teljes kulcslánca.
sampleDevice01.pfx Az eszköz X.509-tanúsítványának PFX-fájlja.

Jegyezze fel a fájlok helyét. Később szüksége lesz rá.

A főtanúsítvány base-64 kódolású verziójának létrehozása

A létrehozott tanúsítványokat tartalmazó helyi gép mappájában hozzon létre egy convert.js nevű fájlt, és adja hozzá a következő JavaScript-tartalmat:

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

Futtassa a következő parancsot a tanúsítvány base-64 kódolású verziójának létrehozásához:

node convert.js mytestrootcert_cert.pem

Jegyezze fel a tanúsítvány base-64 kódolású verzióját. Később szüksége lesz rá.

X.509-regisztrációs csoport hozzáadása

Az alábbi kéréssel hozzon létre egy új regisztrációs csoportot myx509eg azonosítóként:

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

Az alábbi példa egy új X.509-regisztrációs csoportot hozzáadó kérelemtörzset mutat be:

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

A kérelem törzse tartalmaz néhány kötelező mezőt:

  • @displayName: A regisztrációs csoport megjelenítendő neve.
  • @enabled: A csoportot használó eszközök csatlakozhatnak-e az IoT Centralhoz.
  • @type: A csoporton keresztül csatlakozó eszközök típusa vagy iotiotEdge.
  • attestation: A regisztrációs csoport igazolási mechanizmusa vagy symmetricKeyx509.

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

X.509-tanúsítvány hozzáadása egy regisztrációs csoporthoz

A következő kéréssel állítsa be a myx509eg regisztrációs csoport elsődleges X.509-tanúsítványát:

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

Ezzel a kéréssel hozzáadhat egy elsődleges vagy másodlagos X.509-tanúsítványt a regisztrációs csoporthoz.

Az alábbi példa egy kérelemtörzset mutat be, amely egy X.509-tanúsítványt ad hozzá egy regisztrációs csoporthoz:

{
  "verified": false,
  "certificate": "<base64-certificate>"
}
  • tanúsítvány – A korábban jegyzett tanúsítvány 64-es alapverziója.
  • igazolt – true ha igazolja a tanúsítvány érvényességét, false ha igazolnia kell a tanúsítvány érvényességét.

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Ellenőrző kód létrehozása X.509-tanúsítványhoz

A következő kéréssel létrehozhat egy ellenőrző kódot egy regisztrációs csoport elsődleges vagy másodlagos X.509-tanúsítványához.

Ha az előző kérelemben beállította verifiedfalse , a következő kéréssel hozzon létre ellenőrző kódot az elsődleges X.509-tanúsítványhoz a myx509eg regisztrációs csoportban:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Jegyezze fel az ellenőrző kódot, és a következő lépésben szüksége lesz rá.

Az ellenőrző tanúsítvány generálása

Az alábbi paranccsal hozzon létre egy ellenőrző tanúsítványt az előző lépés ellenőrző kódjából:

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

Futtassa a következő parancsot a tanúsítvány base-64 kódolású verziójának létrehozásához:

node convert.js verification_cert.pem

Jegyezze fel a tanúsítvány base-64 kódolású verzióját. Később szüksége lesz rá.

Regisztrációs csoport X.509-tanúsítványának ellenőrzése

A következő kéréssel ellenőrizheti a regisztrációs csoport elsődleges X.509-tanúsítványát az myx509eg aláírt ellenőrző kóddal ellátott tanúsítvány megadásával:

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

Az alábbi példa egy X.509-tanúsítványt ellenőrző kérelemtörzset mutat be:

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

Regisztrációs csoport X.509-tanúsítványának lekérése

A következő kéréssel lekérheti egy regisztrációs csoport X.509-tanúsítványának adatait az alkalmazásból:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

X.509-tanúsítvány törlése egy regisztrációs csoportból

Az alábbi kéréssel törölje az elsődleges X.509-tanúsítványt egy azonosítóval myx509egrendelkező regisztrációs csoportból:

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

Regisztrációs csoport lekérése

A következő kéréssel lekérheti egy regisztrációs csoport mysymmetric adatait azonosítóként:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Regisztrációs csoport frissítése

A következő kéréssel frissíthet egy regisztrációs csoportot.

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

Az alábbi példa egy regisztrációs csoport megjelenítendő nevét kérő törzset mutat be:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Regisztrációs csoport törlése

A következő kéréssel törölhet egy azonosítóval myx509egrendelkező regisztrációs csoportot:

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

Regisztrációs csoportok listázása

A következő kéréssel lekérheti a regisztrációs csoportok listáját az alkalmazásból:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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