Pesquisar e gerenciar os espaços do Google Chat para sua organização do Google Workspace

Este guia explica como um administrador do Google Workspace pode usar o search() método em um Space recurso da API Google Chat com privilégios de administrador (useAdminAccess=true) para gerenciar espaços nomeados na organização e realizar tarefas administrativas.

Como administrador do Google Workspace, só é possível usar a API Chat para gerenciar espaços nomeados, que são definidos como um SpaceType de SPACE. Os espaços nomeados são lugares permanentes em que as pessoas enviam mensagens, compartilham arquivos e colaboram. Não é possível usar a API Chat para gerenciar mensagens diretas (MDs) ou chats em grupo.

O Space recurso representa um lugar em que pessoas e apps do Chat podem enviar mensagens, compartilhar arquivos e colaborar. Há vários tipos de espaços:

  • As mensagens diretas (MDs) são conversas entre dois usuários ou um usuário e um app do Chat.
  • Os chats em grupo são conversas entre três ou mais usuários e apps do Chat.
  • Os espaços nomeados são lugares permanentes em que as pessoas enviam mensagens, compartilham arquivos e colaboram.

Como administrador do Google Workspace, você pode usar a API Chat para pesquisar e gerenciar espaços nomeados na sua organização das seguintes maneiras:

  • Auditar espaços na organização. Usando o método search(), é possível recuperar uma lista de todos os espaços em uma organização com informações detalhadas sobre as configurações e metadados de cada espaço, como data de criação, data da última atividade, número de membros, status da configuração do histórico e capacidade de convidar pessoas externas.
  • Encontrar e excluir espaços inativos. Usando o método search(), é possível encontrar e excluir espaços não usados desde uma data/hora específica. Para mais detalhes e exemplos de código, consulte Encontrar e excluir espaços inativos.
  • Exportar uma lista de espaços com base nos critérios de pesquisa. Usando o método search(), é possível recuperar uma lista de espaços que atendem aos critérios especificados na query e exportar os resultados para um arquivo CSV para análise.
  • Encontrar e entrar em contato com os admins de espaços. Usando o search() método, é possível recuperar uma lista de todos os espaços em uma organização, em seguida, usar o members.list() método para recuperar uma lista de todos os membros do espaço que são admins.
  • Encontrar espaços sem admins designados. Usando o método search(), é possível recuperar uma lista de todos os espaços em uma organização e, em seguida, usar o método members.list() para recuperar uma lista de espaços que não têm admins.

Pré-requisitos

Python

  • Uma conta do Google Workspace Business ou Enterprise com acesso ao Google Chat.

Chamar a API Google Chat como administrador

Para autenticar como um usuário com privilégios de administrador, é necessário transmitir o seguinte na solicitação:

  • Especifique um escopo de autorização que ofereça suporte ao uso da autenticação do usuário com privilégios de administrador.
  • Defina o campo useAdminAccess como true.

Esta seção mostra os seguintes exemplos de como chamar a API Chat como administrador:

Pesquisar espaços na sua organização

Este exemplo explica como os administradores do Google Workspace podem usar o método search() no recurso Space da API Chat para pesquisar espaços em uma organização com base em critérios especificados.

Para chamar o método search() com autenticação do usuário e privilégios de administrador, é necessário especificar o seguinte na solicitação:

  • Especifique o chat.admin.spaces ou chat.admin.spaces.readonly escopo de autorização.
  • Especifique useAdminAccess=true.
  • Especifique os parâmetros de pesquisa query para filtrar os resultados:
    • customer = "customers/my_customer" - obrigatório e o único valor aceito é customers/my_customer
    • spaceType = "SPACE" - obrigatório e o único valor compatível é SPACE
    • Opcionalmente, uma ou mais consultas adicionais para filtrar ainda mais a pesquisa de espaço, como palavras-chave em nomes de exibição (displayName), a data de criação (createTime) ou com base na atividade do espaço (lastActiveTime).

O código a seguir mostra um exemplo de como usar privilégios de administrador para pesquisar espaços com um nome de exibição que contenha "Hello" e "World", em qualquer combinação:

Python

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

  2. Inclua o código a seguir em search_spaces_for_hello_world.py:

    from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

SCOPES = [
  'https://www.googleapis.com/auth/chat.admin.spaces.readonly',
]

def main():
# Authenticate with Google Workspace
# and get user authorization.
flow = InstalledAppFlow.from_client_secrets_file(
    'credentials.json',
    SCOPES,
)
creds = flow.run_local_server()

# Build a service endpoint for Chat API.
chat = build('chat', 'v1', credentials=creds)

spaces = []
page_token = ''

# Search for all spaces.
while True:
  result = (
      chat.spaces()
      .search(
          useAdminAccess=True,
          query=(
            'customer = "customers/my_customer"'
            'AND spaceType = "SPACE"'
            'AND displayName:"Hello World"'
            )
pageToken=page_token,
      )
      .execute()
  )
  if 'spaces' not in result:
    print('No spaces found named Hello World.')
    return
  spaces.extend(result['spaces'])
  if 'nextPageToken' in result:
    page_token = result['nextPageToken']
  else:
    break

print(str(len(spaces)) + ' spaces found:')
# Prints the list of spaces.
print(spaces)

  3. No diretório de trabalho, crie e execute o exemplo:

    python3 search_spaces_for_hello_world.py

Encontrar e excluir espaços inativos

Este exemplo explica como os administradores do Google Workspace podem usar o método search() no recurso Space da API Chat para encontrar espaços inativos e excluí-los usando o método delete() com o parâmetro useAdminAccess.

Os espaços inativos do Google Chat, aqueles que não estão mais sendo usados ativamente, podem ocupar um espaço de armazenamento valioso e criar confusão na interface do usuário. Usando o método search(), os administradores podem encontrar espaços que não foram usados desde uma data e hora especificadas, como há dois meses. Depois que a lista de espaços é enumerada, os administradores podem agir neles, como atualizar ou excluir.

Para pesquisar uma lista de espaços inativos e excluí-los com autenticação do usuário e privilégios de administrador, transmita o seguinte nas solicitações:

  • Para pesquisar espaços inativos, especifique o seguinte:
    • Especifique o chat.admin.spaces ou chat.admin.spaces.readonly escopo de autorização.
    • Chame o método search() no recurso Spaces.
    • Defina INACTIVE_SPACE_DEADLINE como a data e hora da última atividade que determina os espaços a serem retornados.
    • Especifique useAdminAccess=true.
    • Especifique os parâmetros de pesquisa query para filtrar os resultados:
      • customer = "customers/my_customer" - obrigatório e o único valor compatível é customers/my_customer
      • spaceType = "SPACE" - obrigatório e o único valor compatível é SPACE
      • lastActiveTime - para filtrar sua solicitação e retornar apenas espaços inativos, especifique o lastActiveTime
  • Para excluir os espaços inativos dos resultados da pesquisa, especifique o seguinte:
    • Especifique o escopo de autorização chat.admin.delete.
    • Chame o método delete() no recurso Spaces.
    • Especifique useAdminAccess=true.

O código a seguir mostra um exemplo de como pesquisar espaços inativos e excluí-los usando privilégios de administrador:

Python

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

  2. Inclua o código a seguir em find_and_delete_inactive_spaces.py:

    
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

SCOPES = [
    'https://www.googleapis.com/auth/chat.admin.spaces.readonly',
    'https://www.googleapis.com/auth/chat.admin.delete',
]

# Any spaces that have not been active since this time will be deleted.
INACTIVE_SPACE_DEADLINE = '"INACTIVE_DATE"'

def main():
  # Authenticate with Google Workspace
  # and get user authorization.
  flow = InstalledAppFlow.from_client_secrets_file(
      'credentials.json',
      SCOPES,
  )
  creds = flow.run_local_server()

  # Build a service endpoint for Chat API.
  chat = build('chat', 'v1', credentials=creds)

  spaces = []
  page_token = ''

  # Search for all inactive spaces.
  while True:
    result = (
        chat.spaces()
        .search(
            useAdminAccess=True,
            query=(
                'customer = "customers/my_customer" AND spaceType = "SPACE" AND'
                ' lastActiveTime < '
            )
            + INACTIVE_SPACE_DEADLINE,
            pageToken=page_token,
        )
        .execute()
    )
    if 'spaces' not in result:
      print('No inactive spaces found.')
      return
    spaces.extend(result['spaces'])
    if 'nextPageToken' in result:
      page_token = result['nextPageToken']
    else:
      break

  print(str(len(spaces)) + ' inactive spaces found:')
  # Prints the list of inactive spaces.
  print(spaces)

  # Delete all inactive spaces.
  for space in spaces:
    (
        chat.spaces()
        .delete(
            useAdminAccess=True,
            name=space['name'],
        )
        .execute()
    )
    print(
        'Deleted space: '
        + space['displayName']
        + ', Resource Name: '
        + space['name']
    )

if __name__ == '__main__':
  main()

  3. No código, substitua INACTIVE_DATE por uma data e hora no formato AAAA-MM-DDTHH:MM:SS+HH:MM. Por exemplo, "2024-06-01T00:00:00+00:00".

  4. No diretório de trabalho, crie e execute o exemplo:

    python3 find_and_delete_inactive_spaces.py