Share via

Jak zarządzać urządzeniami przy użyciu interfejsu API REST usługi IoT Central

  • Artykuł

Interfejs API REST usługi IoT Central umożliwia tworzenie aplikacji klienckich, które integrują się z aplikacjami usługi IoT Central. Interfejs API REST umożliwia zarządzanie urządzeniami w aplikacji usługi IoT Central.

Każde wywołanie interfejsu API REST usługi IoT Central wymaga nagłówka autoryzacji. Aby dowiedzieć się więcej, zobacz Jak uwierzytelniać i autoryzować wywołania interfejsu API REST usługi IoT Central.

Aby uzyskać dokumentację referencyjną interfejsu API REST usługi IoT Central, zobacz Dokumentacja interfejsu API REST usługi Azure IoT Central.

Napiwek

Narzędzie Postman umożliwia wypróbowanie wywołań interfejsu API REST opisanych w tym artykule. Pobierz kolekcję IoT Central Postman i zaimportuj ją do narzędzia Postman. W kolekcji należy ustawić zmienne, takie jak poddomena aplikacji i token administratora.

Aby dowiedzieć się, jak zarządzać urządzeniami przy użyciu interfejsu użytkownika usługi IoT Central, zobacz Zarządzanie poszczególnymi urządzeniami w aplikacji usługi Azure IoT Central.

Interfejs API REST urządzeń

Interfejs API REST usługi IoT Central umożliwia wykonywanie następujących działań:

  • Dodawanie urządzenia do aplikacji
  • Aktualizowanie urządzenia w aplikacji
  • Pobieranie listy urządzeń w aplikacji
  • Pobieranie urządzenia według identyfikatora
  • Uzyskiwanie poświadczeń urządzenia
  • Usuwanie urządzenia w aplikacji
  • Filtrowanie listy urządzeń w aplikacji

Dodawanie urządzenia

Użyj następującego żądania, aby utworzyć nowe urządzenie.

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

Poniższy przykład przedstawia treść żądania, która dodaje urządzenie dla szablonu urządzenia. Szczegółowe informacje można uzyskać template na stronie szablonów urządzeń w interfejsie użytkownika aplikacji usługi IoT Central.

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

Treść żądania zawiera kilka wymaganych pól:

  • @displayName: nazwa wyświetlana urządzenia.
  • @enabled: deklaruje, że ten obiekt jest interfejsem.
  • @etag: Element ETag używany do zapobiegania konfliktom w aktualizacjach urządzeń.
  • simulated: Czy urządzenie jest symulowane?
  • template : definicja szablonu urządzenia dla urządzenia.

Odpowiedź na to żądanie wygląda następująco:

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

Pobieranie urządzenia

Użyj następującego żądania, aby pobrać szczegóły urządzenia z aplikacji:

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

Uwaga

Możesz pobrać element z interfejsu deviceId użytkownika aplikacji usługi IoT Central, umieszczając wskaźnik myszy na urządzeniu.

Odpowiedź na to żądanie wygląda następująco:

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

W poniższej tabeli przedstawiono sposób mapowania wartości stanu urządzenia w interfejsie użytkownika na wartości używane przez interfejs API REST do interakcji z urządzeniami:

Stan urządzenia interfejsu użytkownika Uwagi Pobieranie interfejsu API REST
Oczekiwanie na zatwierdzenie Opcja automatycznego zatwierdzania jest wyłączona w grupie połączeń urządzeń, a urządzenie nie zostało dodane za pośrednictwem interfejsu użytkownika.
Aby można było go użyć, użytkownik musi ręcznie zatwierdzić urządzenie za pośrednictwem interfejsu użytkownika.		 Provisioned: false
Enabled: false
Zarejestrowano Urządzenie zostało zatwierdzone automatycznie lub ręcznie. Provisioned: false
Enabled: true
Zaaprowizowane Urządzenie zostało aprowidowane i może nawiązać połączenie z aplikacją usługi IoT Central. Provisioned: true
Enabled: true
Zablokowano Urządzenie nie może łączyć się z aplikacją usługi IoT Central. Możesz zablokować urządzenie, które znajduje się w dowolnym z innych stanów. Provisioned: Zależy Waiting for approval/Registered/Provisioned status
Enabled: false

Uzyskiwanie poświadczeń urządzenia

Użyj następującego żądania, aby pobrać poświadczenia urządzenia z aplikacji:

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

Odpowiedź na to żądanie wygląda następująco:

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

Aktualizowanie urządzenia

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

Następująca przykładowa treść żądania zmienia enabled pole na false:

{
  "enabled": false
}

Odpowiedź na to żądanie wygląda następująco:

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

Usuwanie urządzenia

Użyj następującego żądania, aby usunąć urządzenie:

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

Wyświetl listę urządzeń

Użyj następującego żądania, aby pobrać listę urządzeń z aplikacji:

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

Odpowiedź na to żądanie wygląda następująco:

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

Przypisywanie manifestu wdrożenia

Jeśli dodajesz urządzenie usługi IoT Edge, możesz użyć interfejsu API, aby przypisać manifest wdrożenia usługi IoT Edge do urządzenia. Aby dowiedzieć się więcej, zobacz Przypisywanie manifestu wdrożenia do urządzenia.

Korzystanie z filtrów ODATA

W wersji zapoznawczej interfejsu API (api-version=2022-10-31-preview) można użyć filtrów ODATA do filtrowania i sortowania wyników zwracanych przez interfejs API urządzeń listy.

maxpagesize

Użyj parametru maxpagesize , aby ustawić rozmiar wyniku. Maksymalny zwracany rozmiar wyniku to 100, a domyślny rozmiar to 25.

Użyj następującego żądania, aby pobrać 10 pierwszych urządzeń z aplikacji:

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

Odpowiedź na to żądanie wygląda następująco:

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

Odpowiedź zawiera wartość nextLink , której można użyć do pobrania następnej strony wyników.

filtr

Użyj filtru , aby utworzyć wyrażenia filtrujące listę urządzeń. W poniższej tabeli przedstawiono operatory porównania, których można użyć:

Operator porównania Symbol Przykład
Równa się eq id eq 'device1' and scopes eq 'redmond'
Nie równa się ne Enabled ne true
Mniejsze niż lub równe le id le '26whl7mure6'
Mniejsze niż lt id lt '26whl7mure6'
Większe niż lub równe ge id ge '26whl7mure6'
Większe niż gt id gt '26whl7mure6'

W poniższej tabeli przedstawiono operatory logiki, których można używać w wyrażeniach filtru :

Operator logiki Symbol Przykład
ORAZ oraz id eq 'device1' and enabled eq true
LUB lub id eq 'device1' or simulated eq false

Obecnie filtr działa z następującymi polami urządzenia:

Fieldname Type opis
id string Identyfikator urządzenia
displayName string Nazwa wyświetlana urządzenia
enabled boolean Stan włączonego urządzenia
provisioned boolean Stan aprowizowania urządzenia
simulated boolean Stan symulowanego urządzenia
template string Identyfikator szablonu urządzenia
scopes string identyfikator organizacji

filtrowanie obsługiwanych funkcji:

Obecnie jedyną obsługiwaną funkcją contains filtru dla list urządzeń jest funkcja:

filter=contains(displayName, 'device1')

W poniższym przykładzie pokazano, jak pobrać wszystkie urządzenia, na których nazwa wyświetlana zawiera ciąg thermostat:

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

Odpowiedź na to żądanie wygląda następująco:

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

Użyj polecenia orderby , aby posortować wyniki. Obecnie funkcja orderby umożliwia sortowanie tylko według parametru displayName. Domyślnie kolejność sortuje w kolejności rosnącej. Użyj desc do sortowania w kolejności malejącej, na przykład:

orderby=displayName
orderby=displayName desc

W poniższym przykładzie pokazano, jak pobrać wszystkie szablony urządzeń, w których wynik jest sortowany według displayName :

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

Odpowiedź na to żądanie wygląda następująco:

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

Można również połączyć dwa lub więcej filtrów.

W poniższym przykładzie pokazano, jak pobrać trzy pierwsze urządzenia, na których nazwa wyświetlana zawiera ciąg Thermostat.

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

Odpowiedź na to żądanie wygląda następująco:

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

Grupy urządzeń

Grupy urządzeń można tworzyć w aplikacji usługi IoT Central, aby monitorować zagregowane dane, używać ich z zadaniami i zarządzać dostępem. Grupy urządzeń są definiowane przez filtr, który wybiera urządzenia do dodania do grupy. Grupy urządzeń można tworzyć w portalu usługi IoT Central lub przy użyciu interfejsu API.

Dodawanie grupy urządzeń

Użyj następującego żądania, aby utworzyć nową grupę urządzeń.

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

Podczas tworzenia grupy urządzeń należy zdefiniować element filter , który wybiera urządzenia do dodania do grupy. Element filter identyfikuje szablon urządzenia i wszystkie właściwości, które mają być zgodne. Poniższy przykład obejmuje tworzenie grupy urządzeń zawierającej wszystkie urządzenia skojarzone z szablonem "dtmi:modelDefinition:dtdlv2", w którym provisioned właściwość to true.

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

Treść żądania zawiera kilka wymaganych pól:

  • @displayName: Nazwa wyświetlana grupy urządzeń.
  • @filter: Kwerenda definiująca, które urządzenia powinny znajdować się w tej grupie.
  • @etag: Element ETag używany do zapobiegania konfliktom w aktualizacjach urządzeń.
  • description: krótkie podsumowanie grupy urządzeń.

Pole organizacji jest używane tylko wtedy, gdy aplikacja ma zdefiniowaną hierarchię organizacji. Aby dowiedzieć się więcej o organizacjach, zobacz Zarządzanie organizacjami usługi IoT Central.

Odpowiedź na to żądanie wygląda następująco:

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

Pobieranie grupy urządzeń

Użyj następującego żądania, aby pobrać szczegóły grupy urządzeń z aplikacji:

GET https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31
  • deviceGroupId — unikatowy identyfikator grupy urządzeń.

Odpowiedź na to żądanie wygląda następująco:

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

Aktualizowanie grupy urządzeń

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

Przykładowa treść żądania wygląda podobnie do poniższego przykładu, który aktualizuje displayName grupę urządzeń:

{
  "displayName": "New group name"
}

Odpowiedź na to żądanie wygląda następująco:

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

Usuwanie grupy urządzeń

Użyj następującego żądania, aby usunąć grupę urządzeń:

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

Wyświetlanie listy grup urządzeń

Użyj następującego żądania, aby pobrać listę grup urządzeń z aplikacji:

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

Odpowiedź na to żądanie wygląda następująco:

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

Grupy rejestracji

Grupy rejestracji służą do zarządzania opcjami uwierzytelniania urządzeń w aplikacji usługi IoT Central. Aby dowiedzieć się więcej, zobacz Pojęcia dotyczące uwierzytelniania urządzeń w usłudze IoT Central.

Aby dowiedzieć się, jak tworzyć grupy rejestracji i zarządzać nimi w interfejsie użytkownika, zobacz Jak połączyć urządzenia z certyfikatami X.509 z aplikacją usługi IoT Central.

Tworzenie grupy rejestracji

Podczas tworzenia grupy rejestracji dla urządzeń korzystających z certyfikatów X.509 należy najpierw przekazać certyfikat główny lub pośredni do aplikacji usługi IoT Central.

Generowanie certyfikatów głównych i urządzeń

W tej sekcji wygenerujesz certyfikaty X.509, które należy połączyć z usługą IoT Central.

Ostrzeżenie

Ten sposób generowania certyfikatów X.509 jest przeznaczony tylko do testowania. W środowisku produkcyjnym należy użyć oficjalnego, bezpiecznego mechanizmu generowania certyfikatów.

  1. Przejdź do skryptu generatora certyfikatów w pobranym zestawie SDK usługi Microsoft Azure IoT dla Node.js. Zainstaluj wymagane pakiety:

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

  2. Utwórz certyfikat główny, a następnie utwórz certyfikat urządzenia, uruchamiając skrypt:

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

    Napiwek

    Identyfikator urządzenia może zawierać litery, cyfry i - znak.

Te polecenia tworzą następujący katalog główny i certyfikaty urządzeń:

filename Zawartość
mytestrootcert_cert.pem Publiczna część głównego certyfikatu X.509
mytestrootcert_key.pem Klucz prywatny certyfikatu X.509 głównego
mytestrootcert_fullchain.pem Cały pęk kluczy dla głównego certyfikatu X.509.
mytestrootcert.pfx Plik PFX dla głównego certyfikatu X.509.
sampleDevice01_cert.pem Publiczna część certyfikatu X.509 urządzenia
sampleDevice01_key.pem Klucz prywatny certyfikatu X.509 urządzenia
sampleDevice01_fullchain.pem Cały pęk kluczy dla certyfikatu X.509 urządzenia.
sampleDevice01.pfx Plik PFX dla certyfikatu X.509 urządzenia.

Zanotuj lokalizację tych plików. Potrzebujesz go później.

Generowanie zakodowanej w formacie base-64 wersji certyfikatu głównego

W folderze na komputerze lokalnym zawierającym wygenerowane certyfikaty utwórz plik o nazwie convert.js i dodaj następującą zawartość javaScript:

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

Uruchom następujące polecenie, aby wygenerować kodowaną wersję certyfikatu base-64:

node convert.js mytestrootcert_cert.pem

Zanotuj zakodowaną w formacie base-64 wersję certyfikatu. Potrzebujesz go później.

Dodawanie grupy rejestracji X.509

Użyj następującego żądania, aby utworzyć nową grupę rejestracji z myx509eg identyfikatorem:

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

W poniższym przykładzie przedstawiono treść żądania, która dodaje nową grupę rejestracji X.509:

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

Treść żądania zawiera kilka wymaganych pól:

  • @displayName: Nazwa wyświetlana grupy rejestracji.
  • @enabled: czy urządzenia korzystające z grupy mogą łączyć się z usługą IoT Central.
  • @type: typ urządzeń łączących się za pośrednictwem grupy lub iotiotEdge.
  • attestation: Mechanizm zaświadczania dla grupy rejestracji lub symmetricKeyx509.

Odpowiedź na to żądanie wygląda następująco:

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

Dodawanie certyfikatu X.509 do grupy rejestracji

Użyj następującego żądania, aby ustawić podstawowy certyfikat X.509 grupy rejestracji myx509eg:

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

Użyj tego żądania, aby dodać do grupy rejestracji certyfikat podstawowy lub pomocniczy X.509.

W poniższym przykładzie przedstawiono treść żądania, która dodaje certyfikat X.509 do grupy rejestracji:

{
  "verified": false,
  "certificate": "<base64-certificate>"
}
  • certificate — wersja base-64 certyfikatu zanotowanego wcześniej.
  • zweryfikowane — true jeśli zaświadczasz, że certyfikat jest prawidłowy, false jeśli musisz udowodnić ważność certyfikatu.

Odpowiedź na to żądanie wygląda następująco:

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

Generowanie kodu weryfikacyjnego dla certyfikatu X.509

Użyj następującego żądania, aby wygenerować kod weryfikacyjny dla podstawowego lub pomocniczego certyfikatu X.509 grupy rejestracji.

Jeśli ustawisz wartość verifiedfalse w poprzednim żądaniu, użyj następującego żądania, aby wygenerować kod weryfikacyjny podstawowego certyfikatu X.509 w myx509eg grupie rejestracji:

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

Odpowiedź na to żądanie wygląda następująco:

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

Zanotuj kod weryfikacyjny, który będzie potrzebny w następnym kroku.

Generowanie certyfikatu weryfikacji

Użyj następującego polecenia, aby wygenerować certyfikat weryfikacji na podstawie kodu weryfikacyjnego w poprzednim kroku:

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

Uruchom następujące polecenie, aby wygenerować zakodowaną w formacie base-64 wersję certyfikatu:

node convert.js verification_cert.pem

Zanotuj zakodowaną w formacie base-64 wersję certyfikatu. Potrzebujesz go później.

Weryfikowanie certyfikatu X.509 grupy rejestracji

Użyj następującego żądania, aby zweryfikować podstawowy certyfikat myx509eg X.509 grupy rejestracji, podając certyfikat z podpisanym kodem weryfikacyjnym:

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

W poniższym przykładzie przedstawiono treść żądania, która weryfikuje certyfikat X.509:

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

Pobieranie certyfikatu X.509 grupy rejestracji

Użyj następującego żądania, aby pobrać szczegóły certyfikatu X.509 grupy rejestracji z aplikacji:

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

Odpowiedź na to żądanie wygląda następująco:

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

Usuwanie certyfikatu X.509 z grupy rejestracji

Użyj następującego żądania, aby usunąć podstawowy certyfikat X.509 z grupy rejestracji o identyfikatorze myx509eg:

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

Pobieranie grupy rejestracji

Użyj następującego żądania, aby pobrać szczegóły grupy rejestracji z mysymmetric identyfikatorem:

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

Odpowiedź na to żądanie wygląda następująco:

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

Aktualizowanie grupy rejestracji

Użyj następującego żądania, aby zaktualizować grupę rejestracji.

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

W poniższym przykładzie przedstawiono treść żądania, która aktualizuje nazwę wyświetlaną grupy rejestracji:

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

Odpowiedź na to żądanie wygląda następująco:

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

Usuwanie grupy rejestracji

Użyj następującego żądania, aby usunąć grupę rejestracji o identyfikatorze myx509eg:

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

Wyświetlanie listy grup rejestracji

Użyj następującego żądania, aby pobrać listę grup rejestracji z aplikacji:

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

Odpowiedź na to żądanie wygląda następująco:

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