Directory API: Thành viên nhóm
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Thêm thành viên vào nhóm
Để thêm thành viên vào một nhóm, hãy sử dụng yêu cầu POST sau đây và thêm quyền uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. Thành viên của một nhóm có thể là một người dùng hoặc một nhóm khác. groupKey là địa chỉ email của nhóm của thành viên mới hoặc id duy nhất của nhóm. Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API:
POST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members
Nếu bạn thêm một nhóm làm thành viên của một nhóm khác, thì có thể mất tối đa 10 phút thì các thành viên của nhóm con mới xuất hiện với tư cách là thành viên của nhóm mẹ. Ngoài ra, API sẽ trả về lỗi cho các chu kỳ trong gói thành viên nhóm. Ví dụ: nếu group1 là thành viên của group2, thì group2 không thể là thành viên của group1.
Yêu cầu JSON
Yêu cầu JSON sau đây cho thấy nội dung yêu cầu mẫu để tạo thành viên nhóm. Địa chỉ email của thành viên là liz@example.com và vai trò của thành viên trong nhóm là MEMBER. Yêu cầu POST sử dụng NNNNN cho groupKey:
POST https://admin.googleapis.com/admin/directory/v1/groups/NNNNN/members
{
"email": "liz@example.com",
"role": "MEMBER"
}
role của thành viên trong nhóm có thể là:
OWNER – Vai trò này có thể thay đổi chế độ gửi thư đến nhóm, thêm hoặc xoá thành viên, thay đổi vai trò của thành viên, thay đổi chế độ cài đặt của nhóm và xoá nhóm. OWNER phải là thành viên của nhóm.
MANAGER – Vai trò này chỉ có sẵn nếu bạn bật Google Workspace bằng Bảng điều khiển dành cho quản trị viên. Vai trò NGƯỜI QUẢN LÝ có thể làm mọi việc mà vai trò CHỦ SỞ HỮU có thể làm, ngoại trừ việc chỉ định thành viên làm CHỦ SỞ HỮU hoặc xoá nhóm. Một nhóm có thể có nhiều thành viên CHỦ SỞ HỮU và NGƯỜI QUẢN LÝ.
MEMBER – Vai trò này có thể đăng ký theo dõi một nhóm, xem bản lưu trữ cuộc thảo luận và xem danh sách thành viên của nhóm. Để biết thêm thông tin về vai trò của thành viên, hãy xem trung tâm trợ giúp dành cho quản trị viên.
Nội dung phản hồi JSON
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 và thông tin thành viên của người dùng. id là mã thành viên duy nhất của thành viên:
{
"kind": "directory#member",
"id": "group member's unique ID",
"email": "liz@example.com",
"role": "MEMBER",
"type": "GROUP"
}
type của thành viên trong nhóm có thể là:
GROUP – Thành phần là một nhóm khác.MEMBER – Thành viên là người dùng
Cập nhật tư cách thành viên nhóm
Để cập nhật tư cách thành viên của một nhóm, hãy sử dụng yêu cầu PUT sau đây và thêm thông tin uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. groupKey là địa chỉ email của nhóm hoặc id duy nhất của nhóm, còn memberKey là địa chỉ email chính của người dùng hoặc nhóm, địa chỉ email đại diện của người dùng hoặc id duy nhất của người dùng. Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API:
PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members/memberKey
Yêu cầu JSON
Yêu cầu JSON sau đây cho thấy nội dung yêu cầu mẫu cập nhật chế độ cài đặt tư cách thành viên trong nhóm. Địa chỉ email của thành viên là liz@example.com và vai trò của thành viên trong nhóm được thay đổi từ MEMBER thành MANAGER. groupKey của yêu cầu PUT trong ví dụ này là NNNNN. Để biết thông tin về vai trò THÀNH VIÊN, CHỦ SỞ HỮU và QUẢN LÝ, hãy xem trung tâm trợ giúp dành cho quản trị viên:
PUT https://admin.googleapis.com/admin/directory/v1/groups/NNNNN/members/liz@example.com
{
"email": "liz@example.com",
"role": "MANAGER"
}
Nội dung phản hồi JSON
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 và thông tin thành viên đã cập nhật. id là mã thành viên duy nhất của thành viên:
{
"kind": "directory#member",
"id": "group member's unique ID",
"email": "liz@example.com",
"role": "MANAGER",
"type": "GROUP"
}
Truy xuất thành viên của một nhóm
Để truy xuất tư cách thành viên của một nhóm, hãy sử dụng yêu cầu GET sau đây và thêm thông tin uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. groupKey là địa chỉ email của nhóm hoặc id duy nhất của nhóm, còn memberKey là địa chỉ email chính của người dùng hoặc nhóm, địa chỉ email đại diện của người dùng hoặc id duy nhất của người dùng. Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API:
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members/memberKey
Nội dung phản hồi JSON
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 và thông tin thành viên của người dùng. id là mã thành viên duy nhất của thành viên:
{
"kind": "directory#member",
"id": "group member's unique ID",
"email": "liz@example.com",
"role": "MANAGER",
"type": "GROUP"
}
Truy xuất tất cả thành viên trong nhóm
Để truy xuất tất cả thành viên trong nhóm, hãy sử dụng yêu cầu GET sau đây và thêm thông tin uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. groupKey là địa chỉ email của nhóm hoặc id duy nhất của nhóm. Chuỗi truy vấn roles (không bắt buộc) là một bộ lọc cho phép bạn truy xuất thành viên nhóm theo vai trò và các tập hợp vai trò thu được sẽ theo thứ tự được cung cấp trong bộ lọc roles. Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API. Để dễ đọc, ví dụ này sử dụng các dòng trả về:
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
Tất cả thành viên được trả về theo thứ tự bảng chữ cái của địa chỉ email của thành viên. Và sử dụng chuỗi truy vấn pageToken cho các phản hồi có số lượng thành viên lớn. Trong trường hợp phân trang, phản hồi sẽ trả về thuộc tính nextPageToken có mã thông báo cho trang tiếp theo của kết quả phản hồi. Yêu cầu tiếp theo của bạn sẽ sử dụng mã thông báo này làm giá trị chuỗi truy vấn pageToken.
Nội dung phản hồi JSON
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 và danh sách thông tin thành viên. id là mã thành viên duy nhất của thành viên. Có một nextPageToken cho danh sách tiếp theo của các thành viên trong nhóm trong phản hồi này:
{
"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"
}
Xoá tư cách thành viên trong nhóm
Để xoá tư cách thành viên của một thành viên trong nhóm, hãy sử dụng yêu cầu DELETE sau đây và thêm thông tin uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. groupKey là id duy nhất của nhóm và memberKey là địa chỉ email chính của người dùng hoặc thành viên nhóm đã bị xoá hoặc id duy nhất của người dùng. Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API.:
DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/members/memberKey
Ví dụ: yêu cầu DELETE này sẽ xoá thành viên có groupKey là nnn và memberKey là địa chỉ email chính của người dùng, liz@example.com:
DELETE https://admin.googleapis.com/admin/directory/v1/groups/nnnn/members/liz@example.com
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200.
Khi một thành viên bị xoá:
- Những thành viên mà bạn xoá sẽ không nhận được email gửi đến nhóm nữa.
- Việc xoá một thành viên khỏi nhóm sẽ không xoá tài khoản của người dùng đó.
- Nếu bạn xoá chủ sở hữu nhóm, nhóm vẫn hoạt động bình thường. Với tư cách là quản trị viên, bạn có thể quản lý nhóm hoặc chỉ định quyền sở hữu cho một thành viên khác trong nhóm
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-08-29 UTC.
[null,null,["Cập nhật lần gần đây nhất: 2025-08-29 UTC."],[],[],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"]]
