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

تتيح لك خدمة Cloud Identity Groups (CIG) المتقدّمة استخدام واجهة برمجة تطبيقات CIG API في 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);
  }
}