如何驗證和授權 IoT Central REST API 呼叫

發行項
05/11/2024

IoT Central REST API 可讓您開發與 IoT Central 應用程式整合的用戶端應用程式。使用 REST API 處理 IoT Central 應用程式中的資源，例如裝置範本、裝置、工作、使用者和角色。

每個 IoT Central REST API 呼叫都需要授權標頭，供 IoT Central 判斷呼叫者的身分，以及呼叫者在應用程式內獲得授與的權限。

本文描述您可在授權標頭中使用的權杖類型，以及取得權杖的方法。 Srvice 主體是存取 IoT Central REST API 存取管理的建議方法。

權杖類型

若要透過 REST API 存取 IoT Central 應用程式，請使用：

Azure Active Directory 持有人權杖。持有人權杖與 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 從應用程式中擷取角色識別碼清單：

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

下一步

現在您了解如何授權 REST API 呼叫了，建議您接著了解如何使用 IoT Central REST API 查詢裝置。

共用方式為