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

Статья
02/08/2024

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

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

Примечание.

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

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

Совет

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

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

Управление ролями

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

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

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

{
  "value": [
    {
      "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
      "displayName": "Administrator"
    },
    {
      "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
      "displayName": "Operator"
    },
    {
      "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
      "displayName": "Builder"
    },
    {
      "id": "16f8533f-6b82-478f-8ba8-7e676b541b1b",
      "displayName": "Example custom role"
    }
  ]
}

Примечание.

Эта команда показывает только роли, связанные с приложением, а не настраиваемую роль уровня организации.

Управление пользователями

REST API предоставляет следующие возможности.

Вывод списка пользователей в приложении.
Получение сведений об отдельном пользователе.
Создание пользователя
Изменение пользователя.
Удаление пользователя

Список пользователей

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

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

Ответ на этот запрос выглядит, как показано в примере ниже. Значения ролей указывают идентификатор роли, с которой связан пользователь:

{
  "value": [
    {
      "id": "91907508-04fe-4349-91b5-b872f3055a95",
      "type": "email",
      "roles": [
        {
          "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
        }
      ],
      "email": "user1@contoso.com"
    },
    {
      "id": "dc1c916b-a652-49ea-b128-7c465a54c759",
      "type": "email",
      "roles": [
        {
          "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
        }
      ],
      "email": "user2@contoso.com"
    },
    {
      "id": "3ab9375e-d2d9-42da-b419-6ae86a938321",
      "type": "email",
      "roles": [
        {
          "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
        }
      ],
      "email": "user3@contoso.com"
    },
    {
      "id": "fc5a250b-83fb-433d-892c-e0a144f68c2b",
      "type": "email",
      "roles": [
        {
          "role": "16f8533f-6b82-478f-8ba8-7e676b541b1b"
        }
      ],
      "email": "user4@contoso.com"
    }
  ]
}

Получение пользователя

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

GET https://{your app subdomain}.azureiotcentral.com/api/users/dc1c916b-a652-49ea-b128-7c465a54c759?api-version=2022-07-31

Ответ на этот запрос выглядит, как показано в примере ниже. Значение роли указывает идентификатор роли, с которой связан пользователь:

{
  "id": "dc1c916b-a652-49ea-b128-7c465a54c759",
  "type": "email",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "email": "user2@contoso.com"
}

Создание пользователя

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

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

В следующем тексте запроса role является значением для роли оператора, полученным ранее:

{
  "id": "user-001",
  "type": "email",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "email": "user5@contoso.com"
}

Ответ на этот запрос выглядит, как показано в примере ниже. Значение роли указывает, с какой ролью связан пользователь:

{
  "id": "user-001",
  "type": "email",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "email": "user5@contoso.com"
}

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

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

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

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

Текст запроса. Значение для роли построителя, полученное ранее:

{
  "roles": [
    {
      "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

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

{
  "id": "user-001",
  "type": "email",
  "roles": [
    {
      "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ],
  "email": "user5@contoso.com"
}

Удаление пользователя

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

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

Следующие шаги

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

Share via