Pesquisar mensagens

Neste documento, explicamos como usar o método search no recurso Message da API Google Chat para pesquisar mensagens a que o usuário autenticado tem acesso.

Com a autenticação de usuário, você pode pesquisar mensagens em todas as conversas de que o usuário participa ou em uma conversa específica. Por exemplo, você pode pesquisar mensagens que contêm palavras-chave específicas, mencionam o usuário, não foram lidas ou têm anexos.

Na API Chat, uma mensagem do Chat é representada pelo recurso Message. Os usuários do Chat só podem enviar mensagens de texto, mas os apps do Chat podem usar muitos outros recursos de mensagens, incluindo mostrar interfaces de usuário estáticas ou interativas, coletar informações dos usuários e enviar mensagens particulares. Para saber mais sobre os recursos de mensagens disponíveis para a API Chat, consulte a visão geral das mensagens do Google Chat.

Pré-requisitos

Node.js

Python

Java

Apps Script

Pesquisar mensagens

Para pesquisar mensagens com autenticação de usuário, transmita o seguinte na sua solicitação:

  • Especifique o escopo de autorização chat.messages.readonly ou chat.messages.

  • Chame o método SearchMessages.

  • Defina parent como spaces/- para pesquisar em todos os espaços de que o usuário é membro. Usar qualquer outro valor resulta em um erro.

  • No campo filter, especifique uma string de consulta de pesquisa. A consulta pode incluir palavras-chave e filtros.

O exemplo de código a seguir pesquisa mensagens não lidas que contêm a palavra-chave "tarefas":

Node.js

/**
 * Searches for messages in Google Chat.
 * @param {string} filter The search query.
 */
async function searchMessages(filter) {
  const {ChatServiceClient} = require('@google-apps/chat').v1;

  // Instantiates a client
  const chatClient = new ChatServiceClient();

  // See https://github.com/googleworkspace/node-samples/blob/main/chat/client-libraries/cloud/authentication-utils.js
  // for an example of how to authenticate the request.

  // Construct request
  const request = {
    // Parent must be "spaces/-" to search across all spaces.
    parent: 'spaces/-',
    filter: filter,
  };

  // Run request
  const iterable = await chatClient.searchMessagesAsync(request);
  for await (const response of iterable) {
    console.log(response);
  }
}

searchMessages('tasks AND is_unread()');

Python

from google.apps import chat_v1

def search_messages(filter_str: str):
    """
    Searches for messages in Google Chat.
    Args:
        filter_str: The search query.
    """
    # Create a client
    client = chat_v1.ChatServiceClient()

    # See https://github.com/googleworkspace/python-samples/blob/main/chat/client-libraries/cloud/authentication_utils.py
    # for an example of how to authenticate the request.

    # Initialize request argument
    request = chat_v1.SearchMessagesRequest(
        # Parent must be "spaces/-" to search across all spaces.
        parent="spaces/-",
        filter=filter_str
    )

    # Make the request
    page_result = client.search_messages(request=request)

    # Handle the response
    for response in page_result:
        print(response)

search_messages('tasks AND is_unread()')

Java

import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.SearchMessageResult;
import com.google.chat.v1.SearchMessagesRequest;

public class SearchMessages {
  public static void main(String[] args) throws Exception {
    searchMessages("tasks AND is_unread()");
  }

  /**
   * Searches for messages in Google Chat.
   *
   * @param filter The search query.
   */
  public static void searchMessages(String filter) throws Exception {
    // See https://github.com/googleworkspace/java-samples/blob/main/chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/AuthenticationUtils.java
    // for an example of how to authenticate the request.
    try (ChatServiceClient chatServiceClient = ChatServiceClient.create()) {
      SearchMessagesRequest request =
          SearchMessagesRequest.newBuilder()
              .setParent("spaces/-")
              .setFilter(filter)
              .build();
      for (SearchMessageResult result : chatServiceClient.searchMessages(request).iterateAll()) {
        System.out.println(result.getMessage().getText());
      }
    }
  }
}

Apps Script

javascript /** * Searches for messages in Google Chat. */ function searchMessages() { const filter = 'tasks AND is_unread()'; const url = 'https://chat.googleapis.com/v1/spaces/-/messages:search'; const request_payload = { filter: filter }; try { const response = UrlFetchApp.fetch(url, { method: 'post', headers: { 'Authorization': 'Bearer ' + ScriptApp.getOAuthToken() }, contentType: 'application/json', payload: JSON.stringify(request_payload) }); if (response.results) { for (const result of response.results) { console.log('Message text: %s', result.message.text); } } else { console.log('No messages found.'); } } catch (err) { console.log('Failed to search messages with error: %s', err.message); } }

Usar filtros e operadores de pesquisa

É possível refinar os resultados da pesquisa usando palavras-chave, campos e funções no campo filter. Para mais informações, consulte SearchMessagesRequest.

Para pesquisar mensagens que contenham um texto específico, digite as palavras-chave. Por exemplo, para pesquisar relatórios pendentes, use pending reports.

Pesquisar por campo

Você pode filtrar os resultados por campos específicos de mensagens ou espaços. Exemplo:

  • create_time: filtre pelo horário em que a mensagem foi criada. Exemplo: create_time > "2023-01-01T00:00:00Z"
  • sender.name: filtre pelo nome do recurso do remetente. Exemplo: sender.name = "users/1234567890"
  • space.name: limita a pesquisa a um espaço específico. Exemplo: space.name = "spaces/ABCDEFGH"
  • space.display_name: filtra espaços com base em uma correspondência parcial do nome de exibição. Os resultados são limitados aos cinco principais espaços correspondentes. Exemplo: space.display_name:Project
  • attachment: verifique a presença de anexos. Exemplo: attachment:*
  • annotations.user_mentions.user.name: filtre por menções. Exemplo: annotations.user_mentions.user.name:"users/me"

Pesquisar usando funções

A filtragem avançada está disponível nas seguintes funções:

  • has_link: retorna mensagens que contêm pelo menos um hiperlink.
  • is_unread: retorna mensagens que não foram lidas pelo usuário.

Em campos diferentes, apenas os operadores AND são aceitos. Por exemplo, sender.name = "users/me" AND is_unread().