GET/groups

그룹 목록을 조회한다.

Authorization

oauth2

OAuth 2.0 인증.
자세한 인증 방식은 인가·인증를 참고한다.

Scope

directory
directory.read
group
group.read

HTTP Request

GEThttps://www.worksapis.com/v1.0/groups

Query Parameters

ParameterTypeDescription
domainId integer 

도메인 ID


example : 10000001
format : int32 
count integer 

조회 개수


default : 100
minimum : 1
maximum : 100
example : 100
format : int32 
cursor string 

커서값


example : JlIBsfJogXpzDGY8OscZziqZpYqCAu3RbZbaFzBb1od6lWQtSdPUd2FIdCuaGgu8DA== 

Header Parameters

HeadertypeDescription
Authorization string 

Bearer {token}


required 

Response

HTTP 200

OK

PropertyTypeDescription
groups array (Group) 

그룹 정보

 
responseMetaData object (responseMetaData) 

응답 메타데이터

 

Group

PropertyTypeDescription
domainId integer 

도메인ID


required
format : int32 
groupId string 

자동으로 부여되는 ID


readOnly : true 
groupName string 

그룹명. 도메인 내에서 유일해야 함.


required
maxLength : 100 
description string 

그룹 설명


maxLength : 300
nullable : true 
visible boolean 

그룹 공개 여부. 관리자, 구성원이 아닌 사용자의 검색 결과에도 노출할지 여부


default : true 
useServiceNotification boolean 

서비스 알림 발송 여부


default : false 
serviceManageable boolean 

그룹 관리자가 서비스 사용 여부를 변경할 수 있는지 여부


default : true 
groupExternalKey string 

그룹의 외부 키


maxLength : 100
nullable : true 
administrators array (GroupAdministrator) 

그룹의 관리자 목록


required
minItems : 1 
members array (GroupMember) 

그룹 구성원 목록


required 
useMessage boolean 

메시지방 사용 여부.

  • 네이버웍스 코어 상품만 사용 가능
  • false로 설정하면 30일 후 모든 구성원의 대화 기록 및 메시지방 기능(노트, 캘린더, 폴더, 할 일) 데이터가 삭제된다.
  • false로 설정한 후 30일 내에 다시 true로 설정하면 이전 데이터가 복구된다. 30일이 지난 후에 true로 설정하면 이전 데이터는 복구되지 않으며 새로운 메시지방이 생성된다.

default : false 
useNote boolean 

메시지방 노트 사용 여부.

  • false로 설정하면 노트 기능을 사용하지 않는다. 이전 데이터를 다시 확인하려면 이 파라미터를 true로 설정한다.
  • useMessage가 true일 때만 설정할 수 있다.

default : false 
useCalendar boolean 

메시지방 캘린더 사용 여부.

  • false로 설정하면 캘린더 기능을 사용하지 않는다. 이전 데이터를 다시 확인하려면 이 파라미터를 true로 설정한다.
  • useMessage가 true일 때만 설정할 수 있다.

default : false 
useTask boolean 

메시지방 할 일 사용 여부.

  • false로 설정하면 할 일 기능을 사용하지 않는다. 이전 데이터를 다시 확인하려면 이 파라미터를 true로 설정한다.
  • useMessage가 true일 때만 설정할 수 있다.

default : false 
useFolder boolean 

메시지방 폴더 사용 여부.

  • false로 설정하면 폴더 기능을 사용하지 않는다. 이전 데이터를 다시 확인하려면 이 파라미터를 true로 설정한다.
  • useMessage가 true일 때만 설정할 수 있다.

default : false 
useMail boolean 

그룹 메일 사용 여부.

  • 네이버웍스 코어 Standard, Standard Plus 상품만 사용 가능
  • 이 값이 true이면 groupEmail 항목도 필수로 입력해야 함.

default : false 
groupEmail string 

그룹 메일 주소(그룹 메일 사용 시).

  • localpart@domain 형식
  • localpart는 영문 소문자, 숫자, 느낌표(!) 또는 샵(#)으로 시작해야 한다.
  • 점(.)은 localpart의 시작과 끝에 사용할 수 없으며, 연속된 형태(..)로도 사용할 수 없다.
  • localpart는 2~64자의 영문 소문자, 숫자, 점(.), 하이픈(-), 밑줄(_), 느낌표(!), 샵(#)을 허용한다.

minItems : 0
maxLength : 90 
aliasEmails array (string) 

그룹 보조 메일 주소 목록(그룹 메일 사용 시).

  • 항목당 최대 90자
  • localpart@domain 형식
  • localpart는 영문 소문자, 숫자, 느낌표(!) 또는 샵(#)으로 시작해야 한다.
  • 점(.)은 localpart의 시작과 끝에 사용할 수 없으며, 연속된 형태(..)로도 사용할 수 없다.
  • localpart는 2~64자의 영문 소문자, 숫자, 점(.), 하이픈(-), 밑줄(_), 느낌표(!), 샵(#)을 허용한다.

minItems : 0
maxItems : 20 
canReceiveExternalMail boolean 

외부 메일 수신 여부(그룹 메일 사용 시).


default : false 
toExternalEmails array (string) 

그룹 메일을 수신할 외부 메일 주소 목록.
사내 메일 도메인의 메일 주소는 사용할 수 없음.


minItems : 0
maxItems : 500 
membersAllowedToUseGroupEmailAsRecipient array (GroupAllowedMember) 

그룹 메일 주소에 메일을 보낼 수 있는 구성원 지정(그룹 메일 사용 시).
지정된 구성원이 보낸 그룹 메일만 수신


minItems : 0 
membersAllowedToUseGroupEmailAsSender array (GroupAllowedMember) 

해당 그룹 메일 주소를 보내는 주소로 사용할 수 있는 구성원 목록(그룹 메일 사용 시).
그룹 관리자나 구성원인 경우만 지정 가능(아닌 경우 목록에서 제외됨)


minItems : 0 
useDynamicMembership boolean 

동적 멤버십 사용 여부

  • true로 설정 시 쿼리 조건에 따라 그룹 멤버가 자동으로 추가되거나 삭제된다.
  • 동적 멤버십을 사용할 경우 그룹 멤버가 자동으로 추가,삭제되므로 그룹 구성원으로 전달하는 members는 무시된다.

default : false 
dynamicMembership object (dynamicMembership) 

동적 멤버십

 

GroupAdministrator

PropertyTypeDescription
userExternalKey string 

구성원 외부 키


readOnly : true 
userId string 

구성원 ID
- 메일
- 리소스 ID
- 외부 키 "externalKey:{externalKey}" 형태


required 

GroupMember

PropertyTypeDescription
externalKey string 

구성원 외부 키


readOnly : true 
id string 

구성원,조직,그룹의 ID
구성원 ID는 다음을 지정 가능
- 메일
- 리소스 ID
- 외부 키 "externalKey:{externalKey}" 형태


required 
type string 

required
Allowed values : USER, ORGUNIT, GROUP 

GroupAllowedMember

PropertyTypeDescription
userExternalKey string 

구성원 외부 키


readOnly : true 
userId string 

구성원 ID
- 메일
- 리소스 ID
- 외부 키 "externalKey:{externalKey}" 형태


required 

dynamicMembership

PropertyTypeDescription
query string 

멤버십 쿼리.
쿼리 작성법은 개요를 참고한다.


maxLength : 10000 
excludeUserIds array (string) 

그룹에 포함하지 않을 구성원 ID 목록, 아래 유형으로 지정 가능

  • 메일
  • 리소스 ID
  • 외부 키 "externalKey:{externalKey}" 형태

minItems : 0 

responseMetaData

PropertyTypeDescription
nextCursor string 

다음 목록 조회 시 사용하는 커서값

 

Response Example

example

1{2  "groups": [3    {4      "domainId": 10000001,5      "groupId": "group127-8545-4463-603b-04d550d23bf",6      "groupName": "그룹1",7      "description": "도메인 그룹",8      "visible": true,9      "useServiceNotification": true,10      "serviceManageable": true,11      "groupExternalKey": "GROUP_EXT_01",12      "administrators": [13        {14          "userExternalKey": "USER_EXT_01",15          "userId": "userf7da-f82c-4284-13e7-030f3b4c756x"16        }17      ],18      "members": [19        {20          "externalKey": "USER_EXT_01",21          "id": "userf7da-f82c-4284-13e7-030f3b4c756x",22          "type": "USER"23        },24        {25          "externalKey": "ORGUNIT_EXT_01",26          "id": "orgunitf-f27f-4af8-27e1-03817a911417",27          "type": "ORGUNIT"28        },29        {30          "externalKey": "GROUP_EXT_01",31          "id": "group769-e656-477d-69c7-04e2f73a4a77",32          "type": "GROUP"33        }34      ],35      "useMessage": true,36      "useNote": true,37      "useCalendar": true,38      "useFolder": true,39      "useTask": true,40      "useMail": true,41      "groupEmail": "group01@example.com",42      "aliasEmails": [43        "alias@example.com"44      ],45      "canReceiveExternalMail": true,46      "toExternalEmails": [47        "external@example.com"48      ],49      "membersAllowedToUseGroupEmailAsRecipient": [50        {51          "userExternalKey": "USER_EXT_01",52          "userId": "userf7da-f82c-4284-13e7-030f3b4c756x"53        }54      ],55      "membersAllowedToUseGroupEmailAsSender": [56        {57          "userExternalKey": "USER_EXT_01",58          "userId": "userf7da-f82c-4284-13e7-030f3b4c756x"59        }60      ]61    },62    {63      "domainId": 10000001,64      "groupId": "groupa36-79c8-4858-6c23-041098774484",65      "groupName": "グループ2",66      "visible": false,67      "useServiceNotification": true,68      "serviceManageable": true,69      "groupExternalKey": "GROUP_EXT_02",70      "administrators": [71        {72          "userExternalKey": "USER_EXT_02",73          "userId": "user6362-21a9-1kbc-1234-126e09fcegd1"74        }75      ],76      "members": [77        {78          "externalKey": "USER_EXT_01",79          "id": "userf7da-f82c-4284-13e7-030f3b4c756x",80          "type": "USER"81        },82        {83          "externalKey": "ORGUNIT_EXT_02",84          "id": "orgunit7-f511-4757-6040-044af9c9742d",85          "type": "ORGUNIT"86        }87      ],88      "useMessage": true,89      "useNote": true,90      "useCalendar": true,91      "useFolder": true,92      "useTask": true,93      "useMail": true,94      "groupEmail": "group02@example.com",95      "aliasEmails": [96        "alias2@example.com"97      ],98      "canReceiveExternalMail": false,99      "useDynamicMembership": true,100      "dynamicMembership": {101        "query": "user.levelId == levelaa7-b824-4937-66af-042f1f43cefa",102        "excludeUserIds": [103          "userf7da-f82c-4284-13e7-030f3b4c756x"104        ]105      }106    }107  ],108  "responseMetaData": {109    "nextCursor": "JlIBsfJogXpzDGY8OscZziqZpYqCAu3RbZbaFzBb1od6lWQtSdPUd2FIdCuaGgu8DA=="110  }111}