Method: spaces.messages.search

Pesquisa mensagens no Google Chat a que o usuário que fez 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/-. Usar qualquer outro valor para parent resulta em um erro INVALID_ARGUMENT. Os campos name das mensagens retornadas são preenchidos com o nome completo do recurso, que inclui o space específico em que a mensagem está.

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 diretas em um app de 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 do recurso do espaço em que pesquisar.

Para pesquisar em todos os espaços a que o usuário tem acesso, defina este campo como spaces/-. Usar 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 em 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,
  "markupSyntax": enum (MarkupSyntax),
  "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 compatíveis são: < e >=.
  • sender.name: o nome do recurso do remetente (users/{user}). Só é compatível com =. 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 foi postada. (spaces/{space}). Compatível apenas com =. Se esse filtro não for definido, a pesquisa será realizada em todas as mensagens diretas e espaços a que o usuário tem acesso como membro.
  • 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 "Projeto" nos nomes de exibição.
  • space.space_type: o tipo do espaço. Aceita apenas =. Por exemplo, space.space_type="DIRECT_MESSAGE" retorna apenas mensagens diretas. Os valores possíveis são DIRECT_MESSAGE, GROUP_CHAT e SPACE.
  • attachment: aceita o operador :* (tem algum) 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}). Compatível apenas com : (tem). Por exemplo, annotations.user_mentions.user.name:"users/1234567890" retorna apenas mensagens que mencionam o usuário especificado. Como alternativa, o alias me pode ser usado para filtrar mensagens que mencionam o usuário da 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.
  • is_unread(): filtra as mensagens que foram lidas pelo usuário que fez a chamada.

Para usar os filtros space.display_name ou space.space_type, as credenciais de chamada precisam incluir um dos seguintes escopos de autorização:

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

Para usar o filtro is_unread(), as credenciais de chamada precisam incluir 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 os operadores AND são aceitos. Um exemplo válido é sender.name = "users/1234567890" AND is_unread(). A palavra AND é opcional e fica 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 é compatível entre campos diferentes.

No mesmo campo:

  • createTime só é compatível com AND e 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".
  • O sender.name é compatível apenas com o operador OR, por exemplo: sender.name = "users/1234567890" OR sender.name = "users/0987654321".
  • O space.name é compatível apenas com o operador OR, por exemplo: space.name = "spaces/ABCDEFGH" OR space.name = "spaces/QWERTYUI".
  • space.display_name é compatível com os operadores AND e OR, mas não com 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.
  • O space.space_type é compatível apenas com o operador OR, por exemplo: space.space_type = "DIRECT_MESSAGE" OR space.space_type = "GROUP_CHAT".
  • O annotations.user_mentions.user.name é compatível com os operadores AND e OR, mas não com 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 os dois usuários.

Os parênteses são necessários para eliminar a ambiguidade da precedência de operadores ao combinar AND e OR na mesma consulta. Por exemplo: (sender.name="users/me" OR sender.name="users/123456") AND is_unread(). Caso contrário, o uso de parênteses é opcional.

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 tamanho máximo de uma 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á mudado automaticamente para 100.
pageToken

string

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

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

string

Opcional. Como a lista de resultados é ordenada.

Os atributos aceitos para ordenação são:

A ordem padrão é createTime desc. Só é aceita uma ordem por consulta (createTime ou relevance). Apenas a ordem decrescente (desc) é compatível, e ela precisa ser especificada após o atributo de ordenação.
markupSyntax

enum (MarkupSyntax)

Opcional. Especifica a sintaxe de saída desejada para o campo formattedText da mensagem de chat.
view

enum (SearchMessagesView)

Opcional. Especifica o tipo de visualização de resultados da pesquisa a ser retornada. 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 corresponderam à 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 compatíveis com 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, 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 fez a chamada para o espaço em que a mensagem foi 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.

Só será retornado 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 fez a chamada.

Só será retornado 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