Directory API：群組成員
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
將成員新增至群組
如要將成員加入群組，請使用下列 POST 要求，並附上「授權要求」一節中所述的授權。群組成員可以是使用者或其他群組。groupKey 是新成員的群組電子郵件地址或群組專屬 id。如需要求和回應屬性的相關資訊，請參閱 API 參考資料：
POST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members
如果您將某個群組新增為另一個群組的成員，下層群組成員顯示為上層群組成員的時間可能會延遲最多 10 分鐘。此外，API 會針對群組成員資格中的循環傳回錯誤。舉例來說，如果群組 1 是群組 2 的成員，群組 2 就不能是群組 1 的成員。
JSON 要求
以下 JSON 要求顯示建立群組成員的示例要求主體。成員的電子郵件地址為 liz@example.com，在群組中的角色為 MEMBER。POST 要求會為 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 時，才能使用這個角色。管理員角色具備的權限和擁有者角色大致相同，差別只在於管理員無法將成員設為擁有者，也無法刪除群組。群組可以有多位擁有者和管理員成員。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。如要瞭解成員、擁有者和管理員角色，請參閱管理說明中心：
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 是群組的專屬 id，memberKey 則是已刪除的使用者或群組成員的主要電子郵件地址，或是使用者的專屬 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 狀態碼。
刪除成員後的影響：
- 您移除的成員將無法繼續收到傳送給該群組的電子郵件。
- 從群組中移除成員並不會刪除該使用者的帳戶。
- 刪除群組版主也不會影響群組的正常運作。管理員可以接管群組，或是將擁有權指派給其他群組成員
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-08-29 (世界標準時間)。
[null,null,["上次更新時間：2025-08-29 (世界標準時間)。"],[],[],null,["# Directory API: Group Members\n\n|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 1. [Add a member to a group](#create_member) 2. [Update a group membership](#update_member) 3. [Retrieve a group's member](#get_member) 4. [Retrieve all group members](#get_all_members) 5. [Delete membership in a group](#delete_member) |\n\nAdd a member to a group\n-----------------------\n\nTo add a member to a group, use the following `POST` request and include the authorization described in [Authorize requests](/workspace/admin/directory/v1/guides/authorizing). A group member can be a user or another group. The `groupKey` is the new member's group email address or the group's unique `id`. For the request and response properties, see the [API Reference](/workspace/admin/directory/v1/reference/members/insert): \n\n```\nPOST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members\n```\n\nIf you add a group as a member of another group, there may be a delay of up to 10 minutes before the child group's members appear as members of the parent group. In addtion, the API returns an error for cycles in group memberships. For example, if group1 is a member of group2, group2 cannot be a member of group1.\n\n### JSON request\n\nThe following JSON request shows a sample request body that creates a group member. The member's email address is liz@example.com and the member's role in the group is as a `MEMBER`. The `POST` request uses NNNNN for the `groupKey`: \n\n```\nPOST https://admin.googleapis.com/admin/directory/v1/groups/NNNNN/members\n``` \n\n```transact-sql\n{\n \"email\": \"liz@example.com\",\n \"role\": \"MEMBER\"\n}\n```\n\nA group member's `role` can be:\n\n- `OWNER` -- This role can change send messages to the group, add or remove members, change member roles, change group's settings, and delete the group. An `OWNER` must be a member of the group.\n- `MANAGER` -- This role is only available if the Google Workspace is enabled using the Admin console. A MANAGER role can do everything done by an OWNER role except make a member an OWNER or delete the group. A group can have multiple OWNER and MANAGER members.\n- `MEMBER` -- This role can subscribe to a group, view discussion archives, and view the group's membership list. For more information about member roles, see the [administration help center](http://support.google.com/a/bin/answer.py?answer=167094).\n\n\u003cbr /\u003e\n\n### JSON response\n\nA successful response returns an [HTTP 200 status code](http://wikipedia.org/wiki/List_of_HTTP_status_codes) and the member's membership information. The `id` is the member's unique membership ID: \n\n```carbon\n{\n \"kind\": \"directory#member\",\n \"id\": \"group member's unique ID\",\n \"email\": \"liz@example.com\",\n \"role\": \"MEMBER\",\n \"type\": \"GROUP\"\n }\n```\n\nA group member's `type` can be:\n\n- `GROUP` -- The member is another group.\n- `MEMBER` -- The member is a user\n\n\u003cbr /\u003e\n\nUpdate a group membership\n-------------------------\n\nTo update a group membership, use the following `PUT` request and include the authorization described in [Authorize requests](/workspace/admin/directory/v1/guides/authorizing). The `groupKey` is the group's email address or the group's unique `id`, and the `memberKey` is the user's or group's primary email address, a user's alias email address, or the user's unique `id`. For the request and response properties, see the [API Reference](/workspace/admin/directory/v1/reference/members/update): \n\n```\nPUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members/memberKey\n```\n| **Note:** The API also supports the [patch semantics](/workspace/admin/directory/v1/guides/performance#patch).\n\n### JSON request\n\nThe following JSON request shows a sample request body that updates a group membership settings. The member's email address is liz@example.com and the member's role in the group is changed from a `MEMBER` to a `MANAGER`. The `PUT` request's `groupKey` in this example is NNNNN. For information about the MEMBER, OWNER and MANAGER roles, see the [administration help center](http://support.google.com/a/bin/answer.py?answer=167094): \n\n```\nPUT https://admin.googleapis.com/admin/directory/v1/groups/NNNNN/members/liz@example.com\n``` \n\n```transact-sql\n{\n \"email\": \"liz@example.com\",\n \"role\": \"MANAGER\"\n}\n```\n\n### JSON response\n\nA successful response returns an [HTTP 200 status code](http://wikipedia.org/wiki/List_of_HTTP_status_codes) and the updated membership information. The `id` is the member's unique membership ID: \n\n```carbon\n{\n \"kind\": \"directory#member\",\n \"id\": \"group member's unique ID\",\n \"email\": \"liz@example.com\",\n \"role\": \"MANAGER\",\n \"type\": \"GROUP\"\n }\n```\n\nRetrieve a group's member\n-------------------------\n\nTo retrieve a group membership, use the following `GET` request and include the authorization described in [Authorize requests](/workspace/admin/directory/v1/guides/authorizing). The `groupKey` is the group's email address or the group's unique `id`, and the `memberKey` is the user's or group's primary email address, a user's alias email address, or the user's unique `id`. For the request and response properties, see the [API Reference](/workspace/admin/directory/v1/reference/members/get): \n\n```\nGET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members/memberKey\n```\n\n### JSON response\n\nA successful response returns an [HTTP 200 status code](http://wikipedia.org/wiki/List_of_HTTP_status_codes) and the member's membership information. The `id` is the member's unique membership ID: \n\n```carbon\n{\n \"kind\": \"directory#member\",\n \"id\": \"group member's unique ID\",\n \"email\": \"liz@example.com\",\n \"role\": \"MANAGER\",\n \"type\": \"GROUP\"\n }\n```\n\nRetrieve all group members\n--------------------------\n\nTo retrieve all group members, use the following `GET` request and include the authorization described in [Authorize requests](/workspace/admin/directory/v1/guides/authorizing). The `groupKey` is the group's email address or the group's unique `id`. The optional `roles` query string is a filter allowing you to retrieve group members by role and the resulting role collections are in the order given in the `roles` filter. For the request and response properties, see the [API Reference](/workspace/admin/directory/v1/reference/members/list). For readability, this example uses line returns: \n\n```\nGET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members\n?pageToken=pagination token\n&roles=one or more of OWNER,MANAGER,MEMBER separated by a comma\n&maxResults=maximum results per response page\n```\n\nAll members are returned in the alphabetical order of the members' email addresses. And use the `pageToken` query string for responses with large number of members. In the case of pagination, the response returns the `nextPageToken` property which has a token for the next page of response results. Your next request uses this token as the `pageToken` query string value.\n\n### JSON response\n\nA successful response returns an [HTTP 200 status code](http://wikipedia.org/wiki/List_of_HTTP_status_codes) and the list of member information. The `id` is the member's unique membership ID. There is a `nextPageToken` for the follow-on list of group members in this response: \n\n```carbon\n{\n \"kind\": \"directory#members\",\n \"members\": [\n {\n \"kind\": \"directory#member\",\n \"id\": \"group member's unique ID\",\n \"email\": \"liz@example.com\",\n \"role\": \"MANAGER\",\n \"type\": \"USER\"\n },\n {\n \"kind\": \"directory#member\",\n \"id\": \"group member's unique ID\",\n \"email\": \"radhe@example.com\",\n \"role\": \"MANAGER\",\n \"type\": \"USER\"\n }\n ],\n \"nextPageToken\": \"NNNNN\"\n}\n```\n\nDelete membership in a group\n----------------------------\n\nTo delete a member's membership in a group, use the following `DELETE` request and include the authorization described in [Authorize requests](/workspace/admin/directory/v1/guides/authorizing). The `groupKey` is the group's unique `id`, and `memberKey` is the deleted user or group member's primary email address or the user's unique `id`. For the request and response properties, see the [API Reference](/workspace/admin/directory/v1/reference/members/delete).: \n\n```\nDELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members/memberKey\n```\nFor example, this `DELETE` request deletes the member whose `groupKey` is nnn and whose `memberKey` is the user's primary email address, liz@example.com: \n\n```\nDELETE https://admin.googleapis.com/admin/directory/v1/groups/nnnn/members/liz@example.com\n```\n\nA successful response returns an [HTTP 200 status code](http://wikipedia.org/wiki/List_of_HTTP_status_codes).\n\nWhen a member is deleted:\n\n- Members you remove no longer receive email addressed to the group.\n- Removing a member from a group does not delete the user's account.\n- If you delete the group owner, the group still works normally. As an administrator, you can manage the group or assign ownership to another group member\n\n\u003cbr /\u003e"]]
