워크스페이스 소유자 변경¶
POST /api/v1/workspace/{workspace_uuid}/owner/transfer
개요¶
지정한 계정을 Owner로 설정하고 기존 Owner의 직접 멤버 연결을 제거합니다.
호출 전 확인 및 사용 단계¶
w 권한의 External 자격 증명이 필요합니다. 먼저 워크스페이스 목록에서 워크스페이스가 실제로 존재하는지 확인하고 현재 Owner를 조회하여 인수인계 영향을 검토한 다음, 사이트 계정 목록에서 대상 계정을 선택합니다. 대상은 이미 이 워크스페이스에 속해 있을 필요가 없으며, 필요할 경우 직접 멤버 관계가 새로 추가됩니다. 활성 계정 사용을 권장합니다. 현재 검증은 삭제된 계정만 제외하므로 비활성 계정도 통과할 수 있지만 정상적으로 로그인할 수 없습니다. agent 소스는 Owner가 될 수 없습니다. 기존 Owner의 Owner 역할과 직접 멤버 연결은 제거되지만 계정 자체는 삭제되지 않습니다. 백그라운드 그룹 등에 기반해 생성된 상속 관계는 동기적으로 제거되는 것으로 간주해서는 안 됩니다. 대상에는 Owner 역할이 추가되며, 이미 존재하는 다른 직접 역할이 함께 삭제된다고 보장하지 않습니다. 대상이 이미 현재 Owner인 경우 true를 바로 반환합니다. 이 작업은 청구 센터 계정을 생성/이전하지 않으며, 성공 후 워크스페이스 멤버와 Owner를 확인해야 합니다.
경로 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| workspace_uuid | string | Y | 대상 워크스페이스 UUID이며, 먼저 활성 상태와 사이트를 확인합니다. 예시: wksp_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 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| accountUUID | string | Y | 필수 대상 계정 UUID 문자열입니다. 선언상 null을 허용하지만 null 또는 빈 문자열이면 계정을 조회할 수 없습니다. 워크스페이스 UUID를 입력하지 마십시오. 이 External API는 대상이 사전에 워크스페이스 멤버일 것을 요구하지 않습니다. 빈 문자열 허용: False null 허용: True 예시: acnt_example001조회 또는 입력 방법: 사이트 계정 목록의 content.data[].uuid에서 대상 계정을 가져오며, agent 소스가 아니고 status=0인 것을 권장합니다. |
파라미터 추가 설명¶
인증은 External API 서명 인증을 참고하십시오. 이 페이지의 예시는 v20240417을 사용하며, 원본 전체 경로, Query, 요청 본문 서명 알고리즘과 함께 사용됩니다. 이 모듈은 지정한 워크스페이스의 멤버 관계 또는 역할을 조작하며 계정 자체를 생성하지 않습니다. 쓰기 요청이 실패하면 먼저 멤버와 역할의 현재 상태를 확인한 뒤 재시도 여부를 결정해야 합니다. 사전에 목록에서 워크스페이스 UUID를 확인해야 하며, 현재 이전 메서드는 워크스페이스 존재 여부를 추가로 확인해 주지 않습니다. 이전과 후속 캐시 정리는 단계적으로 수행되므로, 실패하면 먼저 현재 Owner를 확인한 뒤 다음 단계를 결정하십시오.
요청 예시¶
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/workspace/wksp_example001/owner/transfer'
query = {}
data = {'accountUUID': '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 | boolean | 이전이 완료되었거나 대상이 이미 현재 Owner이면 true입니다. Owner 상세 정보는 반환하지 않습니다. |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.
다음 표는 확인된 비즈니스 및 요청 오류입니다. 일반 데이터베이스/하위 시스템 5xx 또는 처리되지 않은 예외는 전역에서 ft.InternalServerError로 래핑됩니다. 쓰기 요청 실패 시 부분 반영이 없었다고 보장할 수 없으므로 먼저 관계의 현재 상태를 확인해야 합니다.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | 요청 JSON의 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | JSON 객체를 제출하고, 배열이나 null을 전체 요청 본문으로 사용하지 마십시오. |
| 404 | ft.NotFoundAccount | 대상 accountUUID가 존재하지 않거나, 삭제되었거나, 비어 있거나 null임 | 지정한 계정을 찾을 수 없음 | 사이트 계정 목록에서 대상 계정을 다시 선택합니다. |
| 400 | ft.AgentMemberCanNotBeOwner | 대상 계정 source=agent | agent 소스 멤버는 워크스페이스 소유자로 설정할 수 없음 | 일반 멤버 계정을 선택합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시, 이전 승인 작업 취소 또는 처리되지 않은 배열/필드 예외 | 내부 오류 | traceId를 저장하고 관리자에게 실제 관계와 캐시를 확인하도록 요청하십시오. 쓰기 작업이 일부 커밋되었을 수 있으므로 무작정 재실행해서는 안 됩니다. |