取得使用者設定資料

Apps API 的用途是擷取使用者設定資料。您可以讀取所有使用者或單一使用者的目前使用者設定，不論對方的角色或狀態為何，都是如此。這項輸出內容包含系統和自訂角色。

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

API 功能與限制

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

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

API 回應會包含所有使用者設定檔和設定欄位，但「狀態」欄位除外。API 會提供 deactivated_at 欄位，而非「狀態」欄位。這個欄位會包含：

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

下表列出 API 回應中會包含的使用者設定檔欄位：

表 1. 使用者設定檔欄位表格

Order	資料欄類型	欄數	資料欄名稱	有效值
1	電子郵件地址	1	電子郵件地址	電子郵件地址
2	服務專員 ID	1	服務專員 ID	String
3	名字	1	名字	String
4	姓氏	1	姓氏	String
5	別名	1	別名	String
6	停用時間	1	停用時間	沒有值，日期/時間
7	位置	1	位置	位置名稱字串、空白 (不變更)、空值 (移除目前位置)。
8	即時通訊並行數	1	即時通訊並行數	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, 團隊：團隊名稱 C 等等。	0、1、空白
17	電話號碼	多個	直接撥入號碼：1, 直接撥入號碼：2, 直撥電話號碼：3	電話號碼採用 164 格式
18	篩選器	單一	篩選器	String
19	篩選器逾時	單一	篩選器逾時	介於 0 至 1,440 之間的數值

限制

每個要求僅支援一種使用者 ID。
每個 API 要求最多可包含 1,000 個 ID。
使用者無法在單一 API 要求中同時提供使用者 ID 和頁碼要求。API 會根據要求傳回所有使用者，最多 1,000 人。

API 錯誤訊息

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

頁面大小：「Exceeded maximum page size request (1,000 is the maximum)」(超出頁面大小要求上限 (上限為 1,000))
頁面大小 (須輸入數字)：「Invalid page size request; must be a numeric value」(頁面大小要求無效，必須是數值)
合併使用者 ID 和分頁要求：「Combination of user ID and pagination request is not supported」(不支援合併使用者 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"
    ]
  },
  ...
]

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