高级用户搜索

直接使用 Management API 实现高级用户搜索条件。

执行搜索请求

使用 GET /api/users 进行用户搜索。请注意，这也是一个需要认证的 Management 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，即使用近似字符串匹配（“模糊搜索”）。

备注:

所有模糊搜索模式每个字段仅支持匹配一个值。如果你需要为单个字段匹配多个值，应使用 "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) 身份的发行者。
• identityId：外部身份提供方颁发的用户标识符。

// 查找与钉钉社交身份关联的用户
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%'],
]);