조회¶
GET /api/v1/workspace/member_group/get
개요¶
지정된 팀과 해당 팀의 선택된 멤버, 선택 가능한 멤버 및 역할을 조회하거나, 생성 시의 멤버 후보를 조회합니다.
호출 전 및 사용 단계¶
Query groupUUID는 팀 목록에서 가져옵니다. 유효한 UUID를 전달하면 팀 엔터티, groupMembers, membersNotInGroup, roleInfos를 반환합니다. 생략하거나 빈 문자열이면 생성 후보 구조를 반환하며, 엔터티 uuid, 이름 등의 필드는 포함하지 않고 모든 현재 유효한 멤버는 membersNotInGroup에 위치합니다. 이미 존재하지만 유효하지 않거나 워크스페이스를 떠난 멤버는 선택 가능한 멤버 정보로 반환되지 않습니다.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>발급 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 발급받습니다. |
Query 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| groupUUID | string | 선택 사항인 팀 UUID입니다. 생략하거나 빈 문자열이면 모든 선택 가능한 멤버를 가져옵니다. 예: group_example발급 또는 입력 방법: 팀 목록의 content[].uuid에서 팀 UUID를 가져옵니다. 새 팀의 멤버를 준비할 때는 생략할 수 있습니다. |
파라미터 추가 설명¶
수정 시 groupMembers[].uuid에서 accountUUIDs를 구성하고, roleInfos[].uuid에서 반환된 역할을 가져옵니다. 역할 요약에는 빈 팀의 기존 역할이 누락될 수 있으므로, 수정 전에 추가로 확인하여 []로 잘못 비우지 않도록 해야 합니다.
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/workspace/member_group/get' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode groupUUID=group_example
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | object | 팀 상세 또는 생성 후보입니다. 엔터티 필드는 유효한 groupUUID를 지정한 경우에만 존재합니다. |
| content.id | integer | 데이터베이스 레코드 번호이며, 작업에는 uuid를 사용합니다. |
| content.uuid | string | 팀 UUID입니다. |
| content.name | string | 팀 이름입니다. |
| content.workspaceUUID | string | 소속 워크스페이스 UUID입니다. |
| content.status | integer | 활성 팀은 0입니다. |
| content.creator | string | 생성 주체입니다. |
| content.updator | string | 수정 주체이며 비어 있을 수 있습니다. |
| content.createAt | integer | 생성 Unix 초입니다. |
| content.updateAt | integer | 엔터티 수정 시간(Unix 초)이며, 수정되지 않은 경우 -1입니다. 현재 수정 작업이 이 필드를 갱신한다고 보장할 수 없으므로 멤버/역할 변경 여부를 판단하는 데 사용할 수 없습니다. |
| content.deleteAt | integer | 삭제 Unix 초이며, 삭제되지 않은 경우 -1입니다. |
| content.groupMembers | array<object> |
팀에 여전히 유효한 멤버이며, 연결 생성 시간 내림차순으로 정렬됩니다. |
| content.membersNotInGroup | array<object> |
이 워크스페이스의 유효한 멤버 중 아직 이 팀에 가입하지 않은 후보입니다. |
| content.roleInfos | array<object> |
역할 요약입니다. 현재 멤버가 없는 팀은 비어 있게 표시될 수 있으므로, 이를 근거로 역할이 설정되지 않았다고 추론할 수 없습니다. |
| content.declaration | object 또는 null | 워크스페이스 공용 선언입니다. |
| content.groupMembers[].uuid | string | 멤버 계정 UUID입니다. |
| content.groupMembers[].name | string | 계정 표시 이름입니다. |
| content.groupMembers[].email | string | 계정 이메일입니다. |
| content.groupMembers[].acntWsNickname | string | 이 워크스페이스의 닉네임이며, 설정되지 않은 경우 빈 문자열입니다. |
| content.membersNotInGroup[].uuid | string | 멤버 계정 UUID입니다. |
| content.membersNotInGroup[].name | string | 계정 표시 이름입니다. |
| content.membersNotInGroup[].email | string | 계정 이메일입니다. |
| content.membersNotInGroup[].acntWsNickname | string | 이 워크스페이스의 닉네임이며, 설정되지 않은 경우 빈 문자열입니다. |
| content.roleInfos[].uuid | string | 역할 UUID 또는 내장 역할 식별자이며, roleUUIDs 요소로 사용할 수 있습니다. |
| content.roleInfos[].name | string | 역할 표시 이름입니다. |
{
"code": 200,
"content": {
"id": 42,
"uuid": "group_example",
"name": "프로덕션 운영",
"workspaceUUID": "wksp_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"groupMembers": [
{
"uuid": "acnt_example",
"name": "운영 멤버",
"email": "xxx@guance.com",
"acntWsNickname": ""
}
],
"membersNotInGroup": [],
"roleInfos": [
{
"uuid": "role_example",
"name": "운영 읽기 전용"
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
새 팀 후보 호출(groupUUID 없음)
{
"code": 200,
"content": {
"groupMembers": [],
"membersNotInGroup": [
{
"uuid": "acnt_example",
"name": "운영 멤버",
"email": "xxx@guance.com",
"acntWsNickname": ""
}
],
"roleInfos": [],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공용 요청 오류는 공용 오류 정의를 참조하세요.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 선언되지 않은 Query 파라미터를 사용했거나 파라미터가 규칙을 위반함 | 파라미터 파싱 실패 | Query 파라미터 표와 예시를 확인합니다. |
| 404 | ft.MemberGroupNoExists | 대상 팀이 존재하지 않거나, 삭제되었거나, 이 워크스페이스에 속하지 않음 | 팀이 존재하지 않음 | 팀 목록에서 활성 팀 UUID를 다시 복사합니다. |
| 500 | ft.InternalServerError | 팀 또는 멤버 정보 조회 실패 | 내부 오류 | UUID를 확인하고 traceId를 보관하여 지원팀에 문의합니다. |