Pesquisa de membros da guilda

Pesquise membros da guilda por nome, cargo e informações de entrada. Cada correspondência é um objeto resultado de pesquisa de membro da guilda.

Uma guilda que um operador marcou como indisponível retorna 403 MISSING_ACCESS antes que a rota seja executada.

Os resultados da pesquisa podem estar desatualizados

Os resultados podem ter um atraso em relação às alterações de membros e podem incluir membros que já saíram. Use Obter membro da guilda quando a associação atual for importante.

Tipos de origem de entrada

O Decoding Chat registra o motivo pelo qual uma associação existe no momento em que cria essa associação. A API HTTP não define nenhuma operação que reescreva o valor.

Valor	Nome	Descrição
0	CREATOR	O membro criou a guilda
1	INSTANT_INVITE	O membro entrou através de um convite comum
2	VANITY_URL	O membro entrou através da URL personalizada da guilda
3	BOT_INVITE	A conta foi adicionada através de um convite de bot
4	ADMIN_FORCE_ADD	O administrador da instância adicionou o membro diretamente
6	DISCOVERY	O membro entrou através da descoberta de guildas

O valor 5 não é atribuído.

Objeto de resultado de pesquisa de membro da guilda

Uma associação correspondente. Os campos da conta aparecem no nível superior, em vez de sob user como no objeto de membro da guilda.

Estrutura

Campo	Tipo	Descrição
id1	string	O identificador do resultado da pesquisa, um por associação
guild_id	snowflake	O ID da guilda à qual a associação pertence
user_id	snowflake	O ID da conta à qual a associação pertence
username	string	O nome de usuário da conta
discriminator2	string	O discriminador de quatro dígitos da conta
global_name	?string	O nome de exibição global da conta, ou null quando nenhum está definido
nickname3	?string	O apelido do membro nesta guilda, ou null quando nenhum está definido
role_ids3 4	array[snowflake]	Os IDs dos cargos atribuídos ao membro
joined_at5	integer	O momento em que a conta se tornou membro, em segundos Unix
supplemental6	objeto informações suplementares de pesquisa de membro da guilda	Os metadados de entrada que apenas esta pesquisa expõe
is_bot	boolean	Se a conta é um bot

¹ O ID da guilda e o ID do usuário unidos por um sublinhado, como {guild_id}_{user_id}. Nenhuma outra operação o aceita como identificador

² Preenchido à esquerda com zeros para quatro dígitos

³ O objeto de membro da guilda nomeia esses campos como nick e roles, portanto um cliente reutilizando um renderizador de membro deve mapeá-los

⁴ O cargo everyone nunca está presente

⁵ A mesma unidade que os filtros joined_at_gte e joined_at_lte. O objeto de membro da guilda relata o mesmo momento como um timestamp ISO 8601

⁶ Sempre presente, com todos os campos dentro dele null a menos que o chamador possua MANAGE_GUILD

Exemplo

{
  "id": "1489002177550843904_1489002177550843906",
  "guild_id": "1489002177550843904",
  "user_id": "1489002177550843906",
  "username": "ada",
  "discriminator": "0042",
  "global_name": "Ada",
  "nickname": null,
  "role_ids": ["1489002177550843910"],
  "joined_at": 1755158400,
  "supplemental": {"join_source_type": 1, "source_invite_code": "aBc123", "inviter_id": "1489002177550843905"},
  "is_bot": false
}

Os resultados da pesquisa são representações parciais do membro

O resultado não tem avatar, banner, accent_color, mute, deaf, communication_disabled_until, profile_flags ou mention_flags. Leia a associação completa através de Obter membro da guilda.

Objeto de informações suplementares de pesquisa de membro da guilda

Um objeto de informações suplementares de pesquisa de membro da guilda tem a origem de entrada que o objeto de membro da guilda nunca expõe. Apenas um chamador que possui MANAGE_GUILD recebe seus valores.

Estrutura

Campo	Tipo	Descrição
join_source_type?1 2	?integer	O tipo de origem de entrada registrado para a associação
source_invite_code1	?string	O código de convite pelo qual o membro entrou
inviter_id1	?snowflake	O ID da conta que criou o convite pelo qual o membro entrou

¹ Null tanto quando o chamador não possui MANAGE_GUILD quanto quando a associação não registrou nenhum valor, portanto um null não distingue os dois

² Sempre emitido, então trate um campo ausente e um campo null da mesma forma

Objeto de resposta de pesquisa de membro da guilda

Uma pesquisa retorna este envelope. Todos os campos estão sempre presentes.

Estrutura

Campo	Tipo	Descrição
guild_id	snowflake	O ID da guilda na qual a pesquisa foi executada
members	array[objeto resultado de pesquisa de membro da guilda]	A página correspondente na ordem solicitada
page_result_count1	integer	O número de resultados em members
total_result_count2	integer	O número total de associações indexadas que correspondem aos filtros
indexing3	boolean	Se o índice de membros da guilda está sendo construído

¹ O comprimento de members

² A contagem de documentos correspondentes que o backend de pesquisa configurado relata

³ Um valor verdadeiro (true) sempre vem com um array members vazio e ambas as contagens em zero

Uma instância Elasticsearch relata o verdadeiro total_result_count. Uma instância Meilisearch relata uma estimativa que atinge o limite de 10000. Em uma guilda muito grande, esse valor pode ser menor que o número verdadeiro de correspondências.

Exemplo

{
  "guild_id": "1489002177550843904",
  "members": [],
  "page_result_count": 0,
  "total_result_count": 0,
  "indexing": true
}

Pesquisar membros da guilda

POST/v1/guilds/{guild_id}/members-searchBot

Pesquisa no índice de membros da guilda. Retorna um objeto de resposta de pesquisa de membro da guilda em caso de sucesso. Requer associação à guilda.

Limitações

• O chamador também deve possuir pelo menos um dos seguintes: MANAGE_GUILD, MANAGE_ROLES, MANAGE_NICKNAMES, BAN_MEMBERS, MODERATE_MEMBERS, ou KICK_MEMBERS.
• Cada bit qualificador exceto MANAGE_NICKNAMES é uma das permissões elevadas. Em uma guilda cujo nível MFA é elevado, um chamador que não seja o dono da guilda, que possua um desses bits elevados e não tenha nenhum autenticador cadastrado, recebe 400 TWO_FACTOR_REQUIRED. Um chamador que se qualifica apenas através de MANAGE_NICKNAMES nunca recebe esse código.
• Um não-membro de uma guilda existente recebe o mesmo 403 MISSING_PERMISSIONS que um membro que não possui nenhum dos bits qualificadores, portanto, um chamador não pode distinguir os dois.

Uma guilda que não existe retorna 404 UNKNOWN_GUILD.

Listar membros da guilda precisa apenas da associação e retorna o objeto completo de membro para todos. As permissões acima controlam os filtros, a ordenação, a paginação profunda e a informação suplementar de origem de entrada.

Parâmetros de rota

Campo	Tipo	Descrição
guild_id	snowflake	O ID da guilda

Corpo JSON

Cada campo é opcional e um filtro omitido não é aplicado. A rota lê um corpo omitido, vazio ou contendo apenas espaços em branco como um objeto vazio. Um corpo que não é um JSON válido retorna 400 INVALID_FORM_BODY com o código de validação INVALID_FORMAT no caminho body. Uma solicitação sem campo utilizável retorna a primeira página de todas as associações indexadas.

Campo	Tipo	Descrição
query?1 2	string	O texto correspondido contra os campos de identidade indexados (máx. 100 caracteres)
limit?	integer	O número máximo de resultados a serem retornados (1-100, padrão 25)
offset?	integer	O número de resultados correspondentes a pular (mínimo 0, padrão 0)
role_ids?3	array[snowflake]	Os IDs de cargos que um membro correspondente deve possuir (máx. 10)
joined_at_gte?4	integer	Segundos Unix, inclui membros que entraram nesse ou após esse tempo
joined_at_lte?4	integer	Segundos Unix, inclui membros que entraram nesse ou antes desse tempo
join_source_type?5	array[integer]	Os tipos de origem de entrada a incluir (máx. 10)
source_invite_code?2 5	array[string]	Os códigos de convite a incluir (máx. 10)
is_bot?	boolean	Inclua apenas contas de bot quando true, e apenas contas que não são de bot quando false
user_created_at_gte?4 6	integer	Segundos Unix, inclui contas criadas nesse ou após esse tempo
user_created_at_lte?4 6	integer	Segundos Unix, inclui contas criadas nesse ou antes desse tempo
sort_by?7	string	O campo de ordenação, joinedAt ou relevance
sort_order?7	string	A direção da ordenação, asc ou desc

¹ Aparado antes do uso. Um valor ausente ou que contenha apenas espaços em branco não aplica cláusula de texto

² Verificado pela moderação de conteúdo como qualquer outra string do corpo, então um valor de pelo menos três caracteres correspondendo a uma lista de bloqueio retorna 403 CONTENT_BLOCKED

³ Todo cargo listado deve ser possuído por um resultado, então várias entradas restringem a pesquisa

⁴ Ambos os extremos são inclusivos, e fornecer apenas um deixa o outro ilimitado

⁵ Aplicado apenas quando o chamador possui MANAGE_GUILD, e descartado para qualquer outro chamador. Várias entradas ampliam a pesquisa

⁶ Derivado do snowflake da conta

⁷ O campo de ordenação é camel-cased joinedAt, onde o objeto de resultado nomeia o mesmo valor como joined_at

A normalização de entrada reescreve "" para null, o que o campo query rejeita com 400 INVALID_FORM_BODY. " " é aceito.

Sem sort_by, a rota ordena pelo tempo de entrada e define sort_order para desc por padrão. Dois membros com o mesmo tempo de entrada são ordenados pelo id em ordem decrescente. relevance ignora sort_order. Uma instância Meilisearch ordena uma pesquisa por relevance pelas suas próprias regras de ranqueamento, e uma instância Elasticsearch pelo id em ordem decrescente.

A correspondência de texto percorre o nome de usuário, o discriminador, o nome de exibição global, o apelido na guilda e o ID de usuário. Uma consulta pode corresponder ao meio de um nome de usuário, assim como ao seu início. O backend de pesquisa define a correspondência de termos e a tolerância a erros de digitação. A correspondência de filtros é exata em todos os casos.

Um offset profundo retorna 200 com uma página vazia

Uma instância usando Meilisearch retorna uma página vazia além de 10000 resultados. Instâncias usando Elasticsearch suportam offsets maiores.

Resposta

Status	Corpo	Condição
200	objeto de resposta de pesquisa de membro da guilda	A pesquisa foi avaliada, ou o índice não está pronto
400	resposta de erro	O filtro, valor de ordenação, limite ou offset é inválido
4031	resposta de erro	A guilda está indisponível, uma string do corpo está bloqueada, ou o chamador não é membro ou não possui nenhuma das permissões exigidas
404	resposta de erro	A guilda não existe e a requisição retorna UNKNOWN_GUILD

¹ O código de erro é MISSING_ACCESS para uma guilda indisponível, CONTENT_BLOCKED para uma string de corpo bloqueada e MISSING_PERMISSIONS de outra forma

Quando o Decoding Chat está construindo o índice de membros da guilda, a resposta é 200 com uma página vazia e indexing definido como true. Tente novamente mais tarde. Esta rota não tem resposta FEATURE_TEMPORARILY_DISABLED. Quando o backend de pesquisa está indisponível, a rota retorna 200 com uma página vazia e indexing como false.

indexing false não significa zero correspondências

Uma página vazia com indexing false pode significar ausência de correspondências ou que a pesquisa está indisponível.

Efeitos colaterais

Uma pesquisa em uma guilda cujo índice de membros precisa de construção enfileira um trabalho de indexação e retorna indexing como true. Ela não altera as associações.

Limite de taxa

40 requisições por 10 segundos para cada usuário autenticado e ID de guilda, no bucket compartilhado guild:members::guild_id. Listar membros da guilda, Obter membro atual da guilda, Obter membro da guilda e Listar banimentos da guilda consomem o mesmo bucket.