콘텐츠로 이동

워크스페이스 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"
}

문서 평가

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