سرویس پیشرفته Cloud Identity Groups

سرویس پیشرفته گروه‌های هویت ابری (CIG) به شما امکان می‌دهد از API CIG در Apps Script استفاده کنید.

توجه: این یک سرویس پیشرفته است که قبل از استفاده باید فعال شود.

مرجع

برای اطلاعات دقیق در مورد این سرویس، به مستندات مرجع برای API CIG مراجعه کنید. مانند تمام سرویس‌های پیشرفته در Apps Script، سرویس پیشرفته CIG از همان اشیاء، روش‌ها و پارامترهای API عمومی استفاده می‌کند. برای اطلاعات بیشتر، به بخش «نحوه تعیین امضاهای روش» مراجعه کنید.

کد نمونه

توابع کمکی زیر از نسخه v1 این API استفاده می‌کنند.

ایجاد یک گروه

برای ایجاد یک گروه گوگل، groups.create را با نمونه‌ای از منبع گروه جدید فراخوانی کنید. نمونه گروه باید شامل groupKey ، parent و label تنظیم شده روی cloudidentity.googleapis.com/groups.discussion_forum باشد. همچنین باید پارامتر initialGroupConfig را تنظیم کنید که مالک اولیه گروه را تعریف می‌کند. می‌توانید از مقادیر زیر برای این پارامتر استفاده کنید:

WITH_INITIAL_OWNER : شخصی که درخواست را ارسال می‌کند، مالک گروه می‌کند.

EMPTY : گروهی بدون مالک اولیه ایجاد می‌کند. فقط در صورتی می‌توانید از این مقدار استفاده کنید که مدیر ارشد Google Workspace یا مدیر گروه‌ها باشید. برای اطلاعات بیشتر در مورد نقش‌های 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);
  }
}

جستجوی گروه

برای جستجوی یک گروه گوگل، 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);
  }
}