Busca y administra espacios de Google Chat para tu organización de Google Workspace

En esta guía, se explica cómo un administrador de Google Workspace puede usar el search() método en un Space recurso de la API de Google Chat para administrar espacios con nombre en su organización y realizar tareas administrativas.

Como administrador de Google Workspace, solo puedes usar la API de Chat para administrar espacios con nombre, que se definen como un SpaceType de SPACE. Los espacios con nombre son lugares persistentes donde las personas envían mensajes, comparten archivos y colaboran. No puedes usar la API de Chat para administrar mensajes directos (MD) ni chats en grupo.

El recurso Space representa un lugar donde las personas y las apps de Chat pueden enviar mensajes, compartir archivos y colaborar. Existen varios tipos de espacios:

  • Los mensajes directos (MD) son conversaciones entre dos usuarios o entre un usuario y una app de Chat.
  • Los chats en grupo son conversaciones entre tres o más usuarios y apps de Chat.
  • Los espacios con nombre son lugares persistentes donde las personas envían mensajes, comparten archivos y colaboran.

Como administrador de Google Workspace, puedes usar la API de Chat para buscar y administrar espacios con nombre en tu organización de las siguientes maneras:

  • Auditar espacios en la organización Con el método search(), puedes recuperar una lista de todos los espacios de una organización con información detallada sobre la configuración y los metadatos de cada espacio, como la fecha de creación, la fecha de la última actividad, la cantidad de miembros, el estado de la configuración del historial y la capacidad de invitar a personas externas.
  • Encontrar y borrar espacios inactivos Con el método search(), puedes encontrar espacios que no se hayan usado desde una fecha y hora específicas, y borrarlos. Para obtener más detalles y código de muestra, consulta Cómo encontrar y borrar espacios inactivos.
  • Exportar una lista de espacios según los criterios de búsqueda Con el método search(), puedes recuperar una lista de espacios que cumplan con los criterios especificados en la query y exportar los resultados a un archivo CSV para su análisis.
  • Encontrar y comunicarte con los administradores de espacios Con el método search() puedes recuperar una lista de todos los espacios de una organización, luego usar el método members.list() para recuperar una lista de todos los miembros del espacio que son administradores.
  • Encontrar espacios sin administradores designados Con el método search(), puedes recuperar una lista de todos los espacios de una organización y, luego, usar el método members.list() para recuperar una lista de espacios que no tengan administradores.

Requisitos previos

Python

Llama a la API de Google Chat como administrador

Para autenticarte como usuario con privilegios de administrador, debes pasar lo siguiente en tu solicitud:

  • Especifica un alcance de autorización que admita el uso de la autenticación de usuarios con privilegios de administrador.
  • Configura el campo useAdminAccess como true.

En esta sección, se muestran los siguientes ejemplos de cómo llamar a la API de Chat como administrador:

Busca espacios en tu organización

En este ejemplo, se explica cómo los administradores de Google Workspace pueden usar el método search() en el recurso Space de la API de Chat para buscar espacios en una organización según los criterios especificados.

Para llamar al método search() con autenticación de usuarios y privilegios de administrador, debes especificar lo siguiente en la solicitud:

  • Especifica el chat.admin.spaces o chat.admin.spaces.readonly alcance de autorización.
  • Especifica useAdminAccess=true.
  • Especifica los parámetros query de búsqueda para filtrar los resultados:
    • customer = "customers/my_customer" - Es obligatorio y el único valor admitido es customers/my_customer
    • spaceType = "SPACE" - obligatorio y el único valor admitido es SPACE
    • De manera opcional, una o más consultas adicionales para filtrar aún más la búsqueda de espacios, como palabras clave en los nombres visibles (displayName), la fecha de creación (createTime) o según la actividad del espacio (lastActiveTime).

En el siguiente código, se muestra un ejemplo de cómo usar privilegios de administrador para buscar espacios con un nombre visible que contenga "Hello" y "World", en cualquier combinación:

Python

  1. En tu directorio de trabajo, crea un archivo llamado search_spaces_for_hello_world.py.

  2. Incluye el siguiente código en 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. En tu directorio de trabajo, compila y ejecuta la muestra:

    python3 search_spaces_for_hello_world.py

Encuentra y borra espacios inactivos

En este ejemplo, se explica cómo los administradores de Google Workspace pueden usar el método search() en el recurso Space de la API de Chat para encontrar espacios inactivos y, luego, borrarlos con el método delete() con el parámetro useAdminAccess.

Los espacios inactivos de Google Chat, es decir, los que ya no se usan de forma activa, pueden ocupar un espacio de almacenamiento valioso y crear desorden en la interfaz de usuario. Con el método search(), los administradores pueden encontrar espacios que no se hayan usado desde una fecha y hora específicas, como hace dos meses. Una vez que se enumera la lista de espacios, los administradores pueden tomar medidas en ellos, como actualizarlos o borrarlos.

Para buscar una lista de espacios inactivos y, luego, borrarlos con autenticación de usuarios y privilegios de administrador, pasa lo siguiente en tus solicitudes:

  • Para buscar espacios inactivos, especifica lo siguiente:
    • Especifica el chat.admin.spaces o chat.admin.spaces.readonly alcance de autorización.
    • Llama al método search() en el recurso Spaces.
    • Configura INACTIVE_SPACE_DEADLINE en la fecha y hora de la última actividad que determina los espacios que se mostrarán.
    • Especifica useAdminAccess=true.
    • Especifica los parámetros query de búsqueda para filtrar los resultados:
      • customer = "customers/my_customer" - obligatorio y el único valor admitido es customers/my_customer
      • spaceType = "SPACE" - obligatorio y el único valor admitido es SPACE
      • lastActiveTime: Para filtrar tu solicitud de modo que solo muestre espacios inactivos, especifica lastActiveTime.
  • Para borrar los espacios inactivos de los resultados de la búsqueda, especifica lo siguiente:
    • Especifica el alcance de autorización chat.admin.delete.
    • Llama al método delete() en el recurso Spaces.
    • Especifica useAdminAccess=true.

En el siguiente código, se muestra un ejemplo de cómo buscar espacios inactivos y borrarlos con privilegios de administrador:

Python

  1. En tu directorio de trabajo, crea un archivo llamado find_and_delete_inactive_spaces.py.

  2. Incluye el siguiente código en 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. En el código, reemplaza INACTIVE_DATE por una fecha y hora en el formato AAAA-MM-DDTHH:MM:SS+HH:MM. Por ejemplo, "2024-06-01T00:00:00+00:00".

  4. En tu directorio de trabajo, compila y ejecuta la muestra:

    python3 find_and_delete_inactive_spaces.py