워크스페이스 관리¶
POST /api/v1/mgroup/{group_uuid}/modify/workspace
개요¶
백엔드 그룹의 크로스 워크스페이스 역할 권한 부여를 전체 교체합니다.
호출 전 및 사용 단계¶
먼저 백엔드 그룹 목록에서 showRefWorkspace를 활성화하여 기존 전체 매핑을 읽은 다음, 각 워크스페이스별로 워크스페이스 역할 목록에서 대상 역할을 확인합니다. refWorkspaces가 나타나면 전체를 교체하며, 나열되지 않은 기존 워크스페이스 권한 부여는 제거됩니다. 생략하면 유지되고, null 또는 []이면 모든 그룹 워크스페이스 역할을 비웁니다. 각 workspaceUUID는 한 번만 제공합니다. 중복 항목은 첫 번째 항목만 사용하며 병합하지 않습니다. 특정 워크스페이스의 roleUUIDs=[]는 해당 워크스페이스의 그룹 역할을 제거한다는 의미이며, 워크스페이스 자체와 계정은 삭제되지 않습니다. 이 API는 워크스페이스/역할의 존재 여부, 소속 워크스페이스 또는 대상 권한 부여 제약을 항목별로 검증하지 않으므로 관리자가 각 항목을 사전에 확인해야 하며, true를 유효한 권한이 이미 설정되었다고 간주해서는 안 됩니다. 그룹/관계 상태를 먼저 커밋한 다음 권한 캐시 새로 고침을 전달합니다. HTTP 200이 모든 후속 요청이 새 권한을 즉시 사용함을 보장하지 않으며, 전달 또는 감사 실패로 인한 500도 주체가 저장된 이후에 발생할 수 있습니다. 먼저 목록을 페이지네이션으로 읽고 uuid로 위치를 찾으며, 수정 시에는 전체 members/refWorkspaces를 펼쳐 확인하고, 삭제 시에는 대상이 더 이상 활성 목록에 없는지 확인한 후 재시도 여부를 결정합니다. 새로 고침 대상 목록이 비어 있으면 공유 작업이 모든 활성 워크스페이스를 새로 고치며, 현재 그룹만 새로 고친다고 이해해서는 안 됩니다.
경로 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| group_uuid | string | Y | 활성 백엔드 그룹 UUID이며, 단일 워크스페이스의 group_ 팀 UUID가 아닙니다. 예: mgroup_example001획득 또는 입력 방법: 백엔드 그룹 목록의 content.data[].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 요청 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| refWorkspaces[*].roleUUIDs[*] | string | 단일 역할 UUID 문자열이며 숫자나 객체를 사용하지 않습니다. 성공 응답만으로 역할이 실제로 유효하다고 판단하지 마십시오. 예: readOnly획득 또는 입력 방법: 해당 워크스페이스의 워크스페이스 역할 목록에서 역할 uuid를 가져와 플랫폼 권한 부여 정책에 따라 선택합니다. |
|
| refWorkspaces | array | 전체 워크스페이스 및 역할 대상 목록입니다. 이 필드가 나타나면 전체를 교체하며, 나열되지 않은 기존 워크스페이스 권한 부여는 제거됩니다. 생략하면 유지되고, null 또는 []이면 모든 워크스페이스 역할 권한 부여를 비웁니다. null 허용: True 예: [{"workspaceUUID": "wksp_example001", "roleUUIDs": ["readOnly"]}]획득 또는 입력 방법: 워크스페이스 목록에서 워크스페이스 UUID를 가져온 다음, 각 워크스페이스별로 워크스페이스 역할 목록에서 해당 워크스페이스의 역할을 가져옵니다. |
|
| refWorkspaces[*] | object | 워크스페이스 권한 부여 객체 1개입니다. 요청에 필드가 나타나는 경우에도 선언된 구조를 충족해야 합니다. 중복 workspaceUUID는 첫 번째 역할 목록만 사용하며 병합하지 않습니다. 예: {"workspaceUUID": "wksp_example001", "roleUUIDs": ["readOnly"]}획득 또는 입력 방법: 각 대상 워크스페이스마다 workspaceUUID와 전체 roleUUIDs 배열을 하나의 항목으로 구성합니다. 동일한 워크스페이스는 한 번만 제공합니다. |
|
| refWorkspaces[*].roleUUIDs | array | 조건부 필수 | 전체 역할 배열이 필수입니다. 각 항목은 앞뒤 공백을 제거하고, 중복을 제거하며, 빈 문자열을 제거합니다. []는 해당 워크스페이스의 모든 그룹 역할 권한 부여를 제거합니다. 역할 존재/소속을 완전히 검증하지 않으며 Owner 고유성 또는 인계 검증도 수행하지 않습니다. 알 수 없거나 다른 워크스페이스의 역할을 API가 거부한다고 의존할 수 없으며, Owner 변경이 관련된 경우 공식 인계 절차를 따라야 합니다. null 허용: False 예: ["readOnly"]획득 또는 입력 방법: 해당 항목의 workspaceUUID에 따라 워크스페이스 역할 목록에서 대응하는 유효한 역할 UUID를 가져옵니다. |
| refWorkspaces[*].workspaceUUID | string | 조건부 필수 | 워크스페이스 UUID 문자열이 필수입니다. 먼저 워크스페이스 존재 및 상태를 확인해야 하며, 이 API는 항목별로 검증하지 않으므로 잘못된 UUID도 저장될 수 있습니다. null 허용: False 예: wksp_example001획득 또는 입력 방법: 워크스페이스 목록에서 백엔드 그룹을 통해 권한을 부여해야 하는 활성 워크스페이스를 가져옵니다. |
매개변수 추가 설명¶
사이트 수준 External API AK/SK를 사용하며, 서명 방식은 External API 서명 인증을 참조하십시오. 백엔드 그룹 mgroup_은 여러 워크스페이스와 연결되어 상속 역할을 부여할 수 있으며, 단일 워크스페이스 내의 group_ 팀과 동일한 종류의 객체가 아닙니다. 쓰기 요청에는 w 권한이 필요하고, 목록 조회에는 r 또는 w를 사용할 수 있습니다. roleUUIDs는 증분이 아닌 전체 대상 배열을 사용하며, 구성원이 상속하는 권한도 이에 따라 변경됩니다. 저장 후 관련 워크스페이스 구성원 캐시를 비동기로 새로 고치며, 완료된 후 목록과 실제 액세스 권한을 조회하여 확인합니다.
요청 예시¶
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/mgroup_example001/modify/workspace'
query = {}
data = {'refWorkspaces': [{'workspaceUUID': 'wksp_example001', 'roleUUIDs': ['readOnly']}]}
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 | boolean | 처리가 성공하면 true이며, 실제 기록 수나 유효한 권한 부여 목록을 반환하지 않습니다. refWorkspaces를 생략하여 변경이 없어도 true일 수 있습니다. |
{
"code": 200,
"content": true,
"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 객체를 제출합니다. |
| 404 | ft.MGroupNoExists | 그룹 UUID가 존재하지 않거나 그룹이 삭제되었습니다 | 그룹이 존재하지 않습니다 | 백엔드 그룹 목록에서 활성 mgroup_ 레코드 uuid를 가져옵니다. |
| 500 | ft.InternalServerError | 데이터베이스, 비동기 캐시 새로 고침 전달, 감사 또는 처리되지 않은 필드 예외 | 내부 오류 | traceId를 저장하고 목록에서 그룹/구성원/역할의 현재 상태를 확인합니다. 데이터가 이미 커밋되었을 수 있으므로 무작정 다시 생성하거나 전체를 덮어쓰지 마십시오. |