خدمة Cloud Identity Groups المتقدّمة

الوصول إلى واجهة برمجة التطبيقات CIG في "برمجة التطبيقات"

تتيح لك خدمة "مجموعات Cloud Identity" المتقدّمة استخدام CIG API في Google Apps Script.

هذه خدمة متقدّمة يجب تفعيلها قبل الاستخدام.

مراجع

للحصول على معلومات تفصيلية عن هذه الخدمة، يُرجى الاطّلاع على المستندات المرجعية الخاصة بـ CIG API. مثل جميع الخدمات المتقدّمة في Apps Script، تستخدم خدمة CIG المتقدّمة العناصر والطرق والمعلَمات نفسها التي تستخدمها واجهة برمجة التطبيقات العامة. لمزيد من المعلومات، اطّلِع على كيفية تحديد التواقيع.

نموذج التعليمات البرمجية

تستخدم دوال المساعدة التالية الإصدار 1 من واجهة برمجة التطبيقات.

إنشاء مجموعة

لإنشاء مجموعة Google، استخدِم طريقة groups.create مع مثيل لمورد المجموعة الجديد. يجب أن يتضمّن مثيل المجموعة groupKey وparent وlabel تم ضبطها على cloudidentity.googleapis.com/groups.discussion_forum. عليك أيضًا ضبط المَعلمة initialGroupConfig التي تحدّد المالك الأوّلي للمجموعة. يمكنك استخدام القيم التالية لهذه المَعلمة:

WITH_INITIAL_OWNER: يجعل هذا الخيار الشخص الذي يرسل الطلب مالكًا للمجموعة.

‫EMPTY: لإنشاء مجموعة بدون مالكين أوليين لا يمكنك استخدام هذه القيمة إلا إذا كنت مشرفًا متميّزًا في Google Workspace أو مشرفًا في "مجموعات Google". لمزيد من المعلومات حول أدوار Google Workspace، يُرجى الاطّلاع على أدوار المشرفين المُعدّة مسبقًا.

يوضّح المثال التالي كيفية إنشاء مجموعة يكون فيها المستخدم هو مالك المجموعة:

const groups = CloudIdentityGroups.Groups;

function createGroup(groupId, parentId, displayName) {
  const groupKey = { id: groupId };
  const group = {
    parent: "customerId/" + parentId,
    displayName: displayName,
    groupKey: groupKey,
    // Set the label to specify creation of a Google Group.
    labels: { "cloudidentity.googleapis.com/groups.discussion_forum": "" },
  };
  const optionalArgs = { initialGroupConfig: "WITH_INITIAL_OWNER" };

  try {
    const response = groups.create(group, optionalArgs);
    console.log(response);
  } catch (error) {
    console.error(error);
  }
}

البحث عن مجموعة

للبحث عن مجموعة Google، اتّصِل بـ groups.search باستخدام سلسلة طلب بحث. للبحث عن جميع المجموعات، قدِّم label cloudidentity.googleapis.com/groups.discussion_forum.

const groups = CloudIdentityGroups.Groups;

function searchGroup(customer_id) {
  const search_query = `parent=='customerId/${customer_id}' && 'cloudidentity.googleapis.com/groups.discussion_forum' in labels`;
  const search_group_request = groups.search({ query: search_query });
  console.log(JSON.stringify(search_group_request));
}

إضافة عضوية إلى مجموعة

بعد إنشاء مجموعة، يمكنك إنشاء عضويات لها. تتطلّب هذه الطريقة membership مرجعًا وسلسلة المرجع name الخاصة بالوالد. يمكن الحصول على القيمة السابقة من خلال البحث عن المجموعة باستخدام طريقة lookup.

تعرض طريقة المساعدة التالية مثالاً على إضافة عضوية إلى مجموعة. ‫expiryDetail هو حقل اختياري يمكن إضافته لضبط تاريخ انتهاء صلاحية العضوية. قيمة preferredMemberKey هي عنوان البريد الإلكتروني الخاص بالعضو.

const groups = CloudIdentityGroups.Groups;

function createMembership(namespace, groupId, memberKey) {
  try {
    // Given a group ID and namespace, retrieve the ID for parent group
    const groupLookupResponse = groups.lookup({
      'groupKey.id': groupId,
      'groupKey.namespace': namespace
    });
    const groupName = groupLookupResponse.name;

    // Create a membership object with a memberKey and a single role of type MEMBER
    const membership = {
      preferredMemberKey: { id: memberKey },
      roles: [
        {
          name: "MEMBER",
          expiryDetail: {
            expireTime: "2025-10-02T15:01:23Z",
          },
        },
      ],
    };

    // Create a membership using the ID for the parent group and a membership object
    const response = groups.Memberships.create(membership, groupName);
    console.log(JSON.stringify(response));
  } catch (e) {
    console.error(e);
  }
}

الحصول على عضويات من عضو

استخدِم طريقة groups.memberships.searchDirectGroups للبحث عن الآباء المباشرين لأحد الأعضاء.

يوضّح المثال التالي طريقة مساعدة لتكرار العضويات المباشرة لعضو معيّن.

const groups = CloudIdentityGroups.Groups;

 function searchMemberMemberships(memberId, pageSize) {
  try {
    let memberships = [];
    let nextPageToken = '';
    const withinParent = 'groups/-';  // This parameter sets the scope as "all groups"

    do {
      // Get page of memberships
      const queryParams = {
        query: `member_key_id == \'${memberId}\'`,
        page_size: pageSize,
        page_token: nextPageToken,
      };
      const response = groups.Memberships.searchDirectGroups(withinParent, queryParams);
      memberships = memberships.concat(response.memberships);

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

    return memberships;
  } catch(e) {
    console.error(e);
  }
}

الحصول على عضويات من مجموعة

استخدِم طريقة groups.memberships.list لسرد أعضاء مجموعة.

groupId: المعرّف الرقمي للمجموعة التي تريد عرض أعضائها. للعثور على معرّف مجموعة واحدة، استخدِم طريقة groups.lookup. للاطّلاع على جميع أرقام تعريف المجموعات ضمن عميل أو مساحة اسم، استخدِم طريقة groups.list.

const groups = CloudIdentityGroups.Groups;

function listGroupMemberships(groupId, pageSize) {
  try {
    let membershipList = [];
    let nextPageToken = '';

    // Get group name
    const groupName = groups.lookup({'groupKey.id': groupId}).name;

    do {
      // Get page of memberships
      const queryParams = {
        pageSize: pageSize,
        pageToken: nextPageToken
      }
      const response = groups.Memberships.list(groupName, queryParams);
      membershipList = membershipList.concat(response.memberships);

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

    return membershipList;
  } catch (error) {
    console.error(error);
  }
}