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

文章
05/12/2024

IoT Central REST API 可讓您開發與 IoT Central 應用程式整合的用戶端應用程式。您可以在 IoT Central 應用程式中使用 REST API 來管理使用者和角色。

每個 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 應用程式中定義的角色。使用下列要求，從您的應用程式擷取角色識別碼清單：

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 管理使用者和角色，建議的下一個步驟請參考如何使用 IoT Central REST API 來管理組織。

分享方式：