Mitglieder in einem Gruppenbereich auflisten

In diesem Leitfaden wird erläutert, wie Sie die Methode list für die Ressource Membership der Google Chat API verwenden, um Mitglieder in einem Gruppenbereich als paginierte, filterbare Liste von Mitgliedschaften in einem Gruppenbereich aufzulisten.

Inhaber*innen und Admins von Gruppenbereichen können einschränken, wer die Mitgliederliste in einem Gruppenbereich sehen darf. Wenn die Sichtbarkeit eingeschränkt ist, werden bei Aufrufen dieser Methode mit App-Authentifizierung möglicherweise eine leere Liste zurückgegeben oder Mitgliedschaften ausgelassen, die für Gruppenbereichsmitglieder nicht sichtbar sind. Aufrufe dieser Methode mit Nutzerauthentifizierung können einen PERMISSION_DENIED-Fehler zurückgeben.

  • Wenn Sie Mitgliedschaften mit App-Authentifizierung auflisten, werden Mitgliedschaften in Gruppenbereichen aufgeführt, auf die die Chat-App Zugriff hat. Mitgliedschaften in Chat-Apps, einschließlich der eigenen, werden jedoch ausgeschlossen.
  • Wenn Sie Mitgliedschaften mit Nutzerauthentifizierung auflisten, werden Mitgliedschaften in Gruppenbereichen aufgeführt, auf die der authentifizierte Nutzer Zugriff hat.
  • Wenn Sie als Google Workspace-Administrator mit der Nutzerauthentifizierung über Administratorberechtigungen Mitgliedschaften auflisten, werden Mitgliedschaften in allen Gruppenbereichen in Ihrer Google Workspace-Organisation aufgeführt.

Die Membership-Ressource gibt an, ob ein menschlicher Nutzer oder eine Google Chat-App zu einem Gruppenbereich eingeladen wurde, Teil eines Gruppenbereichs ist oder nicht.

Vorbereitung

Node.js

Python

Java

Apps Script

Mitglieder in einem Bereich mit Nutzerauthentifizierung auflisten

Wenn Sie Nutzer, Google-Gruppen und Chat-Apps in einem Bereich auflisten möchten, auf den der authentifizierte Nutzer Zugriff hat, übergeben Sie Folgendes in Ihrer Anfrage:

  • Geben Sie bei der Nutzerauthentifizierung den Autorisierungsbereich chat.memberships.readonly oder chat.memberships an.
  • Rufen Sie die Methode ListMemberships auf.
  • Wenn Sie Google-Gruppen auflisten möchten, setzen Sie den Abfrageparameter showGroups auf true.

Im folgenden Beispiel werden Google-Gruppen-, Nutzer- und App-Mitglieder aufgeführt, die für den authentifizierten Nutzer sichtbar sind.

Node.js

chat/client-libraries/cloud/list-memberships-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = [
  'https://www.googleapis.com/auth/chat.memberships.readonly',
];

// This sample shows how to list memberships with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(
    USER_AUTH_OAUTH_SCOPES,
  );

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here
    parent: 'spaces/SPACE_NAME',
    // Filter membership by type (HUMAN or BOT) or role (ROLE_MEMBER or
    // ROLE_MANAGER)
    filter: 'member.type = "HUMAN"',
  };

  // Make the request
  const pageResult = chatClient.listMembershipsAsync(request);

  // Handle the response. Iterating over pageResult will yield results and
  // resolve additional pages automatically.
  for await (const response of pageResult) {
    console.log(response);
  }
}

await main();

Python

chat/client-libraries/cloud/list_memberships_user_cred.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.memberships.readonly"]

# This sample shows how to list memberships with user credential
def list_memberships_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.ListMembershipsRequest(
        # Replace SPACE_NAME here
        parent = 'spaces/SPACE_NAME',
        # Filter membership by type (HUMAN or BOT) or role (ROLE_MEMBER or
        # ROLE_MANAGER)
        filter = 'member.type = "HUMAN"',
        # Number of results that will be returned at once
        page_size = 100
    )

    # Make the request
    page_result = client.list_memberships(request)

    # Handle the response. Iterating over page_result will yield results and
    # resolve additional pages automatically.
    for response in page_result:
        print(response)

list_memberships_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/ListMembershipsUserCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.ListMembershipsRequest;
import com.google.chat.v1.ListMembershipsResponse;
import com.google.chat.v1.Membership;

// This sample shows how to list memberships with user credential.
public class ListMembershipsUserCred {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.memberships.readonly";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      ListMembershipsRequest.Builder request = ListMembershipsRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        // Filter membership by type (HUMAN or BOT) or role
        // (ROLE_MEMBER or ROLE_MANAGER).
        .setFilter("member.type = \"HUMAN\"")
        // Number of results that will be returned at once.
        .setPageSize(10);

      // Iterating over results and resolve additional pages automatically.
      for (Membership response :
          chatServiceClient.listMemberships(request.build()).iterateAll()) {
        System.out.println(JsonFormat.printer().print(response));
      }
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to list memberships with user credential
 *
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.memberships.readonly'
 * referenced in the manifest file (appsscript.json).
 */
function listMembershipsUserCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here
  const parent = "spaces/SPACE_NAME";
  // Filter membership by type (HUMAN or BOT) or role (ROLE_MEMBER or
  // ROLE_MANAGER)
  const filter = 'member.type = "HUMAN"';

  // Iterate through the response pages using page tokens
  let responsePage;
  let pageToken = null;
  do {
    // Request response pages
    responsePage = Chat.Spaces.Members.list(parent, {
      filter: filter,
      pageSize: 10,
      pageToken: pageToken,
    });
    // Handle response pages
    if (responsePage.memberships) {
      for (const membership of responsePage.memberships) {
        console.log(membership);
      }
    }
    // Update the page token to the next one
    pageToken = responsePage.nextPageToken;
  } while (pageToken);
}

Ersetzen Sie SPACE_NAME durch die ID aus dem Feld name des Bereichs, um dieses Beispiel auszuführen. Sie können die ID abrufen, indem Sie die Methode ListSpaces aufrufen oder die URL des Bereichs verwenden.

Die Google Chat API gibt eine Liste von Google Groups-, Personen- und App-Mitgliedern aus dem angegebenen Gruppenbereich zurück.

Mitglieder in einem Gruppenbereich mit App-Authentifizierung auflisten

Wenn Sie Nutzer und Chat-Apps in einem Bereich auflisten möchten, auf den die authentifizierte App Zugriff hat, übergeben Sie Folgendes in Ihrer Anfrage:

  • Geben Sie bei der App-Authentifizierung den Autorisierungsbereich chat.bot an.
  • Rufen Sie die Methode ListMemberships auf.
  • Wenn Sie Google-Gruppen auflisten möchten, setzen Sie den Abfrageparameter showGroups auf true.

Im folgenden Beispiel werden die menschlichen Mitglieder des Gruppenbereichs (nicht die Administratoren des Gruppenbereichs) aufgeführt, die für die Chat-App sichtbar sind:

Node.js

chat/client-libraries/cloud/list-memberships-app-cred.js
import {createClientWithAppCredentials} from './authentication-utils.js';

// This sample shows how to list memberships with app credential
async function main() {
  // Create a client
  const chatClient = createClientWithAppCredentials();

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here
    parent: 'spaces/SPACE_NAME',
    // Filter membership by type (HUMAN or BOT) or role (ROLE_MEMBER or
    // ROLE_MANAGER)
    filter: 'member.type = "HUMAN"',
  };

  // Make the request
  const pageResult = chatClient.listMembershipsAsync(request);

  // Handle the response. Iterating over pageResult will yield results and
  // resolve additional pages automatically.
  for await (const response of pageResult) {
    console.log(response);
  }
}

await main();

Python

chat/client-libraries/cloud/list_memberships_app_cred.py
from authentication_utils import create_client_with_app_credentials
from google.apps import chat_v1 as google_chat

# This sample shows how to list memberships with app credential
def list_memberships_app_cred():
    # Create a client
    client = create_client_with_app_credentials()

    # Initialize request argument(s)
    request = google_chat.ListMembershipsRequest(
        # Replace SPACE_NAME here
        parent = 'spaces/SPACE_NAME',
        # Filter membership by type (HUMAN or BOT) or role (ROLE_MEMBER or
        # ROLE_MANAGER)
        filter = 'member.type = "HUMAN"',
        # Number of results that will be returned at once
        page_size = 100
    )

    # Make the request
    page_result = client.list_memberships(request)

    # Handle the response. Iterating over page_result will yield results and
    # resolve additional pages automatically.
    for response in page_result:
        print(response)

list_memberships_app_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/ListMembershipsAppCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.ListMembershipsRequest;
import com.google.chat.v1.ListMembershipsResponse;
import com.google.chat.v1.Membership;

// This sample shows how to list memberships with app credential.
public class ListMembershipsAppCred {

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithAppCredentials()) {
      ListMembershipsRequest.Builder request = ListMembershipsRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        // Filter membership by type (HUMAN or BOT) or role
        // (ROLE_MEMBER or ROLE_MANAGER).
        .setFilter("member.type = \"HUMAN\"")
        // Number of results that will be returned at once.
        .setPageSize(10);

      // Iterate over results and resolve additional pages automatically.
      for (Membership response :
          chatServiceClient.listMemberships(request.build()).iterateAll()) {
        System.out.println(JsonFormat.printer().print(response));
      }
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to list memberships with app credential
 *
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.bot'
 * used by service accounts.
 */
function listMembershipsAppCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here
  const parent = "spaces/SPACE_NAME";
  // Filter membership by type (HUMAN or BOT) or role (ROLE_MEMBER or
  // ROLE_MANAGER)
  const filter = 'member.type = "HUMAN"';

  // Iterate through the response pages using page tokens
  let responsePage;
  let pageToken = null;
  do {
    // Request response pages
    responsePage = Chat.Spaces.Members.list(
      parent,
      {
        filter: filter,
        pageSize: 10,
        pageToken: pageToken,
      },
      getHeaderWithAppCredentials(),
    );
    // Handle response pages
    if (responsePage.memberships) {
      for (const membership of responsePage.memberships) {
        console.log(membership);
      }
    }
    // Update the page token to the next one
    pageToken = responsePage.nextPageToken;
  } while (pageToken);
}

Ersetzen Sie SPACE_NAME durch die ID aus dem Feld name des Bereichs, um dieses Beispiel auszuführen. Sie können die ID abrufen, indem Sie die Methode ListSpaces aufrufen oder die URL des Bereichs verwenden.

Die Google Chat API gibt eine Liste der menschlichen Mitglieder des angegebenen Gruppenbereichs zurück (Administratoren des Gruppenbereichs ausgenommen).

Listenmitglieder als Google Workspace-Administrator

Wenn Sie Google Workspace-Administrator sind, können Sie die Methode ListMemberships aufrufen, um Mitgliedschaften für einen beliebigen Gruppenbereich in Ihrer Google Workspace-Organisation aufzulisten. Die Chat API gibt nur Mitgliedschaften für Nutzer (sowohl interne als auch externe) oder Google-Gruppen aus Ihrer Organisation zurück. Mitgliedschaften für Chat-Apps werden daher ausgelassen.

So rufen Sie diese Methode als Google Workspace-Administrator auf:

  • Rufen Sie die Methode mit der Nutzerauthentifizierung auf und geben Sie einen Autorisierungsbereich an, der den Aufruf der Methode mit Administratorberechtigungen unterstützt.
  • Geben Sie in Ihrer Anfrage die folgenden Abfrageparameter an:
    • Setzen Sie useAdminAccess auf true.
    • Wenn Sie nur Nutzer zurückgeben möchten, legen Sie filter für member.type auf HUMAN fest.
    • Wenn Sie Nutzer und Gruppen zurückgeben möchten, legen Sie filter für member.type auf einen Wert fest, der nicht gleich BOT AND showGroups gleich true ist.

Weitere Informationen und Beispiele finden Sie unter Google Chat-Gruppenbereiche als Google Workspace-Administrator verwalten.

Paginierung anpassen oder Liste filtern

Wenn Sie die Mitgliedschaften auflisten möchten, übergeben Sie die folgenden Abfrageparameter, um die Paginierung der aufgeführten Mitgliedschaften anzupassen oder sie zu filtern:

  • pageSize: Die maximale Anzahl der zurückzugebenden Mitgliedschaften. Der Dienst gibt möglicherweise weniger als diesen Wert zurück. Wenn nicht angegeben, werden maximal 100 Gruppenbereiche zurückgegeben. Der Höchstwert beträgt 1.000. Werte über 1.000 werden automatisch in 1.000 geändert.
  • pageToken: Ein Seitentoken, das von einem vorherigen Aufruf von „list spaces“ empfangen wurde. Geben Sie dieses Token an, um die nachfolgende Seite abzurufen. Beim Paginieren muss der Filterwert mit dem Aufruf übereinstimmen, der das Seitentoken bereitgestellt hat. Die Übergabe eines anderen Werts kann zu unerwarteten Ergebnissen führen.
  • filter: Ein Abfragefilter. Erfordert Nutzerauthentifizierung. Informationen zu unterstützten Abfragen finden Sie in der ListMembershipsRequest-Referenz.