Аутентификация и авторизация вызовов REST API IoT Central

Статья
03/01/2024

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

Каждому вызову REST API IoT Central требуется заголовок Authorization, на основе которого IoT Central определяет удостоверение вызывающего объекта и разрешения, которые предоставляются ему в приложении.

В этой статье рассматриваются типы маркеров (токенов), которые можно использовать в заголовке авторизации, а также способы их получения. Субъекты-службы — это рекомендуемый подход для управления доступом к REST API IoT Central.

Типы маркеров

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

Токен носителя Microsoft Entra. Маркер носителя связан с учетной записью пользователя Или субъектом-службой Microsoft Entra. Этот маркер предоставляет вызывающей стороне те же разрешения, что есть у пользователя или субъекта-службы в приложении IoT Central.
Маркер API IoT Central. Маркер API связан с ролью в приложении IoT Central.

Используйте маркер носителя, связанный с учетной записью пользователя, во время разработки и тестирования автоматизации и сценариев, использующих REST API. Используйте маркер носителя, связанный с субъектом-службой для автоматизации и сценариев рабочей среды. Используйте маркер носителя в предпочтении маркера API, чтобы снизить риск утечки и проблем при истечении срока действия маркеров.

Дополнительные сведения о пользователях и ролях в IoT Central см. в статье Управление пользователями и ролями в приложении IoT Central.

Получение маркера носителя

Чтобы получить маркер носителя для учетной записи пользователя Microsoft Entra, используйте следующие команды Azure CLI:

az login
az account get-access-token --resource https://apps.azureiotcentral.com

Внимание

Команда az login необходима, даже если вы используете Cloud Shell.

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

{
  "accessToken": "eyJ0eX...fNQ",
  "expiresOn": "2021-03-22 11:11:16.072222",
  "subscription": "{your subscription id}",
  "tenant": "{your tenant id}",
  "tokenType": "Bearer"
}

Маркер носителя действителен приблизительно час, после чего необходимо создать новый.

Сведения о получении токена носителя для субъекта-службы см. в разделе Проверка подлинности субъекта-службы.

Получение токена API

Получить маркер API можно в пользовательском интерфейсе IoT Central или путем вызова REST API. Администратор istrator, связанные с корневой организацией и пользователями, назначенными правильной роли, могут создавать маркеры API.

Совет

Операции создания и удаления маркеров API записываются в журнал аудита.

В пользовательском интерфейсе IoT Central:

Перейдите к маркерам> API разрешений.
Выберите +Создать или создайте маркер API.
Введите имя маркера и выберите роль и организацию.
Выберите Создать.
В IoT Central отобразится маркер, который выглядит примерно следующим образом:

SharedAccessSignature sr=5782ed70...&sig=dvZZE...&skn=operator-token&se=1647948035850

Вы увидите маркер API только на этом экране, поэтому если вы его потеряете, то потребуется создать новый.

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

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

С помощью REST API:

С помощью REST API получите список идентификаторов ролей из приложения:

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

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

{
  "value": [
    {
      "displayName": "Administrator",
      "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
    },
    {
      "displayName": "Operator",
      "id": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    },
    {
      "displayName": "Builder",
      "id": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

С помощью REST API создайте маркер API для роли. Например, чтобы создать маркер API operator-token для роли оператора:
```
PUT https://{your app subdomain}.azureiotcentral.com/api/apiToken/operator-token?api-version=2022-07-31
```
Текст запроса:
```
{
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ]
}
```
Ответ на предыдущую команду выглядит, как в следующем фрагменте JSON:
```
{
  "expiry": "2022-03-22T12:01:27.889Z",
  "id": "operator-token",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "token": "SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889"
}
```
Вы увидите маркер API только в этом ответе, поэтому если вы его потеряете, то потребуется создать новый.

С помощью REST API можно получить список маркеров API в приложении и удалить их.

Использование маркера носителя

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

Authorization: Bearer eyJ0eX...fNQ

Использование маркера API

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

Authorization: SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889