워크스페이스 Token 교체¶
POST /api/v1/workspace/{workspace_uuid}/token/rotate
개요¶
지정한 워크스페이스의 기본 수집 Token을 교체하고 이전 값에 짧은 유예 시간을 설정합니다.
호출 전 확인 및 사용 단계¶
먼저 기본 Token을 사용하는 수집 엔드포인트와 통합을 파악하고, 교체를 완료하기에 충분한 이전 값의 유효 기간을 선택합니다. ttl은 이전 Token의 남은 유효 기간을 제어하며, 새 Token의 유효 기간이 아닙니다. 성공 후에는 content.token을 안전하게 저장하고 수집 설정을 업데이트합니다. 기본 자격 증명에 대한 참조는 동기화 과정에서 처리되지만, 외부에서 직접 저장한 Token은 직접 교체해야 합니다. 이 API는 호출할 때마다 새 자격 증명을 생성하며 멱등성을 지원하지 않으므로 24시간 이내에는 다시 교체할 수 없습니다. 실패 시 반드시 content.committed를 확인하고, 이미 저장되었다면 동기화를 처리해야 하며 교체를 계속해서는 안 됩니다. 응답이 유실된 경우 관리자가 워크스페이스 Token 관리에서 현재 값과 동기화 상태를 확인한 후 계속 진행하도록 하십시오.
경로 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| workspace_uuid | string | Y | 대상 워크스페이스 UUID이며, 계정 UUID나 수집 Token이 아닙니다. 예: wksp_example001확인 또는 입력 방법: 워크스페이스 목록의 content.data[].uuid 또는 생성 성공 시 content.wsInfo.uuid에서 가져오고, 사이트와 워크스페이스 이름을 확인합니다. |
요청 헤더¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 예제와 일치해야 하며, 생략한 채 이 알고리즘을 계속 사용할 수 없습니다. 예: v20240417확인 또는 입력 방법: 이 페이지의 원본 경로 및 요청 본문 서명 알고리즘에 맞춰 입력합니다. |
|
| X-Df-Access-Key | string | Y | 여기의 일곱 항목은 모두 쓰기 작업이므로 External 쓰기 권한이 필요합니다. 예: <external-access-key>확인 또는 입력 방법: 사이트 관리자가 w 권한을 부여한 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>확인 또는 입력 방법: 함께 제공된 SK를 사용하여 External API 서명 인증 및 아래 Python 템플릿에 따라 계산합니다. |
| X-Df-Timestamp | string | Y | 예제의 고정 시간을 재사용할 수 없으며, 사이트 서명 유효 시간 범위 내에 있어야 합니다. 예: 1785427200확인 또는 입력 방법: 전송 시 str(int(time.time()))로 현재 Unix 초를 생성합니다. |
Body 요청 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| ttl | string | Y | 필수 문자열이며 0s 또는 양의 정수 + 소문자 s/m/h/d만 허용합니다. 0s는 이전 값을 즉시 무효화하고, 다른 값은 이전 값의 남은 유예 기간이며 24시간을 초과할 수 없습니다. 공백, null, 소수 또는 대문자 단위는 허용하지 않습니다. null 허용: False $matchRegExp: ^(0s|[1-9][0-9]*[smhd])$ 예: 30m확인 또는 입력 방법: 수집 엔드포인트의 교체 기간에 따라 0s, 30m, 1h, 24h 또는 1d 등을 선택하며, 최대 86400초입니다. |
파라미터 추가 설명¶
w 권한이 있는 사이트 수준 External API 자격 증명을 사용합니다. 인증 방식은 External API 서명 인증을 참조하십시오. 예제는 v20240417에 따라 서명을 계산하며, 서명과 전송에는 동일한 경로, Query 및 원본 요청 본문을 사용합니다. 모든 예제는 데모 값이므로 실행 전에 실제 대상으로 교체해야 합니다. 쓰기 요청이 타임아웃되거나 500이 반환되면 먼저 현재 상태를 조회하고, 확인한 후 재시도 여부를 결정해야 합니다.
요청 예제¶
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/token/rotate'
query = {}
data = {'ttl': '30m'}
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을 자동으로 주입하지 않습니다. 워크스페이스 객체의 declaration은 자체 저장 필드입니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content.token | string | 새 기본 수집 Token의 평문이며 이번 응답에서만 반환되므로 안전하게 저장해야 합니다. External API AK가 아닙니다. |
| content.openDataQuery | boolean | 현재 Token의 데이터 조회 권한 표시이며, 교체 후에도 기존 권한을 유지합니다. |
| content.committed | boolean | 일부 409 오류에서만 반환됩니다. true이면 새 Token이 저장되었고, false이면 이번 요청은 아직 저장되지 않았습니다. |
| content.nextRotateAt | integer | 쿨다운 409 오류에서만 반환됩니다. 다음 교체가 허용되는 Unix 초 시간입니다. |
| content.syncStatus | string | 동기화 409 오류에서만 반환되며 일반적으로 pending입니다. |
| content.syncRequiresVerification | boolean | 일부 동기화 오류에서 제공됩니다. true이면 먼저 다운스트림 결과를 검증해야 합니다. |
| content.syncFailureReason | string | 일부 동기화 오류에서 제공됩니다. 예: operation_busy, cache_pending, verification_required, kodo_timeout, kodo_failed. |
| content.tokenRecordUUID | string 또는 null | 일부 동기화 오류에서 제공됩니다. 기본 Token은 일반적으로 null입니다. |
| content.isDefault | boolean | 일부 동기화 오류에서 제공됩니다. 이 API의 대상은 기본 Token이므로 값은 true입니다. |
| 응답 헤더 | 타입 | 설명 |
|---|---|---|
| Cache-Control | string | 성공 응답은 no-store입니다. |
| Pragma | string | 성공 응답은 no-cache입니다. |
{
"code": 200,
"content": {
"token": "<new-workspace-token>",
"openDataQuery": false
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
다음 표는 이 API의 비즈니스 검증 및 확인된 주요 오류 분기를 나열합니다. 다운스트림 서비스는 구체적인 오류 매핑에 따라 다른 4xx 오류를 반환할 수도 있습니다. 일반적인 5xx 및 알 수 없는 예외는 전역 처리에 의해 ft.InternalServerError로 반환됩니다. 쓰기 요청은 현재 설정과 오류 content를 함께 확인하여 적용 여부를 판단해야 하며, HTTP 상태만으로 롤백을 추론해서는 안 됩니다.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 타입 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 JSON 파일 형식 오류 | 파라미터 표에 따라 JSON 객체를 제출하고, 배열 또는 null을 전체 요청 본문으로 사용하지 마십시오. |
| 401 | ft.WKSPNotExistOrReleased | 워크스페이스가 존재하지 않거나 status가 0이 아님 | 워크스페이스가 존재하지 않음/또는 해제됨 | 목록에서 워크스페이스의 활성 상태를 확인합니다. |
| 404 | ft.ObjectNotExists | 워크스페이스의 현재 기본 Token 레코드가 누락됨 | 지정한 객체가 존재하지 않음 | 관리자가 해당 워크스페이스의 Token 레코드를 복구하도록 하며, 이 API를 사용하여 대체 레코드를 생성하지 마십시오. |
| 400 | ft.WorkspaceTokenInvalidTTL | 형식은 유효하지만 이전 값의 유예 시간이 24시간을 초과함 | 이전 값의 유효 기간은 24시간을 초과할 수 없습니다. | 0s를 사용하여 즉시 무효화하거나 24시간을 초과하지 않는 유효 기간을 사용합니다. |
| 409 | ft.WorkspaceTokenCooling | 마지막 교체로부터 24시간이 지나지 않았으며, 이전 진입점에서 유지되는 쿨다운 시간을 포함함 | 아직 재생성 가능한 시간이 되지 않음 | content.nextRotateAt을 읽고 해당 Unix 초 시간 이후에 다시 요청하십시오. 계속 재시도하지 마십시오. |
| 409 | ft.WorkspaceTokenRevoked | 기본 Token이 무효화되었거나 만료되었거나 사용할 수 없음 | Token이 무효화되었거나 사용할 수 없음 | 관리자가 워크스페이스의 현재 자격 증명 상태를 확인하도록 하며, 교체를 자격 증명 복구로 간주하지 마십시오. |
| 409 | ft.WorkspaceTokenOperationBusy | 워크스페이스 수명 주기 잠금을 획득할 때 다른 작업이 이미 존재함 | 현재 워크스페이스에서 다른 작업이 진행 중이므로 이번 작업은 저장되지 않았습니다. 잠시 후 다시 시도하십시오. | content.committed=false이면 잠시 후 새 서명으로 재시도할 수 있습니다. |
| 409 | ft.WorkspaceTokenSyncPending | 처리 대기 중인 동기화가 있거나, 교체 커밋 후 Kodo와의 동기화가 완료되지 않았거나 결과 검증이 필요함 | 분기 안내에 따라 ‘이번 작업은 저장되지 않음’ 또는 ‘변경 사항이 저장됨’으로 표시되며, content.committed와 함께 판단해야 합니다. | committed=true이면 이미 교체되었으므로 반복 교체하지 마십시오. 관리자가 먼저 Kodo 상태를 검증한 후 커밋된 현재 상태를 동기화해야 합니다. syncRequiresVerification=true이면 먼저 검증해야 하며, 검증 없이 무작정 재생해서는 안 됩니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시, 리소스 서비스 또는 처리되지 않은 파라미터 변환 예외 | 내부 오류 | traceId를 저장하고 관리자에게 문의하십시오. 먼저 설정과 다운스트림의 실제 상태를 조회해야 하며, 실패 응답을 곧바로 저장되지 않은 것으로 간주하거나 무작정 반복 생성 또는 교체해서는 안 됩니다. |
커밋되었지만 다운스트림 동기화에 실패한 예제(HTTP 409, 다시 교체할 수 없음):
{
"code": 409,
"content": {
"committed": true,
"syncStatus": "pending",
"syncFailureReason": "kodo_failed",
"syncRequiresVerification": false,
"tokenRecordUUID": null,
"isDefault": true
},
"errorCode": "ft.WorkspaceTokenSyncPending",
"message": "변경 사항은 저장되었지만 Kodo 인터페이스 동기화에 실패했습니다. 동기화를 다시 시도하십시오. 이번 작업을 반복 제출할 필요는 없습니다.",
"success": false,
"traceId": "TRACE-EXAMPLE"
}