進階使用者搜尋

直接使用 Management API 以進行進階使用者搜尋條件。

執行搜尋請求

使用 GET /api/users 來搜尋使用者。請注意，這是一個 Management API，與其他 API 一樣需要驗證。互動方式請參考 與 Management API 互動。

範例

請求

curl \
  --location \
  --request GET \
  'http://<your-logto-endpoint>/api/users?search=%25alice%25'

回應

一個 User 實體陣列。

[
  {
    "id": "MgUzzDsyX0iB",
    "username": "alice_123",
    "primaryEmail": "alice@some.email.domain",
    "primaryPhone": null,
    "name": null,
    "avatar": null
    // ...
  }
]

參數

搜尋請求包含以下參數鍵：

• 搜尋關鍵字：search、search.*
• 欄位搜尋模式：mode、mode.*（預設值 'like'，可用值 ['exact', 'like', 'similar_to', 'posix']）
• 聯集模式：joint 或 jointMode（預設值 'or'，可用值 ['or', 'and']）
• 是否區分大小寫：isCaseSensitive（預設值 false）

此 API 支援 分頁。

以下將透過範例說明。所有搜尋參數皆以 URLSearchParams 建構式格式呈現。

注意:

搜尋模式預設為 like，即使用 近似字串比對 (Approximate string matching)（模糊搜尋）。

備註:

所有模糊搜尋模式僅支援每個欄位比對一個值。若需比對單一欄位多個值，請使用 "exact" 模式。詳見 精確比對與區分大小寫。

基本模糊搜尋

若要對所有可用欄位進行模糊搜尋，只需為 search 鍵提供值。底層會使用 the like operator：

new URLSearchParams([['search', '%foo%']]);

此搜尋會遍歷使用者搜尋中所有可用欄位，即 id、primaryEmail、primaryPhone、username、name。

指定欄位

若只想限定搜尋於 name 欄位，搜尋名稱中包含 foo 的使用者，只需用 . 符號指定欄位：

new URLSearchParams([['search.name', '%foo%']]);

請注意，不支援巢狀欄位，例如 search.name.first 會導致錯誤。

你也可以同時指定多個欄位：

new URLSearchParams([
  ['search.name', '%foo%'],
  ['search.primaryEmail', '%@gmail.com'],
]);

代表搜尋名稱含有 foo 或 電子郵件結尾為 @gmail.com 的使用者。

更改聯集模式

若希望 API 僅回傳同時符合所有條件的結果，請將聯集模式設為 and：

new URLSearchParams([
  ['search.name', '%foo%'],
  ['search.primaryEmail', '%@gmail.com'],
  ['joint', 'and'],
]);

代表搜尋名稱含有 foo 且 電子郵件結尾為 @gmail.com 的使用者。

精確比對與區分大小寫

假設你想搜尋名稱完全等於 "Alice" 的使用者，可以將 mode.name 設為精確比對。

new URLSearchParams([
  ['search.name', 'Alice'],
  ['mode.name', 'exact'],
]);

你會發現預設的 like 模式與指定 exact 效果相同。差異在於 exact 模式使用 = 比對，而 like 則用 like 或 ilike。理論上 = 效能更佳。

此外，在 exact 模式下，你可以傳遞多個值進行比對，系統會以 or 連接：

new URLSearchParams([
  ['search.name', 'Alice'],
  ['search.name', 'Bob'],
  ['mode.name', 'exact'],
]);

將比對名稱為 "Alice" 或 "Bob" 的使用者。

預設搜尋不區分大小寫。若需精確比對，可設為區分大小寫：

new URLSearchParams([
  ['search.name', 'Alice'],
  ['search.name', 'Bob'],
  ['mode.name', 'exact'],
  ['isCaseSensitive', 'true'],
]);

注意 isCaseSensitive 為全域設定，因此所有欄位皆會遵循此設定。

正規表示式（RegEx）

PostgreSQL 支援兩種正規表示式，similar to 與 posix。將 mode 設為 similar_to 或 posix 以正規表示式搜尋：

new URLSearchParams([
  ['search', '^T.?m Scot+$'],
  ['mode', 'posix'],
]);

注意 similar_to 模式僅適用於區分大小寫的搜尋。

比對模式覆寫

預設情況下，所有關鍵字會繼承一般搜尋的比對模式：

new URLSearchParams([
  ['search', '^T.?m Scot+$'],
  ['mode', 'posix'],
  ['search.primaryEmail', 'tom%'], // Posix 模式
  ['joint', 'and'],
]);

若要針對特定欄位覆寫：

new URLSearchParams([
  ['search', '^T.?m Scot+$'],
  ['mode', 'posix'],
  ['search.primaryEmail', 'tom%'], // Like 模式
  ['mode.primaryEmail', 'like'],
  ['search.phone', '0{3,}'], // Posix 模式
  ['joint', 'and'],
]);

依外部身分查詢

若要查找與社交或企業級單一登入 (SSO) 身分綁定的使用者，請同時傳遞以下三個查詢參數以進行精確查找：

• identityType：social 代表社交連接器身分，sso 代表企業級單一登入 (SSO) 身分。
• identityProvider：社交身分的連接器目標（例如 dingtalk），或企業級單一登入 (SSO) 身分的簽發者 (issuer)。
• identityId：外部身分提供者發出的使用者識別碼。

// 查找與 DingTalk 社交身分綁定的使用者
new URLSearchParams([
  ['identityType', 'social'],
  ['identityProvider', 'dingtalk'],
  ['identityId', 'dingtalk-open-id'],
]);

// 查找與企業級單一登入 (SSO) 身分綁定的使用者
new URLSearchParams([
  ['identityType', 'sso'],
  ['identityProvider', 'https://example.com/issuer'],
  ['identityId', 'enterprise-user-id'],
]);

身分篩選會與其他搜尋條件以 AND 邏輯結合。例如，進一步以關鍵字縮小身分查詢範圍：

new URLSearchParams([
  ['identityType', 'social'],
  ['identityProvider', 'dingtalk'],
  ['identityId', 'dingtalk-open-id'],
  ['search', '%foo%'],
]);