你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

如何使用 IoT Central REST API 管理用户和角色

项目
02/16/2024

通过 IoT Central REST API，你可以开发与 IoT Central 应用程序集成的客户端应用程序。可以使用 REST API 来管理 IoT Central 应用程序中的用户和角色。

每个 IoT Central REST API 调用都需要授权标头。有关详细信息，请参阅如何对 IoT Central REST API 调用进行身份验证和授权。

注意

对用户和角色的操作记录在 IoT Central 审核日志中。

有关 IoT Central REST API 的参考文档，请参阅 Azure IoT Central REST API 参考。

提示

可以使用 Postman 尝试本文所述的 REST API 调用。下载 IoT Central Postman 集合并将其导入 Postman。在集合中需要设置变量，例如应用子域和管理员令牌。

若要了解如何使用 IoT Central UI 管理用户和角色，请参阅在 IoT Central 应用程序中管理用户和角色。

管理角色

REST API 允许列出在 IoT Central 应用程序中定义的角色。使用以下请求从应用程序中检索角色 ID 列表：

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

对此请求的响应如下方示例所示。角色值标识与用户关联的角色 ID：

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

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

创建用户

使用以下请求在应用程序中创建用户。 ID 和电子邮件在应用程序中必须是唯一的：

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 调用使用服务主体身份验证，还可以添加服务主体用户，这很有用。有关详细信息，请参阅添加或更新服务主体用户。

更改用户的角色

使用以下请求更改分配给用户的角色。此示例使用之前检索到的构建者角色的 ID：

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 管理用户和角色，建议接下来了解如何使用 IoT Central REST API 管理组织。