Поделиться через

Использование REST API IoT Central для управления устройствами

  • Статья

REST API IoT Central позволяет разрабатывать клиентские приложения, которые интегрируются с приложениями IoT Central. Rest API можно использовать для управления устройствами в приложении IoT Central.

Каждому вызову REST API IoT Central требуется заголовок авторизации. Дополнительные сведения см. в разделе Аутентификация и авторизация вызовов REST API IoT Central.

Справочную документацию по REST API IoT Central см. в справочнике по REST API Azure IoT Central.

Сведения об управлении устройствами с помощью пользовательского интерфейса IoT Central см. в статье "Управление отдельными устройствами" в приложении Azure IoT Central.

REST API устройств

С помощью REST API IoT Central вы можете:

  • Добавление устройства в приложение
  • Обновление устройства в приложении
  • получить список устройств в приложении;
  • получить устройство по идентификатору;
  • Получение учетных данных устройства
  • Удаление устройства в приложении
  • Фильтрация списка устройств в приложении

Добавить устройство

Используйте следующий запрос, чтобы создать новое устройство.

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

В следующем примере показан текст запроса, добавляющий устройство для шаблона устройства. Сведения можно получить template на странице шаблонов устройств в пользовательском интерфейсе приложения IoT Central.

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

Текст запроса содержит некоторые обязательные поля:

  • @displayName: отображаемое имя устройства.
  • @enabled: объявляет, что этот объект является интерфейсом.
  • @etag: ETag, используемый для предотвращения конфликтов в обновлениях устройства.
  • simulated: имитируется ли устройство?
  • template : определение шаблона устройства для устройства.

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Получение устройства

Используйте следующий запрос, чтобы получить сведения об устройстве из приложения:

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

Примечание.

Пользовательский интерфейс приложения IoT Central можно получить deviceId , наведите указатель мыши на устройство.

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

В следующей таблице показано, как значение состояния устройства в пользовательском интерфейсе сопоставляется со значениями, используемыми REST API для взаимодействия с устройствами:

Состояние устройства пользовательского интерфейса Примечания. Получение REST API
Ожидание утверждения Параметр автоматического утверждения отключен в группе подключений устройства, и устройство не было добавлено через пользовательский интерфейс.
Пользователь должен вручную утвердить устройство через пользовательский интерфейс, прежде чем его можно будет использовать.		 Provisioned: false
Enabled: false
Зарегистрировано Устройство было утверждено автоматически или вручную. Provisioned: false
Enabled: true
Подготовлено Устройство подготовлено и может подключиться к приложению IoT Central. Provisioned: true
Enabled: true
Заблокировано Устройство не разрешено подключаться к приложению IoT Central. Вы можете заблокировать устройство, которое находится в любом из других состояний. Provisioned: зависит от Waiting for approval/Registered/Provisioned status
Enabled: false

Получение учетных данных устройства

Используйте следующий запрос, чтобы получить учетные данные устройства из приложения:

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

обновить устройство;

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

Следующий пример текста запроса изменяет поле falseнаenabled:

{
  "enabled": false
}

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

удалить устройство;

Используйте следующий запрос для удаления устройства:

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

Выведите список устройств.

Используйте следующий запрос, чтобы получить список устройств из приложения:

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Назначение манифеста развертывания

Если вы добавляете устройство IoT Edge, вы можете использовать API для назначения манифеста развертывания IoT Edge устройству. Дополнительные сведения см. в статье "Назначение манифеста развертывания устройству".

Использование фильтров ODATA

В предварительной версии API (api-version=2022-10-31-preview) можно использовать фильтры ODATA для фильтрации и сортировки результатов, возвращаемых API устройств списка.

maxpagesize

Используйте maxpagesize для задания размера результата. Максимальный возвращаемый размер результата — 100, а размер по умолчанию — 25.

Используйте следующий запрос, чтобы получить первое устройство из приложения:

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Ответ содержит значение nextLink , которое можно использовать для получения следующей страницы результатов.

Фильтр

Используйте фильтр для создания выражений, которые фильтруют список устройств. В следующей таблице показаны операторы сравнения, которые можно использовать:

Оператор сравнения Символ Пример
Равно eq id eq 'device1' and scopes eq 'redmond'
Не равно ne Enabled ne true
Меньше или равно le id le '26whl7mure6'
Меньше lt id lt '26whl7mure6'
Больше или равно ge id ge '26whl7mure6'
Больше gt id gt '26whl7mure6'

В следующей таблице показаны операторы логики, которые можно использовать в выражениях фильтра :

Оператор логики Символ Пример
И и id eq 'device1' and enabled eq true
ИЛИ or id eq 'device1' or simulated eq false

В настоящее время фильтр работает со следующими полями устройства:

FieldName Тип Описание:
id строка Идентификатор устройства
displayName строка Отображаемое имя устройства
enabled boolean Состояние с включенным устройством
provisioned boolean Состояние подготовки устройства
simulated boolean Состояние имитации устройства
template строка Идентификатор шаблона устройства
scopes строка Идентификатор организации

Фильтрация поддерживаемых функций:

В настоящее время единственной поддерживаемой функцией фильтра для списков устройств является contains функция:

filter=contains(displayName, 'device1')

В следующем примере показано, как получить все устройства, где отображаемое имя содержит строку thermostat:

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Используйте orderby для сортировки результатов. В настоящее время orderby позволяет выполнять сортировку только по displayName. По умолчанию порядок сортировки выполняется по возрастанию. Используйте desc для сортировки в порядке убывания, например:

orderby=displayName
orderby=displayName desc

В следующем примере показано, как получить все шаблоны устройств, в которых результат сортируется по displayName :

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Можно также объединить два или более фильтров.

В следующем примере показано, как получить первые три устройства, где отображаемое имя содержит строку Thermostat.

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Группы устройств

Группы устройств можно создавать в приложении IoT Central для мониторинга статистических данных, использования с заданиями и управления доступом. Группы устройств определяются фильтром, который выбирает устройства для добавления в группу. Группы устройств можно создавать на портале IoT Central или с помощью API.

Добавление группы устройств

Используйте следующий запрос, чтобы создать новую группу устройств.

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

При создании группы устройств определяется filter , который выбирает устройства для добавления в группу. Идентифицирует filter шаблон устройства и соответствующие свойства. В следующем примере создается группа устройств, содержащая все устройства, связанные с шаблоном dtmi:modelDefinition:dtdlv2, где provisioned находится trueсвойство.

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

Текст запроса содержит некоторые обязательные поля:

  • @displayName: отображаемое имя группы устройств.
  • @filter: запрос, определяющий, какие устройства должны находиться в этой группе.
  • @etag: ETag, используемый для предотвращения конфликтов в обновлениях устройства.
  • description: краткая сводка по группе устройств.

Поле организации используется только в том случае, если приложение имеет определенную иерархию организации. Дополнительные сведения о организациях см. в статье "Управление организациями IoT Central".

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Получение группы устройств

Используйте следующий запрос, чтобы получить сведения о группе устройств из приложения:

GET https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31
  • deviceGroupId — уникальный идентификатор для группы устройств.

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Обновление группы устройств

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

Пример текста запроса выглядит следующим образом, который обновляет displayName группу устройств:

{
  "displayName": "New group name"
}

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Удаление группы устройств

Используйте следующий запрос для удаления группы устройств:

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

Вывод списка групп устройств

Используйте следующий запрос, чтобы получить список групп устройств из приложения:

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Группы регистрации

Группы регистрации используются для управления параметрами проверки подлинности устройства в приложении IoT Central. Дополнительные сведения см. в разделе "Основные понятия проверки подлинности устройств" в IoT Central.

Сведения о создании групп регистрации и управлении ими в пользовательском интерфейсе см. в статье "Как подключить устройства с сертификатами X.509 к приложению IoT Central".

Создание группы регистрации

При создании группы регистрации для устройств, использующих сертификаты X.509, сначала необходимо передать корневой или промежуточный сертификат в приложение IoT Central.

Создание корневого сертификата и сертификата устройства

В этом разделе описано, как создать сертификаты X.509, необходимые для подключения устройства к IoT Central.

Предупреждение

Такой способ создания сертификатов X.509 предназначен только для тестирования. Для рабочей среды следует использовать официальный, безопасный механизм создания сертификатов.

  1. Перейдите к скрипту генератора сертификатов из скачанного пакета SDK Интернета вещей Microsoft Azure для Node.js. Установите необходимые пакеты.

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

  2. Создайте корневой сертификат, а затем выберете сертификат устройства, выполнив следующий сценарий:

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

    Совет

    Код устройства может содержать только буквы, цифры и символ -.

Эти команды создают следующие корневые сертификаты и сертификаты устройства:

filename содержание
mytestrootcert_cert.pem Общедоступная часть корневого сертификата X.509
mytestrootcert_key.pem Закрытый ключ для корневого сертификата X.509
mytestrootcert_fullchain.pem Всю цепочку ключей для корневого сертификата X.509.
mytestrootcert.pfx PFX-файл для корневого сертификата X.509.
sampleDevice01_cert.pem Общедоступная часть сертификата X.509 устройства
sampleDevice01_key.pem Закрытый ключ для сертификата X.509 устройства
sampleDevice01_fullchain.pem Весь цепочка ключей для сертификата X.509 устройства.
sampleDevice01.pfx PFX-файл для сертификата X.509 устройства.

Запишите место расположения этих файлов. Он понадобится вам позже.

Создание закодированной версии корневого сертификата в кодировке Base-64

В папке на локальном компьютере, содержащей созданные сертификаты, создайте файл с именем convert.js и добавьте следующее содержимое JavaScript:

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

Выполните следующую команду, чтобы создать версию сертификата в кодировке base-64:

node convert.js mytestrootcert_cert.pem

Запишите версию сертификата в кодировке base-64. Он понадобится вам позже.

Добавление группы регистрации X.509

Используйте следующий запрос, чтобы создать новую группу регистрации с myx509eg идентификатором:

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

В следующем примере показан текст запроса, который добавляет новую группу регистрации X.509:

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

Текст запроса содержит некоторые обязательные поля:

  • @displayName: отображаемое имя группы регистрации.
  • @enabled: разрешено ли устройствам, использующим группу, подключаться к IoT Central.
  • @type: тип устройств, которые подключаются через группу или iot iotEdge.
  • attestation: механизм аттестации для группы регистрации либо symmetricKey x509.

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Добавление сертификата X.509 в группу регистрации

Используйте следующий запрос, чтобы задать основной сертификат X.509 группы регистрации myx509eg:

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

Используйте этот запрос, чтобы добавить в группу регистрации первичный или вторичный сертификат X.509.

В следующем примере показан текст запроса, который добавляет сертификат X.509 в группу регистрации:

{
  "verified": false,
  "certificate": "<base64-certificate>"
}
  • сертификат — версия сертификата base-64, о который вы записали ранее.
  • проверено — true если вы подтверждаете, что сертификат действителен, false если необходимо подтвердить допустимость сертификата.

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Создание кода проверки для сертификата X.509

Используйте следующий запрос, чтобы создать код проверки для первичного или вторичного сертификата X.509 группы регистрации.

Если задано verified false значение в предыдущем запросе, используйте следующий запрос, чтобы создать код проверки для первичного сертификата X.509 в myx509eg группе регистрации:

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Запишите код проверки, его необходимо выполнить на следующем шаге.

Создание сертификата проверки

Используйте следующую команду, чтобы создать сертификат проверки из кода проверки на предыдущем шаге:

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

Выполните следующую команду, чтобы создать версию сертификата в кодировке Base-64:

node convert.js verification_cert.pem

Запишите версию сертификата в кодировке base-64. Он понадобится вам позже.

Проверка сертификата X.509 группы регистрации

Используйте следующий запрос, чтобы проверить основной сертификат myx509eg X.509 группы регистрации, предоставив сертификат с подписанным кодом проверки:

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

В следующем примере показан текст запроса, который проверяет сертификат X.509:

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

Получение сертификата X.509 группы регистрации

Используйте следующий запрос, чтобы получить сведения о сертификате X.509 группы регистрации из приложения:

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Удаление сертификата X.509 из группы регистрации

Используйте следующий запрос, чтобы удалить первичный сертификат X.509 из группы регистрации с идентификатором myx509eg:

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

Получение группы регистрации

Используйте следующий запрос, чтобы получить сведения о группе регистрации с mysymmetric идентификатором:

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Обновление группы регистрации

Используйте следующий запрос, чтобы обновить группу регистрации.

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

В следующем примере показан текст запроса, который обновляет отображаемое имя группы регистрации:

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Удаление группы регистрации

Используйте следующий запрос, чтобы удалить группу регистрации с идентификатором myx509eg:

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

Перечисление групп регистрации

Используйте следующий запрос, чтобы получить список групп регистрации из приложения:

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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