Listar eventos de um espaço do Google Chat

Este guia explica como usar o método list() no recurso SpaceEvent da API Google Chat para listar mudanças nos recursos de um espaço.

O recurso SpaceEvent representa uma mudança no espaço de destino, incluindo recursos filhos do espaço como mensagens, reações e assinaturas. Para mais informações sobre a lista de tipos de eventos e payloads de eventos compatíveis, consulte os campos eventType e payload da documentação de referência do recurso SpaceEvent.

É possível listar eventos até 28 dias antes do horário da solicitação. O servidor retorna eventos que contêm a versão mais recente do recurso afetado. Por exemplo, se você listar eventos sobre novos membros do espaço, o servidor vai retornar recursos Membership que contêm os detalhes mais recentes da associação. Se novos membros foram removidos durante o período solicitado, o payload do evento vai conter um recurso Membership vazio.

Para listar eventos de um espaço, o usuário autenticado ou o app Chat precisa ser membro dele.

Pré-requisitos

Node.js

Python

Listar eventos do espaço (autenticação do usuário)

Para listar eventos de um espaço do Chat, transmita o seguinte na sua solicitação:

  • Especifique um ou mais escopos de autorização para oferecer suporte a cada tipo de evento na sua solicitação. Como prática recomendada, escolha o escopo mais restritivo que ainda permita o funcionamento do app. Para escolher um escopo, consulte a Visão geral da autenticação e autorização.

  • Chame o método ListSpaceEvents() transmitindo o filter dos tipos de eventos a serem listados. É preciso especificar pelo menos um tipo de evento, e também é possível filtrar por data. Para conferir uma lista de tipos de eventos com suporte, consulte o campo eventType do recurso SpaceEvent na documentação de referência.

O exemplo a seguir lista eventos sobre novas assinaturas e mensagens em um espaço:

Node.js

chat/client-libraries/cloud/list-space-events-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

// Authorization scopes based on the event types
const USER_AUTH_OAUTH_SCOPES = [
  'https://www.googleapis.com/auth/chat.memberships.readonly',
  'https://www.googleapis.com/auth/chat.messages.readonly',
];

// This sample shows how to list space events with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(
    USER_AUTH_OAUTH_SCOPES,
  );

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here
    parent: 'spaces/SPACE_NAME',
    // A required filter. Filters events about new memberships and messages.
    filter:
      'eventTypes:"google.workspace.chat.membership.v1.created" OR eventTypes:"google.workspace.chat.message.v1.created"',
  };

  // Make the request
  const pageResult = chatClient.listSpaceEventsAsync(request);

  // Handle the response. Iterating over pageResult will yield results and
  // resolve additional pages automatically.
  for await (const response of pageResult) {
    console.log(response);
  }
}

await main();

Para executar esta amostra, substitua SPACE_NAME pelo ID do name do espaço. Você pode conseguir o ID chamando o método ListSpaces() ou no URL do espaço.

A API Chat retorna uma lista paginada de eventos do espaço sobre novas associações e mensagens.

Listar eventos do espaço (autenticação do app Chat)

A autenticação do app exige uma única aprovação do administrador.

Para listar eventos de um espaço com autenticação de app e a API REST do Chat, transmita o seguinte na sua solicitação:

  • Especifique um ou mais escopos de autorização para oferecer suporte a cada tipo de evento na sua solicitação. Como prática recomendada, escolha o escopo mais restritivo que ainda permita o funcionamento do app. Para saber mais sobre como escolher um escopo, consulte a Visão geral da autenticação e autorização.
    • https://www.googleapis.com/auth/chat.app.memberships
    • https://www.googleapis.com/auth/chat.app.messages.readonly
    • https://www.googleapis.com/auth/chat.app.spaces
  • Chame o método list no recurso spaceEvents.
  • Transmita o name do espaço para listar as mensagens.
  • Transmita um filter para consultar tipos de eventos específicos.

crie uma chave de API

Para chamar um método da API Developer Preview, use uma versão não pública do documento de descoberta da API. Para autenticar a solicitação, transmita uma chave de API.

Para criar a chave de API, abra o projeto do Google Cloud do app e faça o seguinte:

  1. No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.

    Ir para Credenciais

  2. Clique em Criar credenciais > Chave de API.
  3. Sua nova chave de API é exibida.
    • Clique em Copiar para copiar a chave de API e usar no código do app. A chave de API também pode ser encontrada na seção "Chaves de API" das credenciais do seu projeto.
    • Para evitar o uso não autorizado, recomendamos restringir os locais e as APIs em que a chave de API pode ser usada. Para mais detalhes, consulte Adicionar restrições de API.

Escrever um script que chama a API Chat

Confira como listar eventos de espaço com autenticação de app e a API REST do Chat:

Python

  1. No diretório de trabalho, crie um arquivo chamado chat_spaceevents_list_app.py.

  2. Inclua o seguinte código em chat_spaceevents_list_app.py:

    from google.oauth2 import service_account
from apiclient.discovery import build

# Define your app's authorization scopes.
# Set authorization scopes based on the
# event type. For example, if you are getting a space event
# about a new membership, use the `chat.app.memberships.readonly` scope.
#
# When modifying these scopes, delete the file token.json, if it exists.
SCOPES = ["https://www.googleapis.com/auth/chat.app.memberships",
          "https://www.googleapis.com/auth/chat.app.messages.readonly",
          "https://www.googleapis.com/auth/chat.app.spaces"]

def main():
    '''
    Authenticates with Chat API using app authentication,
    then lists space events from a specified space.
    '''

    # Specify service account details.
    creds = (
        service_account.Credentials.from_service_account_file('credentials.json')
        .with_scopes(SCOPES)
    )

    # Build a service endpoint for Chat API.
    chat = build('chat', 'v1', credentials=creds, discoveryServiceUrl='https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY')

    # Use the service endpoint to call Chat API.
    result = chat.spaces().spaceEvents().list(

        # The space to list events from.
        #
        # Replace SPACE_NAME with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        parent='spaces/SPACE_NAME',

        # A required filter. Filters events by event type.
        #
        # Update this filter to match your requirements.
        filter='eventTypes:"google.workspace.chat.message.v1.created"'

    ).execute()

    # Print Chat API's response in your command line interface.
    print(result)

if __name__ == '__main__':
    main()

  3. No código, substitua o seguinte:

    • API_KEY: a chave de API criada para criar o endpoint de serviço da API Chat.
    • SPACE_NAME: o nome de um espaço, que pode ser obtido pelo método spaces.list na API Chat ou no URL de um espaço.

  4. No diretório de trabalho, crie e execute a amostra:

    python3 chat_spaceevents_list_app.py

A API Chat retorna uma lista paginada de eventos do espaço sobre novas associações e mensagens.