Cercare e gestire gli spazi di Google Chat per la tua organizzazione Google Workspace

Questa guida spiega come un amministratore di Google Workspace può utilizzare il metodo search() su una risorsa Space dell'API Google Chat per gestire gli spazi denominati nella propria organizzazione ed eseguire attività amministrative.

In qualità di amministratore di Google Workspace, puoi utilizzare l'API Chat solo per gestire gli spazi denominati, definiti come SpaceType di SPACE. Gli spazi denominati sono luoghi permanenti in cui le persone inviano messaggi, condividono file e collaborano. Non puoi utilizzare l'API Chat per gestire i messaggi diretti o le chat di gruppo.

La risorsa Space rappresenta un luogo in cui persone e app di chat possono inviare messaggi, condividere file e collaborare. Esistono diversi tipi di spazi:

  • I messaggi diretti sono conversazioni tra due utenti o tra un utente e un'app di chat.
  • Le chat di gruppo sono conversazioni tra tre o più utenti e app di chat.
  • Gli spazi denominati sono luoghi permanenti in cui le persone inviano messaggi, condividono file e collaborano.

In qualità di amministratore di Google Workspace, puoi utilizzare l'API Chat per cercare e gestire gli spazi denominati nella tua organizzazione nei seguenti modi:

  • Controllare gli spazi nell'organizzazione. Utilizzando il metodo search(), puoi recuperare un elenco di tutti gli spazi di un'organizzazione con informazioni dettagliate sulle impostazioni e sui metadati di ogni spazio, ad esempio data di creazione, data dell'ultima attività, numero di membri, stato dell'impostazione della cronologia e possibilità di invitare ospiti esterni.
  • Trovare ed eliminare gli spazi inattivi. Utilizzando il metodo search(), puoi trovare spazi che non sono stati utilizzati da una data e ora specificate ed eliminarli. Per ulteriori dettagli e codice di esempio, vedi Trovare ed eliminare gli spazi inattivi.
  • Esportare un elenco di spazi in base ai criteri di ricerca. Utilizzando il metodo search(), puoi recuperare un elenco di spazi che soddisfano i criteri specificati in query ed esportare i risultati in un file CSV per l'analisi.
  • Trovare e contattare i gestori degli spazi. Utilizzando il metodo search(), puoi recuperare un elenco di tutti gli spazi di un'organizzazione, quindi utilizzare il metodo members.list() per recuperare un elenco di tutti i membri dello spazio che sono gestori.
  • Trovare spazi senza gestori designati. Utilizzando il metodo search(), puoi recuperare un elenco di tutti gli spazi di un'organizzazione, quindi utilizzare il metodo members.list() per recuperare un elenco di spazi che non hanno gestori.

Prerequisiti

Python

Chiamare l'API Google Chat come amministratore

Per eseguire l'autenticazione come utente con privilegi di amministratore, devi trasmettere quanto segue nella richiesta:

  • Specifica un ambito di autorizzazione che supporti l'utilizzo dell'autenticazione utente con privilegi amministrativi.
  • Imposta il campo useAdminAccess su true.

Questa sezione mostra i seguenti esempi di chiamata dell'API Chat come amministratore:

Cercare spazi in tutta l'organizzazione

Questo esempio spiega come gli amministratori di Google Workspace possono utilizzare il metodo search() nella risorsa Space dell'API Chat per cercare spazi in un'organizzazione in base a criteri specificati.

Per chiamare il metodo search() con autenticazione utente e privilegi di amministratore, devi specificare quanto segue nella richiesta:

  • Specifica l'ambito di autorizzazione chat.admin.spaces o chat.admin.spaces.readonly.
  • Specifica useAdminAccess=true.
  • Specifica i parametri di query ricerca per filtrare i risultati:
    • customer = "customers/my_customer": obbligatorio e l'unico valore supportato è customers/my_customer
    • spaceType = "SPACE": obbligatorio e l'unico valore supportato è SPACE
    • (Facoltativo) Una o più query aggiuntive per filtrare ulteriormente la ricerca dello spazio, ad esempio parole chiave nei nomi visualizzati (displayName), la data di creazione (createTime) o in base all'attività dello spazio (lastActiveTime).

Il seguente codice mostra un esempio di come utilizzare i privilegi di amministratore per cercare spazi con un nome visualizzato che contenga "Hello" e "World", in qualsiasi combinazione:

Python

  1. Nella directory di lavoro, crea un file denominato search_spaces_for_hello_world.py.

  2. Includi il seguente codice in 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. Nella directory di lavoro, compila ed esegui l'esempio:

    python3 search_spaces_for_hello_world.py

Trovare ed eliminare gli spazi inattivi

Questo esempio spiega come gli amministratori di Google Workspace possono utilizzare il metodo search() sulla risorsa Space dell'API Chat per trovare spazi inattivi ed eliminarli utilizzando il metodo delete() con il parametro useAdminAccess.

Gli spazi di Google Chat inattivi, ovvero quelli che non vengono più utilizzati attivamente, possono occupare spazio di archiviazione prezioso e creare disordine nell'interfaccia utente. Utilizzando il metodo search(), gli amministratori possono trovare gli spazi che non sono stati utilizzati da una data e un'ora specificate, ad esempio due mesi fa. Una volta elencati gli spazi, gli amministratori possono intervenire, ad esempio aggiornarli o eliminarli.

Per cercare un elenco di spazi inattivi ed eliminarli con l'autenticazione utente e i privilegi di amministratore, trasmetti quanto segue nelle tue richieste:

  • Per cercare spazi inattivi, specifica quanto segue:
    • Specifica l'ambito di autorizzazione chat.admin.spaces o chat.admin.spaces.readonly.
    • Chiama il metodo search() sulla risorsa Spaces.
    • Imposta INACTIVE_SPACE_DEADLINE sulla data e l'ora dell'ultima attività che determina gli spazi da restituire.
    • Specifica useAdminAccess=true.
    • Specifica i parametri di query ricerca per filtrare i risultati:
      • customer = "customers/my_customer": obbligatorio e l'unico valore supportato è customers/my_customer
      • spaceType = "SPACE": obbligatorio e l'unico valore supportato è SPACE
      • lastActiveTime - per filtrare la richiesta in modo da restituire solo gli spazi inattivi, specifica lastActiveTime
  • Per eliminare gli spazi inattivi dai risultati di ricerca, specifica quanto segue:
    • Specifica l'ambito di autorizzazione chat.admin.delete.
    • Chiama il metodo delete() sulla risorsa Spaces.
    • Specifica useAdminAccess=true.

Il seguente codice mostra un esempio di come cercare gli spazi inattivi ed eliminarli utilizzando i privilegi di amministratore:

Python

  1. Nella directory di lavoro, crea un file denominato find_and_delete_inactive_spaces.py.

  2. Includi il seguente codice in 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. Nel codice, sostituisci INACTIVE_DATE con una data e un'ora nel formato AAAA-MM-GGTHH:MM:SS+HH:MM. Ad esempio, "2024-06-01T00:00:00+00:00".

  4. Nella directory di lavoro, compila ed esegui l'esempio:

    python3 find_and_delete_inactive_spaces.py