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 요청은 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가 사용 설정된 경우에만 사용할 수 있습니다. MANAGER 역할은 회원을 소유자로 지정하거나 그룹을 삭제하는 작업을 제외하고 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는 그룹의 고유한 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 상태 코드가 반환됩니다.
회원이 삭제되면 다음과 같은 결과가 발생합니다.
- 삭제된 회원은 더 이상 그룹으로 전송되는 이메일을 받지 않게 됩니다.
- 그룹에서 회원을 삭제해도 사용자의 계정은 삭제되지 않습니다.
- 그룹 소유자를 삭제해도 그룹은 정상적으로 작동합니다. 관리자는 직접 그룹을 관리하거나 소유권을 다른 그룹 회원에게 할당할 수 있습니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-29(UTC)
[null,null,["최종 업데이트: 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"]]
