Method: spaces.messages.search

Pesquisa mensagens no Google Chat a que o usuário que faz a chamada tem acesso. Retorna uma lista de mensagens que correspondem aos critérios de pesquisa.

Para pesquisar em todos os espaços a que o usuário tem acesso, defina parent como spaces/-. O uso de qualquer outro valor para parent resulta em um erro INVALID_ARGUMENT. As mensagens retornadas têm o campo name preenchido com o nome completo do recurso, que inclui o space específico em que a mensagem reside.

Essa API não retorna todos os tipos de mensagem. Os tipos de mensagens listados abaixo não estão incluídos na resposta. Use messages.list para listar todas as mensagens.

  • Mensagens particulares visíveis para o usuário autenticado.
  • Mensagens postadas por apps do Chat em espaços ou chats em grupo.
  • Mensagens em uma mensagem direta do app do Chat.
  • Mensagens de usuários bloqueados.
  • Mensagens em espaços que o autor da chamada silenciou.

Requer autenticação do usuário com um dos seguintes escopos de autorização:

  • https://www.googleapis.com/auth/chat.messages.readonly
  • https://www.googleapis.com/auth/chat.messages

Solicitação HTTP

POST https://chat.googleapis.com/v1/{parent=spaces/*}/messages:search

O URL usa a sintaxe de transcodificação gRPC.

Parâmetros de caminho

Parâmetros
parent

string

Obrigatório. O nome de recurso do espaço em que pesquisar.

Para pesquisar em todos os espaços a que o usuário tem acesso, defina esse campo como spaces/-. O uso de qualquer outro valor para parent resulta em um erro INVALID_ARGUMENT.

Para limitar a pesquisa a um ou mais espaços, use space.name ou space.display_name no filter.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON 
{
  "filter": string,
  "pageSize": integer,
  "pageToken": string,
  "orderBy": string,
  "view": enum (SearchMessagesView)
}
Campos
filter

string

Obrigatório. Uma consulta de pesquisa.

A consulta pode especificar uma ou mais palavras-chave de pesquisa, que são usadas para filtrar os resultados,

Também é possível filtrar os resultados usando os seguintes campos de mensagem:

  • createTime: aceita um carimbo de data/hora no formato RFC-3339. Os operadores de comparação aceitos são: < e >=.
  • sender.name: o nome do recurso do remetente (users/{user}). Aceita apenas =. Você pode usar o e-mail como um alias para {user}. Por exemplo, users/example@gmail.com, em que example@gmail.com é o e-mail do usuário do Google Chat.
  • space.name: o nome do recurso do espaço em que a mensagem é postada. (spaces/{space}). Aceita apenas =. Se esse filtro não estiver definido, a pesquisa será realizada em todas as mensagens diretas e espaços a que o usuário tem acesso como membro do espaço.
  • space.display_name: aceita o operador : (tem) e filtra espaços com base em uma correspondência parcial do nome de exibição. Os resultados são limitados às cinco principais correspondências de espaço. Por exemplo, space.display_name:Project pesquisa mensagens nos cinco principais espaços que contêm a palavra "Project" nos nomes de exibição.
  • attachment: aceita o operador :* (tem qualquer) para verificar a presença de anexos. Se attachment:* for especificado, somente as mensagens que tiverem pelo menos um anexo serão retornadas.
  • annotations.user_mentions.user.name: o nome do recurso do usuário mencionado (users/{user}). Aceita apenas : (tem). Por exemplo: annotations.user_mentions.user.name:"users/1234567890" retorna apenas mensagens que contêm uma menção ao usuário especificado. Como alternativa, o alias me pode ser usado para filtrar mensagens que mencionam o usuário que faz a chamada. Por exemplo: annotations.user_mentions.user.name:users/me. Você também pode usar o e-mail como um alias para {user}, por exemplo, users/example@gmail.com.

Para filtragem avançada, as seguintes funções também estão disponíveis:

  • has_link(): retorna apenas mensagens que têm pelo menos um hiperlink no texto da mensagem.
  • is_unread(): filtra as mensagens que foram lidas pelo usuário que faz a chamada.

O uso do filtro space.display_name exige que as credenciais de chamada incluam um dos seguintes escopos de autorização:

  • https://www.googleapis.com/auth/chat.spaces.readonly
  • https://www.googleapis.com/auth/chat.spaces

O uso do filtro is_unread() exige que as credenciais de chamada incluam um dos seguintes escopos de autorização:

  • https://www.googleapis.com/auth/chat.users.readstate.readonly
  • https://www.googleapis.com/auth/chat.users.readstate

Em campos diferentes, apenas operadores AND são aceitos. Um exemplo válido é sender.name = "users/1234567890" AND is_unread(). A palavra AND é opcional e está implícita se for omitida. Por exemplo, sender.name = "users/1234567890" is_unread() é válido e equivalente ao exemplo anterior. Um exemplo inválido é sender.name = "users/1234567890" OR is_unread() porque OR não é aceito entre campos diferentes.

No mesmo campo:

  • createTime aceita apenas AND e só pode ser usado para representar um intervalo, como createTime >= "2022-01-01T00:00:00+00:00" AND createTime < "2023-01-01T00:00:00+00:00".
  • sender.name aceita apenas o operador OR. Por exemplo: sender.name = "users/1234567890" OR sender.name = "users/0987654321".
  • space.name aceita apenas o operador OR. Por exemplo: space.name = "spaces/ABCDEFGH" OR space.name = "spaces/QWERTYUI".
  • space.display_name aceita os operadores AND e OR, mas não uma combinação dos dois. Por exemplo: space.display_name:Project AND space.display_name:Tasks retorna mensagens que estão em espaços com nomes de exibição que contêm Project e Tasks, enquanto space.display_name:Project OR space.display_name:Tasks retorna mensagens que estão em espaços com nomes de exibição que contêm Project ou Tasks ou ambos.
  • annotations.user_mentions.user.name aceita os operadores AND e OR, mas não uma combinação dos dois. Por exemplo: annotations.user_mentions.user.name:"users/1234567890" AND annotations.user_mentions.user.name:"users/0987654321" retorna apenas mensagens que mencionam os dois usuários, enquanto annotations.user_mentions.user.name:"users/1234567890" OR annotations.user_mentions.user.name:"users/0987654321" retorna mensagens que mencionam um ou ambos os usuários.

Os parênteses são necessários para desambiguar a precedência do operador ao combinar operadores AND e OR na mesma consulta. Por exemplo: (sender.name="users/me" OR sender.name="users/123456") AND is_unread(). Caso contrário, os parênteses são opcionais.

As consultas de exemplo a seguir são válidas:

"Pending reports" AND createTime >= "2023-01-01T00:00:00Z"

sender.name = "users/example@gmail.com"

annotations.user_mentions.user.name:"users/0987654321"

attachment:* AND space.name = "spaces/ABCDEFGH"

tasks AND is_unread() AND sender.name = "users/1234567890"

"things to do" "urgent"

(sender.name = "users/1234567890")
AND (createTime < "2023-05-01T00:00:00Z")

tasks AND space.name = "spaces/ABCDEFGH" AND has_link()

"project one" is_unread()

space.display_name:Project tasks

O comprimento máximo da consulta é de 1.000 caracteres.

Consultas inválidas são rejeitadas pelo servidor com um erro INVALID_ARGUMENT.
pageSize

integer

Opcional. O número máximo de resultados a serem retornados. O serviço pode retornar um valor inferior a este.

Se não for especificado, no máximo 25 serão retornados.

O valor máximo é 100. Se você usar um valor maior que 100, ele será alterado automaticamente para 100.
pageToken

string

Opcional. Um token recebido da chamada de mensagens de pesquisa anterior. Forneça esse parâmetro para recuperar a página subsequente.

Na paginação, todos os outros parâmetros fornecidos precisam corresponder à chamada que forneceu o token da página. A transmissão de valores diferentes para os outros parâmetros pode levar a resultados inesperados.
orderBy

string

Opcional. Como a lista de resultados é ordenada.

Os atributos aceitos para ordenar por são:

  • createTime: classifica os resultados pelo horário de criação da mensagem. Valor padrão.
  • relevance: classifica os resultados por relevância.

A ordem padrão é createTime desc. Apenas uma única ordem por consulta (createTime ou relevance) é aceita. Apenas a ordem decrescente (desc) é aceita e precisa ser especificada após o atributo de ordem.
view

enum (SearchMessagesView)

Opcional. Especifica o tipo de visualização de resultados da pesquisa a ser retornado. O padrão é SEARCH_MESSAGES_VIEW_BASIC.

Corpo da resposta

Mensagem de resposta para pesquisar mensagens.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON 
{
  "results": [
    {
      object (SearchMessageResult)
    }
  ],
  "nextPageToken": string
}
Campos
results[]

object (SearchMessageResult)

A lista de resultados da pesquisa que correspondem à consulta.
nextPageToken

string

Um token que pode ser usado para recuperar a próxima página. Se esse campo estiver vazio, não haverá páginas subsequentes.

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

  • https://www.googleapis.com/auth/chat.messages
  • https://www.googleapis.com/auth/chat.messages.readonly

Para mais informações, consulte o guia de autorização.

SearchMessagesView

Os tipos de visualização aceitos para resultados parciais da pesquisa.

Tipos enumerados
SEARCH_MESSAGES_VIEW_UNSPECIFIED O valor padrão / não definido. O padrão da API será a visualização BASIC.
SEARCH_MESSAGES_VIEW_BASIC Inclui apenas as mensagens correspondentes nos resultados, mas sem outros metadados. Esse é o valor padrão.
SEARCH_MESSAGES_VIEW_FULL Inclui tudo nos resultados: as mensagens correspondentes e outros metadados.

SearchMessageResult

Um único item de resultado de uma pesquisa de mensagens.

Representação JSON 
{
  "message": {
    object (Message)
  },
  "spaceMuteSetting": enum (MuteSetting),
  "read": boolean
}
Campos
message

object (Message)

A mensagem correspondente.
spaceMuteSetting

enum (MuteSetting)

A configuração de silenciamento do usuário que faz a chamada para o espaço em que a mensagem é postada. O app de chamada pode usar essas informações para decidir como processar a mensagem, dependendo se o espaço está silenciado para o usuário ou não.

Retornado apenas se a visualização da solicitação for SEARCH_MESSAGES_VIEW_FULL e as credenciais de chamada incluírem o seguinte escopo de autorização:

  • https://www.googleapis.com/auth/chat.users.spacesettings
read

boolean

Indica se a mensagem correspondente foi lida pelo usuário que faz a chamada.

Retornado apenas se a visualização da solicitação for SEARCH_MESSAGES_VIEW_FULL e as credenciais de chamada incluírem um dos seguintes escopos de autorização:

  • https://www.googleapis.com/auth/chat.users.readstate.readonly
  • https://www.googleapis.com/auth/chat.users.readstate