Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

取得使用者設定資料

Apps API /apps/api/v1/users 端點會擷取使用者設定資料。您可以讀取所有使用者或單一使用者的目前設定，無論其角色或帳戶是否啟用。這項輸出內容包含系統和自訂角色。如要僅擷取活躍代理的即時狀態和上線狀態資料，請參閱 Manager API 代理端點。

這個端點與大量使用者上傳程序中使用的端點不同，可提供支援大量作業所需的資訊。如要進一步瞭解如何執行大量使用者管理程序，請參閱「大量使用者管理 API」。

API 功能與限制

擷取使用者資料時，您可以加入參數，根據需求自訂 API 回應。支援下列參數：

特定使用者
- ID 選項：電子郵件、系統 ID 或自訂使用者 ID。使用者可以指定一或多個 ID。如果有多個使用者 ID 指向同一位使用者，則該使用者在回應中應只出現一次。
分頁
- 使用者可以分頁擷取結果，管理大型資料集。API 回應應指出是否有其他頁面可供擷取。
- API 參數可讓使用者要求特定結果頁面。
- 使用者可以指定頁面大小。預設頁面大小為 100，上限為 1,000。如果提供特定頁碼，要求中就不能包含使用者 ID。

API 回應包含所有使用者個人資料和設定欄位，但「Status」欄位除外。API 將提供 deactivated_at 欄位，而非「Status」欄位。這個欄位會包含：

活躍使用者沒有價值。
停用使用者的日期和時間。

下表列出 API 回應中包含的使用者個人資料欄位：

表 1. 使用者個人資料欄位表格

訂單	資料欄類型	欄數	資料欄名稱	有效值
1	電子郵件	1	電子郵件	電子郵件
2	Agent ID	1	Agent ID	String
3	名字	1	名字	String
4	姓氏	1	姓氏	String
5	Alias	1	Alias	String
6	停用時間	1	停用時間	無值、日期/時間
7	Location	1	Location	地點名稱字串、空白 (不變更)、Null (移除目前地點)。
8	Chat 並行	1	Chat 並行	1 到 X (X 為設定值)，空白
9	即時通訊並行狀態	1	即時通訊並行狀態	0、1、空白
10	不限國際電話撥號	1	不限國際電話撥號	(True/False)
11	外部使用者	1	外部使用者	(Yes/No)
12	外部 SIP URI	1	外部 SIP URI	String
13	UCaaS 使用者名稱	1	UCaaS 使用者名稱	String
14	代理擴充功能	1	代理擴充功能
15	角色	多個	角色：角色名稱 A 角色：角色名稱 B 角色：角色名稱 C 等。	0、1、空白
16	團隊	多個	團隊：團隊名稱 A，團隊：團隊名稱 B Team: Team Name C etc.	0、1、空白
17	電話號碼	多個	直撥來電號碼：1，直接來電號碼：2， Direct Inbound Number: 3	電話號碼採用 E. 164 格式
18	篩選	單一	篩選器	String
19	篩選器逾時	單一	篩選器逾時	介於 0 至 1,440 之間的數值

限制

每項要求僅支援一種使用者 ID。
每項 API 要求的 ID 數量上限為 1,000 個。
使用者無法在單一 API 要求中同時提供使用者 ID 和頁碼要求。API 會根據要求傳回所有使用者，最多 1,000 位。

API 錯誤訊息

在特定情況下，API 會提供下列錯誤訊息：

頁面大小：「超出頁面大小要求上限 (上限為 1,000)」
頁面大小 (數字輸入要求)：「Invalid page size request; must be a numeric value」
合併使用者 ID 和分頁要求：「不支援合併使用者 ID 和分頁要求」
使用者 ID (超出上限)：「超出使用者 ID 數量上限 (上限為 1,000 個)」

要求和回應範例

這個範例示範如何擷取第一頁的使用者，每頁有 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"
    ]
  },
  ...
]

這個範例示範如何傳遞電子郵件參數，擷取單一使用者的詳細資料。回應主體包含使用者物件，其中含有詳細的使用者設定資料。