현재 워크스페이스 Token 교체¶
POST /api/v1/workspace/token/rotate
개요¶
현재 워크스페이스의 기본 수집 Token을 교체하고 이전 값의 유예 기간을 설정합니다.
호출 전 및 사용 단계¶
현재 워크스페이스에서 workspace.tokenReplace 권한이 있는 OpenAPI Key를 사용합니다. 먼저 수집 측과 기본 Token을 사용하는 통합을 점검합니다. 여기서는 수집 자격 증명을 교체하며 OpenAPI API Key를 교체하는 것이 아닙니다. ttl은 이전 값의 남은 유효 기간을 제어하며, 0s는 이전 값을 즉시 무효화하고 다른 값은 최대 24시간입니다. 새 값은 기본 장기 자격 증명 의미를 유지하며 openDataQuery를 계속 사용합니다.
성공 후 새 Token을 저장하고 외부 수집 측을 업데이트해야 합니다. 시스템 내 기본 Token 참조는 동기화와 함께 업데이트되며, 외부에서 직접 저장한 값은 직접 교체해야 합니다. 각 교체 시 새 값이 생성되고 24시간 쿨다운 내에는 다시 교체할 수 없으며 멱등성이 없습니다. 어떤 워크스페이스 Token 동기화 pending 상태라도 이번 작업을 차단할 수 있습니다.
OperationBusy/SyncPending 등 content.committed가 포함된 409 분기는 해당 필드를 반드시 확인해야 합니다. false이면 이번 작업이 저장되지 않은 것이므로 잠금/기존 동기화를 처리한 후 다시 요청합니다. true이면 새 값으로 교체된 것이므로 확인/동기화 보완을 해야 하며 반복 교체해서는 안 됩니다. Cooling/Revoked는 committed를 포함하지 않을 수 있으며, 누락을 false로 간주해서는 안 되고 구체적인 errorCode에 따라 처리해야 합니다. syncRequiresVerification=true이면 먼저 다운스트림의 실제 결과를 확인하고 무작정 재시도하지 않습니다. 응답이 유실된 경우 관리자가 워크스페이스 Token 관리에서 현재 자격 증명과 동기화 상태를 확인한 후 수집 측을 업데이트해야 합니다. 성공 응답에는 no-store/no-cache가 포함되므로 자격 증명 캐싱을 피해야 합니다.
요청 헤더¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| ttl | string | Y | 필수, 0s 또는 양의 정수+소문자 s/m/h/d, 선행 0 없음, 공백/대문자/null/소수점은 허용하지 않습니다. 실제 총 초 수는 86400을 초과할 수 없습니다. ttl은 새 값의 수명이 아닙니다.null 허용: False $matchRegExp: ^(0s|[1-9][0-9]*[smhd])$ 예: 30m획득 또는 입력 방법: 수집 구성 교체 기간에 따라 0s/30m/1h/24h/1d 등을 선택합니다. |
매개변수 추가 설명¶
대상은 항상 현재 워크스페이스의 기본 수집 Token이며 팀 Token 또는 OpenAPI Key는 관리하지 않습니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/token/rotate' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"ttl":"30m"}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.token | string | 새 기본 수집 Token의 평문입니다. 안전하게 저장하십시오. OpenAPI Key가 아닙니다. |
| content.openDataQuery | boolean | 기존 Token의 데이터 쿼리 권한을 유지합니다. |
| content.declaration | object 또는 null | 현재 워크스페이스의 공용 선언입니다. |
| content.committed | boolean | 일부 409 오류에만 해당: true이면 변경이 저장되었고, false이면 이번 작업이 저장되지 않았습니다. |
| content.nextRotateAt | integer | Cooling 409에만 해당하며 다음 교체가 허용되는 Unix 초입니다. |
| content.syncStatus | string | 동기화 409에만 해당하며 일반적으로 pending입니다. |
| content.syncRequiresVerification | boolean | 일부 동기화 409에 해당하며, true이면 먼저 다운스트림 결과를 확인해야 합니다. |
| content.syncFailureReason | string | 일부 409의 사유입니다. 예: operation_busy/cache_pending/verification_required/kodo_failed. |
| content.tokenRecordUUID | string 또는 null | 일부 동기화 409에 해당하며 기본 Token은 일반적으로 null이고 자격 증명 평문이 아닙니다. |
| content.isDefault | boolean | 일부 동기화 409에 해당하며 이 진입점은 true입니다. |
| 응답 헤더 | 유형 | 설명 |
|---|---|---|
| Cache-Control | string | 성공 응답은 no-store입니다. |
| Pragma | string | 성공 응답은 no-cache입니다. |
{
"code": 200,
"content": {
"token": "<NEW-WORKSPACE-TOKEN>",
"openDataQuery": false,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건을 위반 | 매개변수 구문 분석 실패 | 매개변수 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 이 페이지의 매개변수에 따라 JSON 객체를 제출합니다. |
| 401 | ft.WKSPNotExistOrReleased | 현재 워크스페이스가 존재하지 않거나 status!=0 |
워크스페이스가 존재하지 않음/또는 해제됨 | 현재 워크스페이스가 활성 상태인지 확인합니다. |
| 404 | ft.ObjectNotExists | 워크스페이스 기본 Token 레코드가 존재하지 않음 | 지정한 객체가 존재하지 않음 | 관리자가 Token 레코드를 복구하도록 하며 이 진입점으로 보완 생성하지 마십시오. |
| 400 | ft.WorkspaceTokenInvalidTTL | 선언 형식은 통과했지만 총 유예 기간이 24시간을 초과함 | 이전 값의 유효 기간은 24시간을 초과할 수 없습니다 | 24시간 이하로 변경하고 즉시 무효화하려면 0s를 사용합니다. |
| 409 | ft.WorkspaceTokenCooling | 마지막 교체로부터 86400초가 지나지 않음, 과거 쿨다운 포함 | 아직 재생성 가능 시간이 되지 않았습니다 | content.nextRotateAt(Unix 초)을 읽고 대기하며 높은 빈도로 재시도하지 않습니다. |
| 409 | ft.WorkspaceTokenRevoked | 기본 Token이 무효화됨/상태 이상/장기 활성 자격 증명이 아님 | Token이 무효화되었거나 사용할 수 없습니다 | 관리자가 현재 기본 자격 증명 상태를 확인합니다. |
| 409 | ft.WorkspaceTokenOperationBusy | 동일 워크스페이스 수명 주기 상호 배제가 다른 작업에 의해 점유됨 | 현재 워크스페이스에서 다른 작업이 진행 중이며 이번 작업은 저장되지 않았습니다. 나중에 다시 시도하십시오. | committed=false이면 먼저 잠금이 해제될 때까지 기다린 후 현재 상태를 확인합니다. |
| 409 | ft.WorkspaceTokenSyncPending | 기존 동기화 대기 레코드/이전 결과 확인 대기 또는 이번 작업이 커밋된 후 동기화 실패 | 분기 안내에 따라 이번 작업이 저장되지 않았거나 변경이 저장되었습니다 | content.committed로 구분합니다. 이미 커밋된 경우 확인/동기화 보완만 하고, syncRequiresVerification=true이면 먼저 다운스트림을 확인합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시/큐, 다운스트림 일반 5xx/시간 초과 또는 처리되지 않은 유형 실패; 쓰기가 이미 커밋되었을 수 있음 | 내부 오류 | 먼저 현재/대상 워크스페이스 상세와 다운스트림 상태에서 저장된 결과를 확인하고 무작정 반복 생성/교체하지 마십시오. 이미 저장된 경우 완료되지 않은 동기화만 처리하고 traceId를 제공합니다. |