Directory API:群組成員

新增群組成員

如要將成員新增至群組,請使用下列 POST 要求,並附上授權要求中所述的授權。可以是使用者或其他群組。groupKey 是新成員的群組電子郵件地址,或是群組的專屬 id。如需要求和回應屬性,請參閱 API 參考資料

POST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members

如果你將某個群組新增為其他群組的成員,最多可能需要 10 分鐘的時間,下層群組的成員才會成為上層群組的成員。再者,API 針對群組成員的循環傳回錯誤。舉例來說,如果 group1 是 group2 的成員,group2 就不得是 group1 成員。

JSON 要求

下列 JSON 要求顯示了建立群組成員的範例要求主體。成員的電子郵件地址為 liz@example.com,成員在群組中的角色則為 MEMBERPOST 要求會為 groupKey 使用 NNNNN:

POST https://admin.googleapis.com/admin/directory/v1/groups/NNNNN/members
{
   "email": "liz@example.com",
    "role": "MEMBER"
}

群組成員的role可以是:

  • OWNER:這個角色可以傳送訊息至群組、新增或移除成員、變更成員角色、變更群組設定,以及刪除群組。OWNER必須是群組成員。
  • MANAGER:您必須先透過管理控制台啟用 Google Workspace,才能使用這個角色。「管理員」角色可以執行「擁有者」角色所做的一切操作,但無法將成員設為「擁有者」或刪除群組。一個群組可以有多位「OWNER」成員和「管理員」。
  • MEMBER:這個角色可以訂閱群組、查看討論封存檔,以及檢視群組的成員清單。如要進一步瞭解成員角色,請參閱管理說明中心

JSON 回應

成功的回應會傳回 HTTP 200 狀態碼和會員身分資訊。id 是成員的專屬會員 ID:

{
   "kind": "directory#member",
   "id": "group member's unique ID",
   "email": "liz@example.com",
   "role": "MEMBER",
   "type": "GROUP"
  }

群組成員的type可以是:

  • GROUP - 成員是另一個群組。
  • MEMBER - 該成員是使用者

更新群組成員

如要更新群組成員,請使用下列 PUT 要求,並附上「授權要求」中所述的授權。groupKey 是群組的電子郵件地址或群組專屬的 id,而 memberKey 是使用者或群組的主要電子郵件地址、使用者的別名電子郵件地址或使用者的專屬 id。如需要求和回應屬性,請參閱 API 參考資料

PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members/memberKey
敬上

JSON 要求

以下 JSON 要求範例顯示會更新群組成員設定的範例要求主體。成員的電子郵件地址為 liz@example.com,群組成員的角色已從 MEMBER 變更為 MANAGER。在本例中,PUT 要求的 groupKey 是 NNNNN。如需 MEMBER、OWNER 和 MANAGER 角色的相關資訊,請參閱管理說明中心

PUT https://admin.googleapis.com/admin/directory/v1/groups/NNNNN/members/liz@example.com
{
   "email": "liz@example.com",
    "role": "MANAGER"
}

JSON 回應

成功的回應會傳回 HTTP 200 狀態碼和更新的成員資格資訊。id 是成員的專屬會員 ID:

{
   "kind": "directory#member",
   "id": "group member's unique ID",
   "email": "liz@example.com",
   "role": "MANAGER",
   "type": "GROUP"
  }

擷取群組成員

如要擷取群組成員,請使用下列 GET 要求,並附上「授權要求」中所述的授權。groupKey 是群組的電子郵件地址或群組專屬的 id,而 memberKey 是使用者或群組的主要電子郵件地址、使用者的別名電子郵件地址或使用者的專屬 id。如需要求和回應屬性,請參閱 API 參考資料

GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members/memberKey

JSON 回應

成功的回應會傳回 HTTP 200 狀態碼和會員身分資訊。id 是成員的專屬會員 ID:

{
   "kind": "directory#member",
   "id": "group member's unique ID",
   "email": "liz@example.com",
   "role": "MANAGER",
   "type": "GROUP"
  }

擷取所有群組成員

如要擷取所有群組成員,請使用下列 GET 要求,並納入「授權要求」中所述的授權。groupKey 是群組的電子郵件地址或群組的專屬 id。選用的 roles 查詢字串是一項篩選條件,可用來依角色擷取群組成員,而產生的角色集合會依照 roles 篩選器中的指定順序顯示。如需要求和回應屬性的相關資訊,請參閱 API 參考資料。為了方便閱讀,這個範例使用了一行回傳:

GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members
?pageToken=pagination token
&roles=one or more of OWNER,MANAGER,MEMBER separated by a comma
&maxResults=maximum results per response page

所有成員都會按照成員的字母順序傳回電子郵件地址。並針對具有大量成員的回應使用 pageToken 查詢字串。如果是分頁,回應會傳回 nextPageToken 屬性,該屬性含有用於後續回應結果頁面的符記。下一個要求會使用這個權杖做為 pageToken 查詢字串值。

JSON 回應

成功的回應會傳回 HTTP 200 狀態碼和成員資訊清單。id 是成員的專屬會員 ID。這個回應中有 nextPageToken 的後續群組成員清單:

{
   "kind": "directory#members",
   "members": [
   {
    "kind": "directory#member",
    "id": "group member's unique ID",
    "email": "liz@example.com",
    "role": "MANAGER",
    "type": "USER"
   },
   {
    "kind": "directory#member",
    "id": "group member's unique ID",
    "email": "radhe@example.com",
    "role": "MANAGER",
    "type": "USER"
   }
  ],
   "nextPageToken": "NNNNN"
}

刪除群組中的成員資格

如要刪除群組中的成員身分,請使用下列 DELETE 要求,並附上授權要求中所述的授權。groupKey 是群組專屬的idmemberKey 是遭到刪除的使用者或群組成員的主要電子郵件地址,或是使用者的專屬 id。如需要求和回應屬性,請參閱 API 參考資料

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members/memberKey
敬上 舉例來說,這個 DELETE 要求會刪除 groupKey 為 nnn,且 memberKey 是使用者的主要電子郵件地址 liz@example.com 的成員:
DELETE https://admin.googleapis.com/admin/directory/v1/groups/nnnn/members/liz@example.com

成功的回應會傳回 HTTP 200 狀態碼

刪除成員後:

  • 成員一經移除,即無法再收到寄送至群組的電子郵件。
  • 從群組中移除成員並不會刪除該使用者的帳戶。
  • 即使您刪除群組擁有者,該群組仍然能夠正常運作。管理員可以管理群組,或是將擁有權指派給其他群組成員