Pular para o conteúdo principal

Pesquisa avançada de usuários

Utilize diretamente a Management API para aproveitar condições avançadas de pesquisa de usuários.

Realizar uma solicitação de pesquisa​

Use GET /api/users para pesquisar usuários. Observe que é uma Management API que requer autenticação como as demais. Veja Interaja com a Management API para a receita de interação.

Exemplo​

Requisição

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

Resposta

Um array de entidades User.

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

Parâmetros​

Uma solicitação de pesquisa consiste nas seguintes chaves de parâmetro:

  • Palavras-chave de pesquisa: search, search.*
  • Modo de pesquisa para campos: mode, mode.* (valor padrão 'like', disponíveis ['exact', 'like', 'similar_to', 'posix'])
  • Modo de junção: joint ou jointMode (valor padrão 'or', disponíveis ['or', 'and'])
  • É sensível a maiúsculas e minúsculas: isCaseSensitive (valor padrão false)

Esta API possui paginação habilitada.

Vamos passar por eles com alguns exemplos. Todos os parâmetros de pesquisa serão formatados como um construtor de URLSearchParams.

atenção:

O modo de pesquisa é definido como like por padrão, que utiliza Correspondência aproximada de strings ("busca difusa").

nota:

Todos os modos de busca difusa suportam apenas a correspondência de um valor por campo. Se você precisar corresponder múltiplos valores para um único campo, deve usar o modo "exact". Veja Correspondência exata e sensibilidade a maiúsculas e minúsculas para detalhes.

Se você deseja realizar uma busca difusa em todos os campos disponíveis, basta fornecer um valor para a chave search. Será utilizado o operador like internamente:

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

Esta busca irá iterar sobre todos os campos disponíveis em uma pesquisa de usuário, ou seja, id, primaryEmail, primaryPhone, username, name.

Especificar campos​

E se você quiser limitar a busca apenas ao campo name? Para buscar alguém que inclua foo no nome, basta usar o símbolo . para especificar o campo:

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

Lembre-se de que campos aninhados não são suportados, por exemplo, search.name.first resultará em erro.

Você também pode especificar vários campos ao mesmo tempo:

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

Significa buscar usuários que tenham foo no nome OU cujo e-mail termine com @gmail.com.

Alterando o modo de junção​

Se você deseja que a API retorne apenas o resultado que satisfaça TODAS as condições, defina o modo de junção como and:

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

Significa buscar usuários que tenham foo no nome E cujo e-mail termine com @gmail.com.

Correspondência exata e sensibilidade a maiúsculas e minúsculas​

Suponha que você queira buscar quem tem o nome exatamente "Alice". Você pode definir mode.name para usar correspondência exata.

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

Você pode perceber que tem o mesmo efeito ao usar o modo like (padrão) vs. especificar exact. Uma diferença é que o modo exact usa = para comparar enquanto like usa like ou ilike. Teoricamente, = deve ter melhor desempenho.

Além disso, no modo exact, você pode passar múltiplos valores para correspondência, e eles serão conectados com or:

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

Irá corresponder usuários com nome "Alice" OU "Bob".

Por padrão, a busca não diferencia maiúsculas de minúsculas. Para ser mais preciso, defina a busca como sensível a maiúsculas e minúsculas:

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

Observe que isCaseSensitive é uma configuração global. Assim, TODO campo irá segui-la.

Expressão regular (RegEx)​

O PostgreSQL suporta dois tipos de expressões regulares, similar to e posix. Defina mode como similar_to ou posix para buscar por expressões regulares:

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

Observação: O modo similar_to só funciona em buscas sensíveis a maiúsculas e minúsculas.

Sobrescrever o modo de correspondência​

Por padrão, todas as palavras-chave herdarão o modo de correspondência da busca geral:

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

Para sobrescrever para um campo específico:

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

Buscar por identidade externa​

Para encontrar o usuário vinculado a uma identidade social ou SSO corporativo, passe os três parâmetros de consulta a seguir juntos para uma busca exata:

  • identityType: social para uma identidade de conector social, ou sso para uma identidade de SSO corporativo.
  • identityProvider: o destino do conector para uma identidade social (por exemplo, dingtalk), ou o emissor para uma identidade de SSO corporativo.
  • identityId: o identificador do usuário emitido pelo provedor de identidade externo.
// Encontrar o usuário vinculado a uma identidade social do DingTalk
new URLSearchParams([
  ['identityType', 'social'],
  ['identityProvider', 'dingtalk'],
  ['identityId', 'dingtalk-open-id'],
]);
// Encontrar o usuário vinculado a uma identidade SSO corporativa
new URLSearchParams([
  ['identityType', 'sso'],
  ['identityProvider', 'https://example.com/issuer'],
  ['identityId', 'enterprise-user-id'],
]);

O filtro de identidade é combinado com outros filtros de pesquisa usando lógica AND. Por exemplo, para refinar ainda mais a busca de identidade com uma palavra-chave:

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