進階 Cloud Identity 群組服務

您可以使用進階 Cloud Identity Groups (CIG) 服務，在 Apps Script 中使用 CIG API。

參考資料

如要進一步瞭解這項服務，請參閱 CIG API 的參考說明文件。與 Apps Script 中的所有進階服務一樣，進階 CIG 服務使用的物件、方法和參數都與公開 API 相同。詳情請參閱「如何判斷方法簽章」。

程式碼範例

下列輔助函式使用 API 的v1 版。

建立群組

如要建立 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：要列出成員的群組數值 ID。如要找出單一群組的 ID，請使用 groups.lookup 方法。如要查看特定客戶或命名空間下的所有群組 ID，請使用 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);
  }
}