Vom Gruppendienst zum erweiterten Cloud Identity-Gruppendienst migrieren

Der erweiterte Dienst für Cloud Identity Groups (CIG) bietet die gleichen Funktionen wie die Groups Service API und kann an ihrer Stelle verwendet werden.

In den Hilfsmethoden erfahren Sie, wie Sie mit dem erweiterten Dienst für CIG entsprechende Funktionen nutzen können.

Einrichtung

Wenn Sie den erweiterten Dienst für CIG verwenden möchten, müssen Sie ihn zuerst aktivieren in Ihrem Skriptprojekt.

Um einige der Methodensignaturen in diesem Leitfaden zu verkürzen, haben wir die folgende Variable definiert:

const groups = CloudIdentityGroups.Groups;

GroupsApp-Methoden

Die folgenden Hilfsmethoden entsprechen denen von Groups Service GroupsApp.

In diesem Leitfaden bezieht sich der Begriff Gruppe auf eine Gruppen ressource, und nicht auf ein Gruppenklassen-Objekt. Gruppenressourcen sind JavaScript-Objekte, die keine Methoden haben. Sie können jedoch im erweiterten Dienst für CIG verwendet werden, um ähnliche Informationen wie in Gruppen klassen-Objekten abzurufen.

getGroupByEmail

/**
 * Given a group's email, returns that group's resource
 *
 * @param {String} email: The email address to lookup a group by
 * @return {Group} group: The group resource associated with the email
 */
function groupsAppGetGroupByEmail(email) {
  // Retrieve the name ID of the group
  const groupName = groups.lookup({
    'groupKey.id': email,
    'groupKey.namespace': ''  // Optional for google groups, dynamic groups, and security groups
                              // Necessary for identity-mapped groups (see https://developers.google.com/cloud-search/docs/guides/identity-mapping)
  }).name;

  // Retrieve the group resource
  return groups.get(groupName);
}

getGroups

Die folgende Hilfsmethode gibt eine Liste von Mitgliedschaftsressourcen zurück. Greifen Sie auf das Feld group eines Elements zu, um die ID des Namens zu finden. Dies ist für viele Methoden des erweiterten Dienstes für CIG nützlich. Greifen Sie auf ähnliche Weise auf groupKey.id eines Elements zu, um die E‑Mail-Adresse zu finden.

/**
 * Retrieves all the membership relation resources to groups which you are a
 * direct member (or a pending member).
 *
 * @return {Array<MembershipRelation>} groups : List of direct memberships where
 * you are the member.
 */
function groupsAppGetGroups() {
  const myEmail = Session.getActiveUser().getEmail();
  let pageToken = '';
  let membershipList = [];

  do {
    const queryParams = {
      query:`member_key_id=='${myEmail}'`,
      pageToken:pageToken
    };
    const searchResult = groups.Memberships.searchDirectGroups('groups/-', queryParams);
    membershipList = membershipList.concat(searchResult.memberships);
    pageToken = searchResult.nextPageToken;
  } while (pageToken);

  return membershipList;
}

Gruppenmethoden

Die folgenden Hilfsmethoden entsprechen denen der Klasse Group im Groups Service.

getEmail

/**
 * Gets a group's email address
 *
 * @param {Object} group: A group resource
 * @return {String} email: The email associated with the group resource.
 */
function getEmail(group) {
  return group.groupKey.id;
}

getGroups

Die folgende Methode verwendet Memberships.list, um alle Mitgliedschaften für die angegebene Gruppe abzurufen. Dazu können sowohl Mitgliedschaften von Nutzern als auch von Gruppen gehören.

Um die Methode getGroups des Groups Service besser nachzubilden, können wir Mitgliedschaften nach ihrem Typefiltern. Sie können auf dieses Feld zugreifen, indem Sie entweder eine FULL View als Abfrageparameter für Memberships.list angeben oder für jede angegebene Mitgliedschaft eine einzelne Memberships.lookup -Abfrage ausführen.

/**
 * Fetch a list of memberships with provided group as its parent
 *
 * @param {Group} group: A group resource
 * @return {Array<Membership>} membershipList: The memberships where the parent
 * is the provided group and member is a also a group.
 */
function getGroups(group) {
  let membershipList = [];
  let pageToken = '';

  do {
    // Fetch a page of memberships
    const queryParams = {
      view: 'FULL',
      pageToken: pageToken
    }
    const response = groups.Memberships.list(group.name, queryParams);

    // Filter non-group memberships
    const onlyGroupMemberships = response.memberships.filter(
      membership => membership.type == 'GROUP'
    );
    membershipList = membershipList.concat(onlyGroupMemberships);

    // Set up next page
    pageToken = response.nextPageToken;
  } while(pageToken);

  return membershipList;
}

getRole und getRoles

Während der Groups Service mit getRole möglicherweise nur die Rolle mit der höchsten Priorität zurückgegeben hat, enthält das Feld roles in einer Mitgliedschaftsressource ein separates Element für jede Rolle, für die das Mitglied infrage kommt (z. B. MEMBER, OWNER, ADMIN).

/**
 * Retrieve the membership roles of a member to a group.
 *
 * @param {Group} containingGroup: The group whom the member belongs to
 * @param {String} email: The email address associated with a member that
 * belongs to the containingGroup
 * @return {Array<Role>} roles: List of roles the member holds with respect to
 * the containingGroup.
 */
function getRoleWithEmail(containingGroup, email) {
  // First fetch the membership
  const membershipName = groups.Memberships.lookup(containingGroup.name, { 'memberKey.id': email }).name;
  const membership = groups.Memberships.get(membershipName);

  // Then retrieve the role
  return membership.roles;
}

/**
 * Retrieve the membership roles of a member to a group.
 *
 * @param {Group} containingGroup: The group resource whom the member belongs to
 * @param {User} user: The user associated with a member that belongs to the
 * containingGroup
 * @return {Array<Role>} roles: List of roles the member holds with respect to
 * the containingGroup
 */
function getRoleWithUser(containingGroup, user) {
  return getRoleWithEmail(containingGroup, user.getEmail());
}

/**
 * Retrieve the membership roles of a group of members to a group
 *
 * @param {Group} containingGroup: The group resource to which roles are
 * relevant
 * @param {Array<User>} users: List of users to fetch roles from
 * @return {Array<Array<Role>>} roles: A list where every element is a list of
 * roles of member to the containingGroup
 */
function getRoles(containingGroup, users) {
  let roles = [];
  for (const user of users) {
    roles.push(getRoleWithUser(containingGroup, user));
  }
  return roles;
}

getUsers

Ähnlich wie bei getGroups können wir die Mitgliedschaften einer Gruppe mit Memberships.list abrufen und die Ergebnisse filtern, um nur den gewünschten Type zu behalten.

/**
 * Given a group, retrieve its direct members and banned members of the group
 * that have a known corresponding Google Account.
 *
 * @param {Group} group: The group Resource whom the users being queried belong
 * to
 * @return {Array<String>} users: A list of emails associated with members of
 * the given group
 */
function getUsers(group) {
  let userList = [];
  let pageToken = '';

  do {
    // Fetch a page of memberships from the group
    const queryParams = {
      view: 'FULL',
      pageToken: pageToken
    }
    const listResponse = groups.Memberships.list(group.name, queryParams);

    // Filter non-users and keep member emails
    const users = listResponse.memberships
      .filter(membership => membership.type == 'USER')
      .map(membership => membership.preferredMemberKey.id);
    userList = userList.concat(users);

    // Prepare next page
    pageToken = listResponse.nextPageToken;
  } while (pageToken);

  return userList;
}

hasGroup und hasUser

Sowohl hasGroup als auch hasUser im Groups Service bestätigen, ob eine Entität Mitglied einer bestimmten Gruppe ist. Da sowohl eine Gruppe als auch ein Nutzer durch eine E‑Mail-Adresse dargestellt werden können, kann mit der folgenden Methode bestätigt werden, ob eine der beiden zu einer bestimmten Gruppe gehört.

/**
 * Tests if the given email has an associated direct member to the given group.
 *
 * @param {Group} group: Group resource to which the entity is checked as
 * a member
 * @param {String} email: Email that can represent a Group or User entity
 * @return {Boolean} isMember: Whether the entity is a direct member to the
 * group or not
 */
function checkDirectGroupMembership(group, email) {
  try {
    groups.Memberships.lookup(group.name, {'memberKey.id': email});

  } catch(e) {
    // Log failure if exception is not related to membership existence
    if (!e.message.includes('Membership does not exist.')) {
      console.error(e);
    }
    return false;
  }
  return true;
}