Pesquisa avançada de usuários

Usando 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. Note que é uma Management API que requer autenticação como as outras. Veja Interagir com a Management API para a receita de interação.

Exemplo

Solicitaçã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": "[email protected]",
    "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ível ['exact', 'like', 'similar_to', 'posix'])
• Modo de junção: joint ou jointMode (valor padrão 'or', disponível ['or', 'and'])
• É sensível a maiúsculas e minúsculas: isCaseSensitive (valor padrão false)

Esta API tem paginação habilitada.

Vamos passar por eles através de 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 usa Correspondência aproximada de strings ("pesquisa difusa").

nota

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

Pesquisa difusa básica

Se você quiser realizar uma pesquisa difusa em todos os campos disponíveis, basta fornecer um valor para a chave search. Ele usará o operador like internamente:

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

Esta pesquisa 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 pesquisa apenas em name? Para pesquisar 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 um erro.

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

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

Significa pesquisar usuários que têm foo no nome OU cujo email termina com @gmail.com.

Alterando o modo de junção

Se você quiser 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 pesquisar usuários que têm foo no nome E cujo email termina com @gmail.com.

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

Digamos que você queira pesquisar quem tem o nome exato "Alice". Você pode definir mode.name para usar a correspondência exata.

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

Você pode achar 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 um desempenho melhor.

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

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

Isso corresponderá aos usuários com o nome "Alice" OU "Bob".

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

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

Note que isCaseSensitive é uma configuração global. Portanto, TODOS os campos seguirão isso.

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 pesquisar por expressões regulares:

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

Nota: O modo similar_to só funciona em pesquisas 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 pesquisa 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'],
]);