목록 조회¶
GET /api/v1/mgroup/list
개요¶
사이트 백엔드 그룹을 페이지네이션으로 나열하며, 계정 및 워크스페이스 간 역할을 확장할 수 있습니다.
호출 전 준비 및 사용 단계¶
활성 그룹을 생성 시간 내림차순으로 반환합니다. 기본적으로 members 또는 refWorkspaces를 포함하지 않으며, 각각 showMembers, showRefWorkspace로 활성화합니다. 비활성화 시 해당 필드는 생략되며 빈 배열이 아닙니다. 멤버 요약에는 확인할 수 있는 계정만 포함되며, 계정 자체 상태가 활성으로 일괄 제한되지는 않습니다. 연결된 워크스페이스도 이미 삭제되었을 수 있으므로 각각의 status를 기준으로 판단하세요. 역할 요약은 더 이상 유효하지 않은 역할을 필터링합니다. 이 목록은 단일 워크스페이스의 팀 목록이 아니며, groupUUID 정확 조회를 제공하지 않습니다. 이름으로 검색한 뒤 반환된 uuid로 대상을 확인하세요.
요청 헤더¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 원본 경로 및 요청 본문 서명 버전입니다. 생략한 뒤 이 페이지의 알고리즘을 계속 사용할 수 없습니다. 예: v20240417확인 또는 입력 방법: 이 페이지의 예시는 이 고정 버전을 사용하며, 예시 서명 알고리즘과 함께 사용됩니다. |
|
| X-Df-Access-Key | string | Y | 읽기 API는 r 또는 w 자격 증명을 사용할 수 있고, 쓰기 API에는 w 자격 증명이 필요합니다. 예: <external-access-key>확인 또는 입력 방법: 사이트 관리자가 할당한 External API AK를 사용하며, 워크스페이스 OpenAPI Key는 사용할 수 없습니다. |
| X-Df-Nonce | string | Y | 임시 일련번호입니다. 실패 후 재전송할 때도 새 값을 생성하고 서명을 다시 계산합니다. 예: 97d275ee9f774315a7885ba7347acbd9확인 또는 입력 방법: 요청할 때마다 uuid.uuid4().hex를 새로 생성합니다. |
| X-Df-Signature | string | Y | 대문자 메서드, nonce, 원본 전체 경로, timestamp 및 원본 UTF-8 요청 본문을 공백으로 연결한 후 HMAC-SHA256을 수행하고 hex 다이제스트를 사용합니다. 예: <hmac-sha256-hex>확인 또는 입력 방법: External API 서명 인증에 따라 대응하는 SK로 계산하세요. 전체 실행 가능한 템플릿은 아래와 같습니다. |
| X-Df-Timestamp | string | Y | 사이트에 구성된 서명 유효 시간 범위 내에 있어야 하며, 예시 시간을 재사용할 수 없습니다. 예: 1785427200확인 또는 입력 방법: 전송 시 str(int(time.time()))를 사용하여 현재 Unix 초 문자열을 생성합니다. |
Query 요청 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| pageIndex | integer | 기본값 1, 최솟값 1입니다. null 허용: False $minValue: 1 예: 1확인 또는 입력 방법: 1부터 시작하며 content.pageInfo에 따라 후속 페이지로 진행합니다. |
|
| pageSize | integer | 기본값 20, 최댓값 1000입니다. null 허용: False $maxValue: 1000 $minValue: 1 예: 20확인 또는 입력 방법: 클라이언트 요구에 따라 1~1000을 선택하며, 멤버/워크스페이스를 확장할 때는 페이지당 수량을 제어하는 것이 좋습니다. |
|
| search | string | 선택 사항이며, 앞뒤 공백을 제거한 뒤 그룹 이름 포함 일치로 검색합니다. 생략하거나 공백만 있으면 필터링하지 않습니다. null 허용: False 예: 研发확인 또는 입력 방법: 백엔드 그룹 이름의 키워드를 입력합니다. |
|
| showMembers | boolean | 선택 사항이며, 문자열 true/1(대소문자 및 앞뒤 공백 무시)이면 활성화됩니다. 다른 값이면 비활성화되며 기본값은 false입니다. null 허용: False 예: true확인 또는 입력 방법: URL Query에서 true 또는 1로 계정 확장을 활성화하고, 필요 없으면 생략합니다. |
|
| showRefWorkspace | boolean | 선택 사항이며, 문자열 true/1이면 활성화되고 다른 값이면 비활성화되며 기본값은 false입니다. null 허용: False 예: true확인 또는 입력 방법: URL Query에서 true 또는 1로 워크스페이스 및 역할 확장을 활성화합니다. |
파라미터 추가 설명¶
사이트 수준 External API AK/SK를 사용하며, 서명 방식은 External API 서명 인증을 참조하세요. 백엔드 그룹 mgroup_은 여러 워크스페이스에 연결하고 상속 역할을 부여할 수 있으며, 단일 워크스페이스 내의 group_ 팀과 동일한 종류의 객체가 아닙니다. 쓰기 요청에는 w 권한이 필요하고, 목록 조회는 r 또는 w를 사용할 수 있습니다.
요청 예시¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 대상 사이트 주소 및 관리자가 할당한 External API AK/SK로 교체합니다.
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'GET'
path = '/api/v1/mgroup/list'
query = {'search': '研发', 'showMembers': 'true', 'showRefWorkspace': 'true', 'pageIndex': 1, 'pageSize': 20}
data = None
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
응답¶
HTTP 200, application/json 통합 응답 래퍼이며 비즈니스 데이터는 content에 있습니다. External은 declaration을 자동으로 추가하지 않으며, 목록 페이지네이션 정보는 content.pageInfo에 있습니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content.data | 객체 배열 | 현재 페이지의 백엔드 그룹입니다. 결과가 없으면 []입니다. |
| content.data[].id | integer 또는 null | 레코드 일련번호입니다. 호출에는 uuid를 사용합니다. 생성 스냅샷은 flush 전에 가져오므로 id가 null일 수 있습니다. |
| content.data[].uuid | string | 백엔드 그룹 UUID이며, 일반적으로 mgroup_ 접두사를 사용합니다. |
| content.data[].status | integer | 활성 그룹은 0입니다. 목록에서 삭제된 그룹은 필터링됩니다. |
| content.data[].creator | string | 생성 주체이며, External의 경우 일반적으로 sys입니다. |
| content.data[].updator | string | 최근 수정 주체이며, 수정하지 않은 경우 비어 있을 수 있습니다. |
| content.data[].createAt | integer | 생성 Unix 초입니다. |
| content.data[].deleteAt | integer | 삭제 Unix 초이며, 삭제되지 않은 경우 일반적으로 -1입니다. |
| content.data[].updateAt | integer | 그룹 엔터티 업데이트 시간이며, 아직 수정하지 않은 경우 일반적으로 -1입니다. 멤버/워크스페이스 역할만 변경한 경우 엔터티 시간이 동기화되어 업데이트된다고 보장할 수 없으므로, 이를 근거로 권한 부여 변경 여부를 판단할 수 없습니다. |
| content.data[].name | string | 백엔드 그룹 표시 이름입니다. |
| content.data[].members | 객체 배열 | showMembers가 활성화된 경우에만 존재하며, 확인할 수 없는 계정은 생략됩니다. |
| content.data[].members[].uuid | string | 계정 UUID이며, accountUUIDs 요소로 사용할 수 있습니다. |
| content.data[].members[].status | integer | 계정 자체 상태로, 비활성화/삭제 상태를 포함할 수 있으며 표시된다고 해서 로그인 가능한 것은 아닙니다. |
| content.data[].members[].wsAccountStatus | integer | 신원 요약의 워크스페이스 관계 상태입니다. 이 목록은 단일 워크스페이스를 지정하지 않으므로 일반적으로 3이며, 그룹 권한 부여 실패를 판단하는 데 사용할 수 없습니다. |
| content.data[].members[].username | string | 계정 로그인 이름입니다. |
| content.data[].members[].name | string | 표시 닉네임입니다. |
| content.data[].members[].iconUrl | string | 아바타 URL이며, 아바타가 없으면 비어 있을 수 있습니다. |
| content.data[].members[].email | string | 계정 이메일입니다. |
| content.data[].members[].mobile | string | 계정 휴대폰 번호입니다. |
| content.data[].members[].countryCode | string | 휴대폰 국가 코드입니다. |
| content.data[].members[].acntWsNickname | string | 신원 요약 워크스페이스 닉네임이며, 이 사이트 목록에서는 일반적으로 비어 있습니다. |
| content.data[].refWorkspaces | 객체 배열 | showRefWorkspace가 활성화된 경우에만 존재하며, 각 워크스페이스의 유효 역할 요약을 포함합니다. |
| content.data[].refWorkspaces[].uuid | string | 연결된 워크스페이스 UUID이며, 쓰기 요청에서는 필드 이름이 workspaceUUID입니다. |
| content.data[].refWorkspaces[].name | string 또는 null | 연결된 워크스페이스 이름이며, 레코드가 없으면 null일 수 있습니다. |
| content.data[].refWorkspaces[].status | integer 또는 null | 워크스페이스 상태로, 삭제됨 3을 포함할 수 있으며, 워크스페이스 레코드를 찾을 수 없으면 null일 수 있습니다. |
| content.data[].refWorkspaces[].roles | 객체 배열 | 유효 역할 요약입니다. 삭제되었거나 확인할 수 없는 역할은 요약에 나타나지 않으며, 이를 연결 테이블에 이력 레코드가 없다고 잘못 판단해서는 안 됩니다. |
| content.data[].refWorkspaces[].roles[].uuid | string | 역할 UUID입니다. |
| content.data[].refWorkspaces[].roles[].name | string | 역할 표시 이름입니다. |
| content.pageInfo.pageIndex | integer | 현재 페이지 번호입니다. |
| content.pageInfo.pageSize | integer | 페이지당 항목 수입니다. |
| content.pageInfo.count | integer | 현재 페이지의 그룹 수입니다. |
| content.pageInfo.totalCount | integer | 필터링된 그룹 총수입니다. |
{
"code": 200,
"content": {
"data": [
{
"id": 1001,
"uuid": "mgroup_example001",
"status": 0,
"creator": "sys",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例研发分组",
"members": [
{
"uuid": "acnt_example001",
"status": 0,
"wsAccountStatus": 3,
"username": "xxx@guance.com",
"name": "示例成员",
"iconUrl": "",
"email": "xxx@guance.com",
"mobile": "",
"countryCode": "",
"acntWsNickname": ""
}
],
"refWorkspaces": [
{
"uuid": "wksp_example001",
"name": "示例空间",
"status": 0,
"roles": [
{
"uuid": "readOnly",
"name": "ReadOnly"
}
]
}
]
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 20,
"count": 1,
"totalCount": 1
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
확장을 활성화하지 않으면 각 그룹은 기본 엔터티 필드만 반환합니다.
{
"code": 200,
"content": {
"data": [
{
"id": 1001,
"uuid": "mgroup_example001",
"status": 0,
"creator": "sys",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例研发分组"
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 20,
"count": 1,
"totalCount": 1
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
일치하는 항목이 없으면 data=[]이고 페이지네이션 count/totalCount는 0입니다.
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
표에는 확인된 요청 및 읽기 오류가 나열되어 있습니다. 일반적인 데이터베이스, 캐시 읽기 또는 결과 형식 지정 예외는 최종적으로 500 ft.InternalServerError가 됩니다. 이 API는 읽기만 수행하며 그룹이나 관계를 업데이트하지 않습니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인하세요. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시 읽기 또는 목록 필드 형식 지정 예외 | 내부 오류 | traceId를 보관하고 잠시 후 제한된 횟수로 재시도하세요. 계속 실패하면 관리자에게 읽기 경로 점검을 요청하세요. |