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 método search() en un recurso Space 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 de 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 grupales 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:

  • Audita los espacios de 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.
  • Exporta una lista de espacios según los criterios de búsqueda. Con el método search(), puedes recuperar una lista de espacios que cumplen con los criterios especificados en query y exportar los resultados a un archivo CSV para su análisis.
  • Buscar y comunicarse con los administradores del espacio 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 todos los miembros del espacio que son administradores.
  • Encuentra 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 los espacios que no tienen administradores.

Requisitos previos

Python

Llama a la API de Google Chat como administrador

Para autenticarte como un 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 llamadas a la API de Chat como administrador:

Cómo buscar espacios en toda 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 criterios especificados.

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

  • Especifica el alcance de autorización chat.admin.spaces o chat.admin.spaces.readonly.
  • Especifica useAdminAccess=true.
  • Especifica los parámetros de búsqueda query para filtrar los resultados:
    • customer = "customers/my_customer": Es obligatorio y el único valor admitido es customers/my_customer.
    • spaceType = "SPACE": Es obligatorio y el único valor admitido es SPACE.
    • De manera opcional, puedes incluir una o más búsquedas adicionales para filtrar aún más tu búsqueda de espacios, como palabras clave en los nombres visibles (displayName), la fecha de creación (createTime) o 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 "Hola" y "Mundo", 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

Cómo encontrar y borrar 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() y el parámetro useAdminAccess.

Los espacios de Google Chat inactivos, es decir, los que ya no se usan de forma activa, pueden ocupar espacio de almacenamiento valioso y generar 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. Después de enumerar la lista de espacios, los administradores pueden realizar acciones en ellos, como actualizarlos o borrarlos.

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

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