ユーザー構成データを取得する

Apps API は、ユーザー構成データを取得するように設計されています。ロールやステータスに関係なく、すべてのユーザーまたは単一のユーザーの現在のユーザー構成を読み取ることができます。この出力には、システムロールとカスタムロールの両方が含まれます。

このエンドポイントは、ユーザーの一括アップロードプロセスで使用されるエンドポイントとは異なり、一括オペレーションをサポートするために必要な情報を提供します。ユーザーの一括管理プロセスを実行する方法について詳しくは、ユーザーの一括管理 API をご覧ください。

API の機能と制限事項

ユーザーデータを取得する際に、パラメータを指定して API レスポンスをニーズに合わせて調整できます。次のパラメータがサポートされています。

特定のユーザー
- ID オプション: メール、システム ID、カスタムユーザー ID。ユーザーは 1 つまたは複数の ID を指定できます。複数のユーザー ID が同じユーザーを指している場合、そのユーザーはレスポンスで 1 回だけ表される必要があります。
ページ分け
- ユーザーは、ページ設定されたセットで結果を取得して、大規模なデータセットを管理できます。API レスポンスは、取得する追加のページがあるかどうかを示す必要があります。
- API パラメータを使用すると、結果の特定のページをリクエストできます。
- ユーザーはページサイズを指定できます。デフォルトのページサイズは 100 で、最大値は 1,000 です。特定のページ番号が指定されている場合、リクエストにユーザー ID を含めることはできません。

API レスポンスには、「ステータス」フィールドを除くすべてのユーザープロファイルと構成フィールドが含まれます。API は、[ステータス] フィールドの代わりに deactivated_at フィールドを提供します。このフィールドには次の内容が含まれます。

アクティブユーザーの値がありません。
ユーザーが無効になった日時。

次の表に、API レスポンスに含まれるユーザープロフィールフィールドを示します。

表 1. ユーザープロフィールフィールドの表

Order	列の型	列数	列名	有効な値
1	Email	1	Email	Email
2	エージェント ID	1	エージェント ID	String（文字列）
3	名	1	名	String（文字列）
4	姓	1	姓	String（文字列）
5	エイリアス	1	エイリアス	String（文字列）
6	無効化日時	1	無効化日時	値なし、日付/時刻
7	場所	1	場所	位置情報の名前を表す文字列。Empty（変更なし）、Null（現在の位置情報を削除）。
8	チャットの同時接続数	1	チャットの同時接続数	1 ～ X（X は構成された値）、空
9	チャットの同時実行ステータス	1	チャットの同時実行ステータス	0、1、空
10	制限のない国際通話	1	制限のない国際通話	（True/False）
11	外部ユーザー	1	外部ユーザー	（はい/いいえ）
12	外部 SIP URI	1	外部 SIP URI	String（文字列）
13	UCaaS ユーザー名	1	UCaaS ユーザー名	String（文字列）
14	エージェント拡張機能	1	エージェント拡張機能
15	ロール	複数	Role: Role Name A Role: Role Name B Role: Role Name C など。	0、1、空
16	チーム	複数	チーム: チーム名 A、チーム: チーム名 B、チーム: チーム名 C など。	0、1、空
17	電話番号	複数	Direct Inbound Number: 1, Direct Inbound Number: 2, Direct Inbound Number: 3	電話番号が E. 164 形式
18	フィルタ	Single	フィルタ	String（文字列）
19	フィルタのタイムアウト	Single	フィルタのタイムアウト	0 ～ 1,440 の数値

制限事項

リクエストごとにサポートされるユーザー ID のタイプは 1 つのみです。
API リクエストあたりの ID の最大数は 1,000 です。
ユーザーは、1 つの API リクエストでユーザー ID とページ番号の両方をリクエストすることはできません。API は、リクエストに基づいて最大 1,000 人のすべてのユーザーを返します。

API エラーメッセージ

API は、特定のシナリオで次のエラーメッセージを返します。

ページサイズ: 「最大ページサイズのリクエストを超えました（最大値は 1,000 です）」
ページサイズ（数値入力の要件）: 「無効なページサイズのリクエストです。数値で指定する必要があります」
ユーザー ID とページネーションリクエストの組み合わせ: 「Combination of user ID and pagination request is not supported」
ユーザー ID（超過）: 「ユーザー ID の最大数を超えました（最大数は 1,000 です）」

リクエストとレスポンスの例

この例では、1 ページあたり 100 人のユーザーを含むユーザーの最初のページを取得する方法を示します。レスポンス本文には、ユーザーオブジェクトの配列が含まれます。各ユーザーオブジェクトには、ユーザー構成の詳細データが含まれています。

リクエスト:

Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/users?page=1&per_page=100

回答:

[
  {
    "email": "email",
    "agent_number": "number",
    "first_name": "first",
    "last_name": "last",
    "status": "Active",
    "location": "location",
    "max_chat_limt": 3,
    "max_chat_limit_enabled": true,
    "deleted_at": "2024-07-16T15:57:12.000Z",
    "ucaas_user_name": "username",
    "external_user": true,
    "ucaas_sip_uri": "sip uri",
    "unrestricted_international_calling": false,
    "roles": [
      { "name": "Admin" },
      { "name": "Manager" }
    ],
    "teams": [
      { "name": "name" }
    ],
    "phone_numbers": [
      "123-456-7890",
      "098-765-4321"
    ]
  },
  ...
]

この例では、メールパラメータを渡して単一のユーザーの詳細を取得する方法を示します。レスポンスの本文には、詳細なユーザー構成データを含むユーザーオブジェクトが含まれます。