Cercare spazi

Questa guida spiega come utilizzare il search() metodo sulla Space risorsa dell' API Google Chat per cercare spazi denominati in un'organizzazione Google Workspace.

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

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

Se sei un amministratore di Google Workspace e vuoi eseguire ricerche in tutti gli spazi della tua organizzazione, inclusi gli spazi privati a cui non hai partecipato, consulta Cercare e gestire gli spazi come amministratore di Google Workspace per chiamare l'API con i privilegi di amministratore (useAdminAccess=true).

Quando si cercano spazi con l'autenticazione utente senza privilegi di amministratore, il metodo cerca gli spazi denominati (spaceType di SPACE) a cui l'utente autenticato ha accesso, ad esempio gli spazi di cui è membro, all'interno della sua organizzazione.

Prerequisiti

Node.js

Python

Java

Apps Script

Cercare spazi con l'autenticazione utente

Per cercare spazi in Google Chat senza privilegi di amministratore, passa quanto segue nella richiesta:

  • Con l'autenticazione utente, specifica l'ambito di autorizzazione chat.spaces.readonly o chat.spaces.
  • Chiama il search() metodo sulla risorsa Space.
  • Imposta useAdminAccess su false (o ometti il parametro).
  • Specifica i parametri di query ricerca per filtrare i risultati:
    • spaceType = "SPACE" - obbligatorio quando viene specificato query e l'unico valore supportato è SPACE.
    • displayName: filtra in base al nome visualizzato dello spazio utilizzando l'operatore HAS (:). Ad esempio, displayName:"Project". Il testo da trovare viene tokenizzato e ogni token viene abbinato al prefisso senza distinzione tra maiuscole e minuscole e in modo indipendente come sottostringa ovunque nel displayName dello spazio. Nota: quando useAdminAccess è false, displayName è obbligatorio nella query per recuperare risultati significativi; in caso contrario, il metodo restituisce una risposta vuota.
    • externalUserAllowed - facoltativamente, filtra in base al fatto che gli ospiti esterni siano consentiti nello spazio (true o false).
  • Facoltativamente, specifica pageSize per limitare il numero massimo di spazi da restituire (fino a 1000) o pageToken per recuperare le pagine successive dei risultati.
  • Facoltativamente, specifica orderBy per ordinare i risultati di ricerca (createTime desc o relevance desc). Nota: relevance desc è disponibile tramite il programma di anteprima per sviluppatori di Google Workspace.

Nei diversi campi della query sono supportati solo gli operatori AND. Ad esempio: spaceType = "SPACE" AND displayName:"Hello" AND externalUserAllowed = "true". All'interno di displayName e externalUserAllowed, gli operatori OR sono supportati se vuoi trovare la corrispondenza con più criteri.

L'esempio seguente cerca gli spazi denominati che contengono "Project" nel nome visualizzato:

Node.js

/**
 * This sample shows how to search for spaces without administrator privileges.
 *
 * It relies on the @google-apps/chat npm package.
 */
// Read the documentation for more details:
// https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search

const {ChatServiceClient} = require('@google-apps/chat');
const {auth} = require('google-auth-library');

async function main() {
  // Create a client
  const chatClient = new ChatServiceClient({
    authClient: await auth.getClient({
      scopes: ['https://www.googleapis.com/auth/chat.spaces.readonly']
    })
  });

  // Initialize request arguments.
  // When useAdminAccess is false, spaceType and displayName are required in query.
  const request = {
    query: 'spaceType = "SPACE" AND displayName:"Project"',
    useAdminAccess: false
  };

  // Call the API and iterate over the paginated response
  const iterable = chatClient.searchSpacesAsync(request);
  for await (const result of iterable) {
    console.log('Found space:', result.space.displayName, result.space.name);
  }
}

main().catch(console.error);

Python

"""
This sample shows how to search for spaces without administrator privileges.
"""
from google.apps import chat_v1
import google.auth

# Read the documentation for more details:
# https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search

def search_spaces():
    # Create a client
    scopes = ["https://www.googleapis.com/auth/chat.spaces.readonly"]
    credentials, _ = google.auth.default(scopes=scopes)
    client = chat_v1.ChatServiceClient(credentials=credentials)

    # Initialize request arguments.
    # When use_admin_access is False, space_type and display_name are required in query.
    request = chat_v1.SearchSpacesRequest(
        query='spaceType = "SPACE" AND displayName:"Project"',
        use_admin_access=False
    )

    # Make the request and iterate over the paginated results.
    page_result = client.search_spaces(request)
    for result in page_result.results:
        print(f"Found space: {result.space.display_name} ({result.space.name})")

if __name__ == "__main__":
    search_spaces()

Java

/**
 * This sample shows how to search for spaces without administrator privileges.
 */
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.ChatServiceClient.SearchSpacesPagedResponse;
import com.google.chat.v1.SearchSpacesRequest;
import com.google.chat.v1.SearchSpaceResult;

// Read the documentation for more details:
// https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search

public class SearchSpaces {
  public static void main(String[] args) throws Exception {
    // See https://github.com/googleworkspace/java-samples/blob/main/chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/AuthenticationUtils.java
    // for an example of how to authenticate the request.
    try (ChatServiceClient chatServiceClient = AuthenticationUtils.createClientWithUserCredentials(
        ImmutableList.of("https://www.googleapis.com/auth/chat.spaces.readonly"))) {
      SearchSpacesRequest request = SearchSpacesRequest.newBuilder()
          .setQuery("spaceType = \"SPACE\" AND displayName:\"Project\"")
          .setUseAdminAccess(false)
          .build();

      SearchSpacesPagedResponse response = chatServiceClient.searchSpaces(request);

      for (SearchSpaceResult result : response.iterateAll()) {
        System.out.printf("Found space: %s (%s)\n", result.space.getDisplayName(), result.space.getName());
      }
    }
  }
}

Apps Script

/**
 * This sample shows how to search for spaces without administrator privileges.
 */
// Read the documentation for more details:
// https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search

function searchSpaces() {
  try {
    // Call the API
    // When useAdminAccess is false, spaceType and displayName are required in query.
    const response = Chat.Spaces.search({
      query: 'spaceType = "SPACE" AND displayName:"Project"',
      useAdminAccess: false
    });

    if (response.results && response.results.length > 0) {
      response.results.forEach(result => {
        console.log('Found space: %s (%s)', result.space.displayName, result.space.name);
      });
    } else {
      console.log('No matching spaces found.');
    }
  } catch (err) {
    console.log('Failed to search spaces: ' + err.message);
  }
}

L'API Chat restituisce un elenco paginato di spazi che corrispondono alla query e sono accessibili all'utente chiamante.