שירות מתקדם של Cloud Identity Groups

השירות המתקדם של Cloud Identity Groups ‏ (CIG) מאפשר להשתמש ב-CIG API ב-Apps Script.

הערה: זהו שירות מתקדם שצריך להפעיל לפני שמשתמשים בו.

חומרי עזר

למידע מפורט על השירות הזה, ראו את מאמרי העזרה של CIG API. כמו כל השירותים המתקדמים ב-Apps Script, גם בשירות המתקדם של CIG נעשה שימוש באותם אובייקטים, שיטות ופרמטרים כמו ב-API הציבורי. למידע נוסף, ראו איך נקבעות חתימות השיטות.

קוד לדוגמה

פונקציות העזר הבאות משתמשות בגרסה v1 של ה-API.

צור קבוצה

כדי ליצור קבוצת Google, צריך להפעיל את הפונקציה 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);
  }
}

חיפוש קבוצה

כדי לחפש קבוצת 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);
  }
}

אחזור של חברויות ממנויים

משתמשים ב-method‏ 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);
  }
}