進階 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: "EMPTY" };

  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);
  }
}

從 Member 取得會籍

使用 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);
  }
}