שירות מתקדם של 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);
  }
}

איך מקבלים חברות במועדון מחבר

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