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 con nome nella propria organizzazione ed eseguire attività amministrative.

In qualità di amministratore di Google Workspace, puoi utilizzare l'API Chat solo per gestire gli spazi con nome, definiti come SpaceType di SPACE. Gli spazi con nome 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 le persone e le 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 con nome 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 con nome nella tua organizzazione nei seguenti modi:

  • Eseguire controlli sugli spazi dell'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 gli spazi che non vengono utilizzati da una data e un'ora specificate ed eliminarli. Per ulteriori dettagli e codice di esempio, consulta Trovare ed eliminare gli spazi inattivi.
  • Esportare un elenco di spazi in base a 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.
  • Trova e contatta 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.
  • Trova gli 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

  • Devi disporre dei privilegi di amministratore per gestire le conversazioni di Chat e degli spazi per la tua organizzazione Google Workspace.

Chiamare l'API Google Chat come amministratore

Per autenticarti come utente con privilegi di amministratore, devi specificare quanto segue nella richiesta:

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

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

Cercare gli spazi nella tua organizzazione

Questo esempio spiega in che modo gli amministratori di Google Workspace possono utilizzare il metodo search() della 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 amministrativi, 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 ricerca query 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
    • Se vuoi, una o più query aggiuntive per filtrare ulteriormente la ricerca nello 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 gli spazi con un nome visualizzato contenente "Un saluto da" e "Google", 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(
    '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. 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 gli 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 confusione 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 autenticazione utente e privilegi di amministratore, invia quanto segue nelle richieste:

  • Per cercare gli spazi non attivi, 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 sull'ora dell'ultima attività che determina gli spazi da restituire.
    • Specifica useAdminAccess=true.
    • Specifica i parametri di ricerca query 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 codice seguente 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(
      '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. 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