콘텐츠로 이동

목록 조회



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를 보관하고 잠시 후 제한된 횟수로 재시도하세요. 계속 실패하면 관리자에게 읽기 경로 점검을 요청하세요.

문서 평가

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