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 o passo a passo 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": "[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í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.

Busca difusa básica

Se você deseja realizar uma busca difusa em todos os campos disponíveis, basta fornecer um valor para a chave search. Isso utilizará 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 múltiplos campos ao mesmo tempo:

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

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

Alterando o modo de junção

Se você deseja que a API retorne apenas resultados que satisfaçam 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 email 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 aos 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, TODOS os campos irão 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 conector alvo para uma identidade social (por exemplo, dingtalk), ou o emissor para uma identidade SSO corporativa.
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 restringir ainda mais a busca de identidade com uma palavra-chave:

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

Buscar por dados personalizados

Para encontrar usuários pelos valores exatos armazenados em seus dados personalizados, passe um ou mais parâmetros de consulta customData para GET /api/users. Cada valor deve ser um objeto JSON codificado em URL:

curl \
  --get \
  --data-urlencode 'customData={"qq":114514}' \
  'http://<your-logto-endpoint>/api/users'

--data-urlencode codifica o objeto JSON para você. A URL equivalente da requisição é GET /api/users?customData=%7B%22qq%22%3A114514%7D.

nota:

Buscas por dados personalizados podem ser mais lentas quando um tenant possui um grande número de usuários. Combine customData com outro filtro seletivo, como search ou uma busca por identidade, para restringir a consulta.

O Logto compara o valor com o custom_data do usuário usando JSONB containment. Apenas as chaves incluídas no valor precisam corresponder; outras chaves nos dados personalizados do usuário são ignoradas.

Os tipos são estritos: o número 114514 não corresponde à string "114514".
Strings diferenciam maiúsculas de minúsculas.
null corresponde apenas a um JSON null explícito, não a uma chave ausente.
Objetos aninhados são correspondidos recursivamente.
Arrays são correspondidos por elemento, independentemente da ordem ou duplicatas.

Todas as chaves dentro de um objeto JSON devem corresponder (AND). Se você passar customData mais de uma vez, um usuário corresponderá quando qualquer um dos objetos corresponder (OR):

curl \
  --get \
  --data-urlencode 'customData={"qq":114514}' \
  --data-urlencode 'customData={"wechat":"logto"}' \
  'http://<your-logto-endpoint>/api/users'

O filtro de dados personalizados é sempre combinado com outros filtros usando AND, incluindo search, busca por identidade (identityType, identityProvider e identityId), excludeRoleId e excludeOrganizationId. Por exemplo, a seguinte requisição retorna usuários cujo qq é 114514 e cujo nome de usuário contém alice:

curl \
  --get \
  --data-urlencode 'customData={"qq":114514}' \
  --data-urlencode 'search.username=%alice%' \
  'http://<your-logto-endpoint>/api/users'

Os parâmetros mode, joint e isCaseSensitive afetam apenas buscas por palavra-chave e não têm efeito sobre customData.

A API retorna 400 Bad Request quando um valor de customData não é um objeto JSON válido (por exemplo, [] ou 114514), é um objeto vazio {}, ou contém um objeto ou array vazio em qualquer nível (por exemplo, {"profile":{}} ou {"tags":[]}). Nomes de parâmetros aninhados como customData.qq, customData[qq] e mode.customData também são rejeitados com 400.

Realizar uma solicitação de pesquisa​

Exemplo​

Parâmetros​

Busca difusa básica​

Especificar campos​

Alterando o modo de junção​

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

Expressão regular (RegEx)​

Sobrescrever o modo de correspondência​

Buscar por identidade externa​

Buscar por dados personalizados​