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

發行項
02/08/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 應用程式中定義的角色。使用下列要求，從您的應用程式擷取角色標識碼清單：

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 來管理組織。