نقل البيانات من خدمة "مجموعات Google" إلى خدمة "مجموعات Cloud Identity" المتقدّمة

تقدّم خدمة Cloud Identity Groups (CIG) المتقدّمة ميزات مماثلة لتلك المتوفّرة في Groups Service API ويمكن استخدامها بدلاً منها.

راجِع طرق المساعدة المتوفّرة للتعرّف على كيفية تحقيق إمكانات مماثلة من خلال "الخدمة المتقدّمة" في CIG.

الإعداد

لاستخدام CIG Advanced Service، عليك أولاً تفعيلها ضمن مشروع النص البرمجي.

لاختصار بعض تواقيع الطرق في هذا الدليل، حدّدنا المتغير التالي:

const groups = CloudIdentityGroups.Groups;

طُرق GroupsApp

تتطابق طرق المساعدة التالية مع طرق خدمة المجموعات GroupsApp.

في هذا الدليل، يشير المصطلح مجموعة إلى مورد مجموعة، وليس إلى عنصر فئة مجموعة. موارد المجموعة هي عناصر JavaScript لا تتضمّن طرقًا، ولكن يمكن استخدامها في خدمة CIG المتقدّمة لاسترداد معلومات مشابهة لتلك الموجودة في عناصر فئة المجموعة.

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

تعرض طريقة المساعدة التالية قائمة بمراجع الاشتراك. يمكنك الوصول إلى الحقل group الخاص بأحد العناصر للعثور على رقم تعريف اسمه. ويُعدّ ذلك مفيدًا للعديد من طرق "الخدمة المتقدّمة" في CIG. وبالمثل، يمكنك الوصول إلى groupKey.id لأحد العناصر للعثور على عنوان بريده الإلكتروني.

/**
 * 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;
}

طُرق التجميع

تتطابق طرق المساعدة التالية مع طرق خدمة المجموعات Groups Class.

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

تستخدم الطريقة التالية Memberships.list، التي ستجلب كل عضوية في المجموعة المحدّدة. ويمكن أن يشمل ذلك عضويات المستخدمين والمجموعات.

لتقريب طريقة getGroups في "خدمة المجموعات" بشكل أفضل، يمكننا فلترة العضويات حسب Type. يمكننا الوصول إلى هذا الحقل من خلال تقديم FULL View كمَعلمة طلب بحث إلى Memberships.list أو من خلال تنفيذ Memberships.lookup فردي لكل عضوية محدّدة.

/**
 * 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 وgetRoles

في حين أنّ خدمة "مجموعات Google" قد تعرض فقط الدور الأعلى أولوية في getRole()، يحتوي الحقل roles في مورد العضوية على عنصر منفصل لكل دور يكون العضو مؤهلاً له (مثال: 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

على غرار نهجنا في getGroups، يمكننا استرداد عضويات المجموعة باستخدام Memberships.list وفلترة النتائج للاحتفاظ Type المستهدَف فقط.

/**
 * 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 وhasUser

تؤكّد كلّ من خدمة "المجموعات" hasGroup وhasUser ما إذا كان الكيان عضوًا في مجموعة معيّنة. بما أنّه يمكن تمثيل كل من المجموعة والمستخدم بعنوان بريد إلكتروني، يمكن استخدام الطريقة التالية لتأكيد ما إذا كان أي منهما ينتمي إلى مجموعة معيّنة.

/**
 * Tests if the given email has an associated direct member to the given group.
 *
 * @param {Group} group: Group resource to which the entity is being 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;
}