Nach Gruppenbereichen suchen

In diesem Leitfaden wird erläutert, wie Sie mit der search() Methode für die Space Ressource der Google Chat API nach benannten Gruppenbereichen in einer Google Workspace-Organisation suchen.

Die Ressource Space stellt einen Ort dar, an dem Nutzer und Chat-Apps Nachrichten senden, Dateien teilen und zusammenarbeiten können. Es gibt verschiedene Arten von Gruppenbereichen:

  • Direktnachrichten sind Unterhaltungen zwischen zwei Nutzern oder einem Nutzer und einer Chat-App.
  • Gruppenchats sind Unterhaltungen zwischen mindestens drei Nutzern und Chat-Apps.
  • Benannte Gruppenbereiche sind dauerhafte Orte, an denen Nutzer Nachrichten senden, Dateien teilen und zusammenarbeiten können.

Wenn Sie Google Workspace-Administrator sind und in allen Gruppenbereichen Ihrer Organisation suchen möchten, einschließlich privater Gruppenbereiche, denen Sie nicht beigetreten sind, lesen Sie den Hilfeartikel Gruppenbereiche als Google Workspace-Administrator suchen und verwalten. Dort erfahren Sie, wie Sie die API mit Administratorberechtigungen aufrufen (useAdminAccess=true).

Wenn Sie ohne Administratorberechtigungen nach Gruppenbereichen mit Nutzerauthentifizierung suchen, werden mit der Methode benannte Gruppenbereiche (spaceType von SPACE) durchsucht, auf die der authentifizierte Nutzer Zugriff hat, z. B. Gruppenbereiche, in denen er Mitglied ist.

Vorbereitung

Node.js

Python

Java

Apps Script

Mit Nutzerauthentifizierung nach Gruppenbereichen suchen

Wenn Sie ohne Administratorberechtigungen in Google Chat nach Gruppenbereichen suchen möchten, übergeben Sie Folgendes in Ihrer Anfrage:

  • Geben Sie bei der Nutzerauthentifizierung den chat.spaces.readonly oder chat.spaces Autorisierungsbereich an.
  • Rufen Sie die search() Methode für die Space Ressource auf.
  • Setzen Sie useAdminAccess auf false oder lassen Sie den Parameter weg.
  • Geben Sie die Such query parameter an, um die Ergebnisse zu filtern:
    • spaceType = "SPACE": Ist erforderlich, wenn query angegeben ist. Der einzige unterstützte Wert ist SPACE.
    • displayName – Filtern Sie nach dem Anzeigenamen des Gruppenbereichs mit dem Operator HAS (:). Beispiel: displayName:"Project". Der abzugleichende Text wird in Tokens zerlegt. Jedes Token wird unabhängig und ohne Berücksichtigung der Groß-/Kleinschreibung als Teilstring an einer beliebigen Stelle im displayName des Gruppenbereichs mit einem Präfix abgeglichen. Hinweis: Wenn useAdminAccess auf false gesetzt ist, ist displayName in Ihrer Abfrage erforderlich, um aussagekräftige Ergebnisse zu erhalten. Andernfalls gibt die Methode eine leere Antwort zurück.
    • externalUserAllowed: Optional können Sie filtern, ob externe Gäste im Gruppenbereich zulässig sind (true oder false).
  • Optional können Sie pageSize angeben, um die maximale Anzahl der zurückzugebenden Gruppenbereiche zu begrenzen (bis zu 1000), oder pageToken, um nachfolgende Ergebnisseiten abzurufen.
  • Optional können Sie orderBy angeben, um die Suchergebnisse zu sortieren (createTime desc oder relevance desc). Hinweis: relevance desc ist über das Google Workspace Developer Preview Program verfügbar.

In verschiedenen Feldern in der Abfrage werden nur AND-Operatoren unterstützt. Beispiel: spaceType = "SPACE" AND displayName:"Hello" AND externalUserAllowed = "true". In displayName und externalUserAllowed werden OR-Operatoren unterstützt, wenn Sie mehrere Kriterien abgleichen möchten.

Im folgenden Beispiel wird nach benannten Gruppenbereichen gesucht, deren Anzeigename „Project“ enthält:

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);
  }
}

Die Chat API gibt eine paginierte Liste von Gruppenbereichen zurück, die der Abfrage entsprechen und für den aufrufenden Nutzer zugänglich sind.