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

تتيح لك خدمة Cloud Identity Groups (CIG) المتقدّمة استخدام الـ CIG API في برمجة تطبيقات Google.

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

مراجع

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