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

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

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

مراجع

للحصول على معلومات مفصّلة حول هذه الخدمة، يُرجى الاطّلاع على المستندات المرجعية الخاصة بواجهة برمجة التطبيقات CIG. مثل جميع الخدمات المتقدّمة في "برمجة التطبيقات"، تستخدم خدمة 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);
  }
}