Použití rozhraní IoT Central REST API ke správě zařízení

  • Článek

Rozhraní IoT Central REST API umožňuje vyvíjet klientské aplikace, které se integrují s aplikacemi IoT Central. Rozhraní REST API můžete použít ke správě zařízení v aplikaci IoT Central.

Každé volání rozhraní REST API služby IoT Central vyžaduje autorizační hlavičku. Další informace najdete v tématu Ověřování a autorizace volání rozhraní REST API služby IoT Central.

Referenční dokumentaci k rozhraní IoT Central REST API najdete v referenčních informacích k rozhraní REST API služby Azure IoT Central.

Tip

Pomocí nástroje Postman můžete vyzkoušet volání rozhraní REST API popsaná v tomto článku. Stáhněte si kolekci IoT Central Postman a naimportujte ji do Postmanu. V kolekci budete muset nastavit proměnné, jako je subdoména vaší aplikace a token správce.

Informace o správě zařízení pomocí uživatelského rozhraní IoT Central najdete v tématu Správa jednotlivých zařízení v aplikaci Azure IoT Central.

Rozhraní REST API pro zařízení

Rozhraní IoT Central REST API umožňuje:

  • Přidání zařízení do aplikace
  • Aktualizace zařízení v aplikaci
  • Získat seznam zařízení v aplikaci
  • Získat zařízení podle ID
  • Získání přihlašovacích údajů zařízení
  • Odstranění zařízení v aplikaci
  • Filtrování seznamu zařízení v aplikaci

Přidání zařízení

Pomocí následujícího požadavku vytvořte nové zařízení.

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

Následující příklad ukazuje text požadavku, který přidá zařízení pro šablonu zařízení. Podrobnosti najdete template na stránce šablon zařízení v uživatelském rozhraní aplikace IoT Central.

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

Text požadavku obsahuje některá povinná pole:

  • @displayName: Zobrazovaný název zařízení.
  • @enabled: Deklaruje, že tento objekt je rozhraní.
  • @etag: ETag použitý k zabránění konfliktům v aktualizacích zařízení.
  • simulated: Simuluje se zařízení?
  • template : Definice šablony zařízení pro zařízení.

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Získání zařízení

Pomocí následujícího požadavku načtěte podrobnosti o zařízení z vaší aplikace:

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

Poznámka:

Uživatelské rozhraní aplikace IoT Central můžete získat deviceId tak, že na zařízení najedete myší.

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Následující tabulka ukazuje, jak se stavová hodnota zařízení v uživatelském rozhraní mapuje na hodnoty používané rozhraním REST API pro interakci se zařízeními:

Stav zařízení uživatelského rozhraní Notes Získání rozhraní REST API
Čekání na schválení Možnost automatického schvalování je ve skupině připojení zařízení zakázaná a zařízení se nepřidá prostřednictvím uživatelského rozhraní.
Uživatel musí zařízení před jeho používáním ručně schválit prostřednictvím uživatelského rozhraní.		 Provisioned: false
Enabled: false
Registrováno Zařízení bylo schváleno buď automaticky, nebo ručně. Provisioned: false
Enabled: true
Zřízené Zařízení bylo zřízeno a může se připojit k aplikaci IoT Central. Provisioned: true
Enabled: true
Blokované Zařízení se nemůže připojit k aplikaci IoT Central. Zařízení, které je v jakémkoli jiném stavu, můžete zablokovat. Provisioned: závisí na Waiting for approval/Registered/Provisioned status
Enabled: false

Získání přihlašovacích údajů zařízení

Pomocí následujícího požadavku načtěte přihlašovací údaje zařízení z vaší aplikace:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Aktualizovat zařízení

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

Následující vzorový text požadavku změní pole na enabledfalse:

{
  "enabled": false
}

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Odstranit zařízení

K odstranění zařízení použijte následující požadavek:

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

Získejte seznam zařízení.

Pomocí následujícího požadavku načtěte seznam zařízení z vaší aplikace:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Přiřazení manifestu nasazení

Pokud přidáváte zařízení IoT Edge, můžete k zařízení přiřadit manifest nasazení IoT Edge pomocí rozhraní API. Další informace najdete v tématu Přiřazení manifestu nasazení k zařízení.

Použití filtrů ODATA

Ve verzi Preview rozhraní API (api-version=2022-10-31-preview) můžete pomocí filtrů ODATA filtrovat a řadit výsledky vrácené rozhraním API seznamu zařízení.

maxpagesize

K nastavení velikosti výsledku použijte maxpagesize. Maximální vrácená velikost výsledku je 100 a výchozí velikost je 25.

Pomocí následujícího požadavku načtěte z aplikace 10 nejlepších zařízení:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Odpověď obsahuje hodnotu nextLink , kterou můžete použít k načtení další stránky výsledků.

filter

Pomocí filtru můžete vytvářet výrazy, které filtrují seznam zařízení. Následující tabulka uvádí operátory porovnání, které můžete použít:

Relační operátor Symbol Příklad
Je rovno eq id eq 'device1' and scopes eq 'redmond'
Není rovno ne Enabled ne true
Menší než nebo rovno le id le '26whl7mure6'
Je menší než lt id lt '26whl7mure6'
Větší než nebo rovno ge id ge '26whl7mure6'
Je větší než gt id gt '26whl7mure6'

Následující tabulka ukazuje operátory logiky, které můžete použít ve výrazech filtru :

Operátor logiky Symbol Příklad
A a id eq 'device1' and enabled eq true
NEBO nebo id eq 'device1' or simulated eq false

V současné době filtr funguje s následujícími poli zařízení:

Fieldname Typ Description
id string ID zařízení
displayName string Zobrazovaný název zařízení
enabled boolean Stav povoleného zařízení
provisioned boolean Stav zřízeného zařízení
simulated boolean Stav simulovaného zařízení
template string ID šablony zařízení
scopes string ID organizace

podporované funkce filtru:

V současné době je jedinou podporovanou contains funkcí filtru pro seznamy zařízení funkce:

filter=contains(displayName, 'device1')

Následující příklad ukazuje, jak načíst všechna zařízení, kde zobrazovaný název obsahuje řetězec thermostat:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Výsledky můžete seřadit pomocí orderby . V současné době orderby umožňuje řazení pouze podle displayName. Ve výchozím nastavení řazení seřadí pořadí ve vzestupném pořadí. Pomocí funkce desc můžete seřadit sestupně, například:

orderby=displayName
orderby=displayName desc

Následující příklad ukazuje, jak načíst všechny šablony zařízení, podle kterých je výsledek seřazen:displayName

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Můžete také zkombinovat dva nebo více filtrů.

Následující příklad ukazuje, jak načíst první tři zařízení, kde zobrazovaný název obsahuje řetězec Thermostat.

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Skupiny zařízení

Skupiny zařízení můžete vytvořit v aplikaci IoT Central pro monitorování agregovaných dat, použití s úlohami a správu přístupu. Skupiny zařízení jsou definovány filtrem, který vybere zařízení, která se mají přidat do skupiny. Skupiny zařízení můžete vytvářet na portálu IoT Central nebo pomocí rozhraní API.

Přidání skupiny zařízení

Pomocí následujícího požadavku vytvořte novou skupinu zařízení.

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

Když vytvoříte skupinu zařízení, definujete filter , která vybere zařízení, která se mají do skupiny přidat. A filter identifikuje šablonu zařízení a všechny vlastnosti, které se mají shodovat. Následující příklad vytvoří skupinu zařízení, která obsahuje všechna zařízení přidružená k šabloně "dtmi:modelDefinition:dtdlv2", kde provisioned je truevlastnost .

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

Text požadavku obsahuje některá povinná pole:

  • @displayName: Zobrazovaný název skupiny zařízení.
  • @filter: Dotaz definující zařízení, která mají být v této skupině.
  • @etag: ETag použitý k zabránění konfliktům v aktualizacích zařízení.
  • description: Krátký přehled skupiny zařízení.

Pole organizace se používá jenom v případech, kdy má aplikace definovanou hierarchii organizace. Další informace o organizacích najdete v tématu Správa organizací IoT Central.

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Získání skupiny zařízení

Pomocí následujícího požadavku načtěte podrobnosti o skupině zařízení z vaší aplikace:

GET https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31
  • deviceGroupId – Jedinečné ID pro skupinu zařízení.

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Aktualizace skupiny zařízení

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

Tělo ukázkové žádosti vypadá jako v následujícím příkladu, který aktualizuje displayName skupinu zařízení:

{
  "displayName": "New group name"
}

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Odstranění skupiny zařízení

K odstranění skupiny zařízení použijte následující požadavek:

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

Výpis skupin zařízení

Pomocí následujícího požadavku načtěte seznam skupin zařízení z vaší aplikace:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Skupiny registrací

Skupiny registrací se používají ke správě možností ověřování zařízení v aplikaci IoT Central. Další informace najdete v tématu Koncepty ověřování zařízení v IoT Central.

Informace o vytváření a správě skupin registrací v uživatelském rozhraní najdete v tématu Postup připojení zařízení s certifikáty X.509 k aplikaci IoT Central.

Vytvoření skupiny registrací

Když vytvoříte skupinu registrací pro zařízení, která používají certifikáty X.509, musíte nejprve nahrát kořenový nebo zprostředkující certifikát do aplikace IoT Central.

Generování kořenových certifikátů a certifikátů zařízení

V této části vygenerujete certifikáty X.509, které potřebujete k připojení zařízení ke službě IoT Central.

Upozorňující

Tímto způsobem se generují certifikáty X.509 pouze pro testování. V produkčním prostředí byste měli používat oficiální zabezpečený mechanismus pro generování certifikátů.

  1. Přejděte do skriptu generátoru certifikátů v sadě Microsoft Azure IoT SDK pro Node.js jste si stáhli. Nainstalujte požadované balíčky:

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

  2. Vytvořte kořenový certifikát a potom odvodit certifikát zařízení spuštěním skriptu:

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

    Tip

    ID zařízení může obsahovat písmena, číslice a - znak.

Tyto příkazy vytvoří následující kořenový adresář a certifikáty zařízení:

filename Obsah
mytestrootcert_cert.pem Veřejná část kořenového certifikátu X.509
mytestrootcert_key.pem Privátní klíč pro kořenový certifikát X.509
mytestrootcert_fullchain.pem Celý klíčence kořenového certifikátu X.509.
mytestrootcert.pfx Soubor PFX pro kořenový certifikát X.509.
sampleDevice01_cert.pem Veřejná část certifikátu X.509 zařízení
sampleDevice01_key.pem Privátní klíč pro certifikát X.509 zařízení
sampleDevice01_fullchain.pem Celá řetězce klíčů pro certifikát X.509 zařízení.
sampleDevice01.pfx Soubor PFX pro certifikát X.509 zařízení.

Poznamenejte si umístění těchto souborů. Budete ho potřebovat později.

Vygenerování verze kořenového certifikátu s kódováním base-64

Ve složce na místním počítači, který obsahuje certifikáty, které jste vygenerovali, vytvořte soubor s názvem convert.js a přidejte následující obsah JavaScriptu:

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

Spuštěním následujícího příkazu vygenerujte verzi certifikátu kódování base-64:

node convert.js mytestrootcert_cert.pem

Poznamenejte si verzi certifikátu s kódováním base-64. Budete ho potřebovat později.

Přidání skupiny registrací X.509

Pomocí následujícího požadavku vytvořte novou skupinu registrací s myx509eg ID:

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

Následující příklad ukazuje text požadavku, který přidá novou skupinu registrací X.509:

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

Text požadavku obsahuje některá povinná pole:

  • @displayName: Zobrazovaný název skupiny registrací.
  • @enabled: Určuje, jestli se zařízení používající skupinu můžou připojit ke službě IoT Central.
  • @type: Typ zařízení, která se připojují prostřednictvím skupiny, nebo iotiotEdge.
  • attestation: Mechanismus ověření identity pro skupinu registrací, buď symmetricKey nebo x509.

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Přidání certifikátu X.509 do skupiny registrací

Pomocí následujícího požadavku nastavte primární certifikát X.509 skupiny registrací myx509eg:

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

Tento požadavek použijte k přidání primárního nebo sekundárního certifikátu X.509 do skupiny registrací.

Následující příklad ukazuje text požadavku, který přidá certifikát X.509 do skupiny registrací:

{
  "verified": false,
  "certificate": "<base64-certificate>"
}
  • certifikát – verze base-64 certifikátu, který jste si poznamenali dříve.
  • ověřeno – true pokud ověříte, že certifikát je platný, false pokud potřebujete prokázat platnost certifikátu.

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Vygenerování ověřovacího kódu pro certifikát X.509

Pomocí následujícího požadavku vygenerujte ověřovací kód pro primární nebo sekundární certifikát X.509 skupiny registrací.

Pokud jste nastavili verifiedfalse v předchozím požadavku, pomocí následujícího požadavku vygenerujte ověřovací kód pro primární certifikát X.509 ve myx509eg skupině registrací:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Poznamenejte si ověřovací kód, který potřebujete v dalším kroku.

Vygenerování ověřovacího certifikátu

Pomocí následujícího příkazu vygenerujte ověřovací certifikát z ověřovacího kódu v předchozím kroku:

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

Spuštěním následujícího příkazu vygenerujte zakódovanou verzi certifikátu base-64:

node convert.js verification_cert.pem

Poznamenejte si verzi certifikátu s kódováním base-64. Budete ho potřebovat později.

Ověření certifikátu X.509 skupiny registrací

Pomocí následujícího požadavku ověřte primární certifikát myx509eg X.509 skupiny registrací zadáním certifikátu podepsaného ověřovacího kódu:

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

Následující příklad ukazuje text požadavku, který ověřuje certifikát X.509:

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

Získání certifikátu X.509 skupiny registrací

Pomocí následujícího požadavku načtěte podrobnosti o certifikátu X.509 skupiny registrací z vaší aplikace:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Odstranění certifikátu X.509 ze skupiny registrací

Pomocí následujícího požadavku odstraňte primární certifikát X.509 ze skupiny registrací s ID myx509eg:

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

Získání skupiny registrací

Pomocí následujícího požadavku načtěte podrobnosti o skupině registrací s mysymmetric ID:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Aktualizace skupiny registrací

Pomocí následujícího požadavku aktualizujte skupinu registrací.

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

Následující příklad ukazuje text požadavku, který aktualizuje zobrazovaný název skupiny registrací:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Odstranění skupiny registrací

Pomocí následujícího požadavku odstraňte skupinu registrací s ID myx509eg:

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

Výpis skupin registrací

Pomocí následujícího požadavku načtěte ze své aplikace seznam skupin registrací:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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