콘텐츠로 이동

조회



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 없음)

curl --get '<Endpoint>/api/v1/workspace/member_group/get' \
  -H 'DF-API-KEY: <DF-API-KEY>'
{
  "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를 보관하여 지원팀에 문의합니다.

문서 평가

이 페이지가 도움이 되었나요?