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，并且该成员在群组中的角色为 MEMBER。POST 请求使用 NNNNN 作为 groupKey：
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 状态代码。
删除成员后：
- 您移除的成员将无法再收到发送给群组的电子邮件。
- 从群组中移除成员不会删除该用户的账号。
- 如果您删除群组所有者，群组仍能正常工作。作为管理员，您可以管理群组或将所有权分配给其他群组成员
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-29。
[null,null,["最后更新时间 (UTC)：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"]]
