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

Článek
03/05/2024

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.

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 enabled false:

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

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

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
```
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 iot iotEdge.
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 verified false 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

Přidání skupiny registrace symetrického klíče

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

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

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

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

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

IoT Central při volání tohoto rozhraní API vygeneruje primární a sekundární symetrické klíče.

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

Sdílet prostřednictvím

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

Rozhraní REST API pro zařízení

Přidání zařízení

Získání zařízení

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

Aktualizovat zařízení

Odstranit zařízení

Získejte seznam zařízení.

Přiřazení manifestu nasazení

Použití filtrů ODATA

maxpagesize

filter

orderby

Skupiny zařízení

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

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

Aktualizace skupiny zařízení

Odstranění skupiny zařízení

Výpis skupin zařízení

Skupiny registrací

Vytvoření skupiny registrací

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

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

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

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

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

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

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

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

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

Přidání skupiny registrace symetrického klíče

Získání skupiny registrací

Aktualizace skupiny registrací

Odstranění skupiny registrací

Výpis skupin registrací

Váš názor

Další materiály