콘텐츠로 이동

생성



POST /api/v1/mgroup/add

개요

백엔드 그룹을 생성하고 초기 계정 구성원을 설정할 수 있습니다.

호출 전 확인 및 사용 단계

먼저 동일한 이름의 그룹을 조회하고, 기존 계정을 초기 구성원으로 선택합니다. 이 API는 이름을 기준으로 중복을 제거하지만 멱등 키가 없습니다. 타임아웃 발생 후에는 먼저 목록을 조회하여 결과를 확인합니다. accountUUIDs는 그룹 관계만 생성하며 계정을 생성하거나 활성화하지 않습니다. refWorkspaces를 수신한다고 선언되어 있지만 현재 생성 구현에서는 워크스페이스/역할 매핑을 저장하지 않습니다. 이 파라미터는 생략하고, 새 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 초 문자열을 생성합니다.

Body 요청 파라미터

파라미터 이름 유형 필수 설명
accountUUIDs[*] string 단일 계정 UUID 문자열이며, 이메일 또는 워크스페이스 UUID가 아닙니다.
예: acnt_example001
가져오기 또는 입력 방법: 사이트 계정 목록의 content.data[].uuid에서 단일 계정을 가져옵니다.
refWorkspaces[*].roleUUIDs[*] string 단일 역할 UUID 문자열이며, 숫자나 객체를 사용하지 않습니다. 성공 응답만으로 역할이 실제로 유효하다고 판단하지 마십시오.
예: readOnly
가져오기 또는 입력 방법: 해당 워크스페이스의 워크스페이스 역할 목록에서 역할 uuid를 가져오며, 플랫폼 권한 부여 정책에 따라 선택합니다.
accountUUIDs array 전체 계정 UUID 배열이며 집합 기준으로 중복을 제거합니다. 호출자는 계정 존재 여부와 필요한 상태를 사전에 검증해야 하며, API는 모든 알 수 없거나 삭제된 계정을 능동적으로 필터링하지 않습니다. 생략하거나 null 또는 []이면 초기 구성원을 추가하지 않습니다.
null 허용: True
예: ["acnt_example001"]
가져오기 또는 입력 방법: 사이트 계정 목록의 content.data[].uuid에서 실제 계정을 가져오고, 먼저 상태를 확인합니다.
name string Y 필수 비어 있지 않은 이름이며 최대 256자입니다.
null 허용: False
최대 길이: 256
예: 示例研发分组
가져오기 또는 입력 방법: 백엔드 그룹 목록에서 활성 그룹 이름을 확인한 후 새 비어 있지 않은 이름을 지정합니다.
refWorkspaces array 현재 생성 API는 이 파라미터를 저장하지 않습니다. 생략하는 것이 좋으며, 생성 후 별도로 워크스페이스 역할 수정을 호출하십시오.
null 허용: True
예: [{"workspaceUUID": "wksp_example001", "roleUUIDs": ["readOnly"]}]
가져오기 또는 입력 방법: 워크스페이스 목록에서 워크스페이스 UUID를 가져온 다음, 각 워크스페이스별로 워크스페이스 역할 목록에서 해당 워크스페이스 역할을 가져옵니다.
refWorkspaces[*] object 하나의 워크스페이스 권한 부여 객체이며, 요청에 필드가 포함되는 경우에도 선언된 구조를 충족해야 합니다. 생성 시에는 이 객체가 적용되지 않습니다.
예: {"workspaceUUID": "wksp_example001", "roleUUIDs": ["readOnly"]}
가져오기 또는 입력 방법: 각 대상 워크스페이스마다 workspaceUUID와 전체 roleUUIDs 배열을 하나의 항목으로 구성하며, 동일한 워크스페이스는 한 번만 제공합니다.
refWorkspaces[*].roleUUIDs array 조건부 필수 필수 전체 역할 배열입니다. 현재 생성 시에는 이 매핑을 무시합니다.
null 허용: False
예: ["readOnly"]
가져오기 또는 입력 방법: 해당 항목의 workspaceUUID에 따라 워크스페이스 역할 목록에서 대응하는 유효한 역할 UUID를 가져옵니다.
refWorkspaces[*].workspaceUUID string 조건부 필수 필수 워크스페이스 UUID 문자열입니다. 현재 생성 시에는 이 매핑을 무시합니다.
null 허용: False
예: wksp_example001
가져오기 또는 입력 방법: 워크스페이스 목록에서 백엔드 그룹을 통해 권한을 부여해야 하는 활성 워크스페이스를 가져옵니다.

파라미터 추가 설명

사이트 수준 External API AK/SK를 사용하며, 서명 방식은 External API 서명 인증을 참조하십시오. 백엔드 그룹 mgroup_은 여러 워크스페이스에 연결하고 상속 역할을 부여할 수 있으며, 단일 워크스페이스 내의 group_ 팀과는 동일한 종류의 객체가 아닙니다. 쓰기 요청에는 w 권한이 필요하고, 목록 조회에는 r 또는 w를 사용할 수 있습니다. 리포지토리의 countLimit 기본값은 1000이며 사이트에서 재정의할 수 있습니다. 현재 판단은 기존 수량이 임계값보다 큰 경우에만 거부하므로, 임계값과 같은 값을 백엔드에서 반드시 거부한다고 간주할 수 없습니다. 생성 스냅샷은 flush 전에 가져오며, id는 null일 수 있습니다.

요청 예시

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 = 'POST'
path = '/api/v1/mgroup/add'
query = {}
data = {'name': '示例研发分组', 'accountUUIDs': ['acnt_example001']}
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.id integer 또는 null 레코드 일련번호입니다. 호출에는 uuid를 사용합니다. 생성 스냅샷은 flush 전에 가져오며 id는 null일 수 있습니다.
content.uuid string 백엔드 그룹 UUID이며 일반적으로 mgroup_ 접두사를 사용합니다.
content.status integer 활성 그룹은 0입니다. 목록에서는 삭제된 그룹을 필터링합니다.
content.creator string 생성 주체이며 External에서는 일반적으로 sys입니다.
content.updator string 최근 수정 주체이며 수정되지 않은 경우 비어 있을 수 있습니다.
content.createAt integer 생성 Unix 초입니다.
content.deleteAt integer 삭제 Unix 초이며 삭제되지 않은 경우 일반적으로 -1입니다.
content.updateAt integer 그룹 엔터티 업데이트 시간이며 아직 수정되지 않은 경우 일반적으로 -1입니다. 구성원/워크스페이스 역할만 변경하는 경우 엔터티 시간이 동기화되어 업데이트된다고 보장할 수 없으므로, 이를 근거로 권한이 변경되었는지 판단할 수 없습니다.
content.name string 백엔드 그룹 표시 이름입니다.
{
  "code": 200,
  "content": {
    "id": null,
    "uuid": "mgroup_example001",
    "status": 0,
    "creator": "sys",
    "updator": "",
    "createAt": 1785427200,
    "deleteAt": -1,
    "updateAt": -1,
    "name": "示例研发分组"
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.

표에는 확인된 요청 및 비즈니스 오류가 나열되어 있습니다. 일반 내부 예외는 최종적으로 500 ft.InternalServerError가 됩니다. 그룹/관계가 이미 커밋되었지만 이후 캐시 또는 감사가 실패할 수 있으므로 먼저 현재 상태를 읽어야 하며, 오류만으로 적용되지 않았다고 추론할 수 없습니다.

HTTP 상태 errorCode 트리거 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 파라미터 파싱 실패 파라미터 위치, 필드 이름, 유형 및 값을 확인하십시오.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않음 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정하십시오.
400 ft.JsonFormatError JSON 최상위가 객체가 아님 일부 json 파일 형식 오류 표에 따라 JSON 객체를 제출하십시오.
406 ft.MissingParameters name이 빈 문자열임 파라미터 누락 비어 있지 않은 그룹 이름을 제공하십시오.
400 ft.MGroupNameExists 동일한 이름의 활성 백엔드 그룹이 이미 있음 동일한 이름의 그룹이 이미 존재합니다 먼저 목록을 조회하고 중복되지 않는 이름을 선택하십시오. 기존 그룹은 수정해야 하며 중복 생성하지 마십시오.
400 ft.MGroupCountExceedsLimit 현재 활성 그룹 수가 사이트 countLimit보다 큰 상태에서 다시 추가하는 경우 그룹 수가 최대 제한을 초과했습니다. 최대 제한 수: {} 관리자는 사이트 그룹 할당량과 기존 그룹을 확인하고, 정리하거나 구성을 조정한 후 다시 생성하십시오.
500 ft.InternalServerError 데이터베이스, 비동기 캐시 새로 고침 전달, 감사 또는 처리되지 않은 필드 예외 내부 오류 traceId를 저장하고 목록에서 그룹/구성원/역할의 현재 상태를 확인하십시오. 데이터가 이미 커밋되었을 수 있으므로 무작정 중복 생성하거나 전체를 덮어쓰지 마십시오.

문서 평가

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