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 nombrados en toda 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 en los que 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 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 en los que 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 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 invitados externos.
  • Busca y borra espacios inactivos. Con el método search(), puedes encontrar espacios que no se hayan usado desde una fecha y hora específicos, 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.
  • Busca a los administradores del espacio y comunícate con ellos. 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 espacios que no tienen ningún administrador.

Requisitos previos

Python

  • Debes tener privilegios de administrador para administrar el chat y las conversaciones de los espacios en tu organización de Google Workspace.

Cómo llamar a la API de Google Chat como administrador

Para autenticar 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 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 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 permiso 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, 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(
    'client_secrets.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

Busca 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, 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 permiso 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 mostrará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 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 de 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(
      'client_secrets.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 una 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