IoT Central REST API を使用してユーザーとロールを管理する方法

[アーティクル]
11/15/2023

IoT Central REST API を使用して、IoT Central アプリケーションと統合するクライアントアプリケーションを開発できます。 REST API を使用すると、ご自身の IoT Central アプリケーション内でユーザーとロールを管理することができます。

すべての IoT Central REST API 呼び出しに承認ヘッダーが必要です。詳細については、「IoT Central REST API 呼び出しを認証および承認する方法」を参照してください。

Note

ユーザーとロールに関する操作は、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

この要求に対する応答は次の例のようになります。これには 3 つの組み込みロールとカスタムロールが含まれます。

{
  "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"
    }
  ]
}

Note

このコマンドは、組織レベルのカスタムロールではなく、アプリケーションに関連付けられているロールのみを表示します。

ユーザーの管理

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 を使用して組織を管理する方法」です。

Share via