콘텐츠로 이동

워크스페이스 관리



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를 저장하고 목록에서 그룹/구성원/역할의 현재 상태를 확인합니다. 데이터가 이미 커밋되었을 수 있으므로 무작정 다시 생성하거나 전체를 덮어쓰지 마십시오.

문서 평가

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