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

如何对 IoT Central REST API 调用进行身份验证和授权

项目
03/06/2024

通过 IoT Central REST API，你可以开发与 IoT Central 应用程序集成的客户端应用程序。使用 REST API 可以处理 IoT Central 应用程序中的资源，例如设备模板、设备、作业、用户和角色。

每个 IoT Central REST API 调用都需要一个授权头，IoT Central 使用该授权头来确定调用方的标识，以及在应用程序中为该调用方授予的权限。

本文介绍可在授权头中使用的令牌类型，以及如何获取这些令牌。建议使用服务主体进行 IoT Central REST API 访问管理。

令牌类型

若要通过 REST API 访问 IoT Central 应用程序，可以使用：

Microsoft Entra 持有者令牌。持有者令牌与 Microsoft Entra 用户帐户或服务主体相关联。该令牌为调用方授予用户或服务主体在 IoT Central 应用程序中所拥有的相同权限。
IoT Central API 令牌。 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

重要

即使使用的是 Cloud Shell，也需要运行 az login 命令。

上述命令的 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 UI 或 REST API 调用。与根组织关联的管理员以及被分配了正确角色的用户可以创建 API 令牌。

提示

对 API 令牌的创建和删除操作记录在审核日志中。

在 IoT Central UI 中：

导航到“权限”>“API 令牌”。
选择“+ 新建”或“创建 API 令牌”。
输入令牌的名称并选择一个角色和组织。
选择生成。
IoT Central 将显示如以下示例所示的令牌：

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

API 令牌只会在此屏幕中显示一次，如果丢失此令牌，则需要生成新令牌。

API 令牌的有效期大约为一年。可以在 IoT Central 应用程序中为内置角色和自定义角色生成令牌。在创建 API 令牌时选择的组织决定了 API 可以访问哪些设备。在将任何组织添加到应用程序之前创建的任何 API 令牌都与根组织相关联。

如果需要撤销访问权限，可以在 IoT Central UI 中删除 API 令牌。

使用 REST API：

使用 REST API 从应用程序中检索角色 ID 列表：

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 令牌。例如，若要为操作员角色创建名 operator-token 为的 API 令牌，请运行以下命令：

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 令牌

若要在发出 REST API 调用时使用 API 令牌，授权头应如以下示例所示：

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