수정¶
POST /api/v1/workspace/inner_accesskey/{workspace_uuid}/refresh
개요¶
워크스페이스 내장 시스템 Key의 AK/SK를 재설정하며, Key가 없으면 새 Key를 생성합니다.
호출 전 및 사용 단계¶
w 권한이 필요합니다. 먼저 워크스페이스 목록에서 활성 워크스페이스를 확인한 다음, 초기화 및 내장 Key 가져오기로 현재 Key와 종속 대상을 확인합니다. 이 엔드포인트 자체는 워크스페이스의 활성 상태를 다시 검증하지 않으며, Key가 없으면 바로 생성하므로 임의의 UUID를 전달하여 워크스페이스 존재 여부를 탐색해서는 안 됩니다. Key가 이미 있으면 레코드 uuid를 유지하고 AK/SK를 다시 생성하며 업데이트 시간을 갱신합니다. Key가 없으면 Owner 시스템 Key를 생성합니다. 요청 본문이 없고 ttl 유예 시간이나 이름만 변경하는 옵션도 없으며, 새로 고칠 때마다 새 자격 증명이 생성되므로 멱등성이 없습니다. 실패 후에는 먼저 현재 자격 증명을 확인해야 하며, 무작정 다시 새로 고쳐서는 안 됩니다. 현재 구현은 이전 AK의 인증 캐시를 능동적으로 무효화하지만, 이전 SK 캐시를 동시에 능동적으로 삭제하지는 않습니다. 이전 SK에 유효한 인증 캐시가 이미 있으면 성공 응답만으로 모든 이전 자격 증명이 즉시 폐기되었다고 판단해서는 안 되며, 관리자가 캐시 처리와 실제 인증 결과를 확인해야 합니다.
라우트 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| workspace_uuid | string | Y | 워크스페이스 UUID이며, API Key 레코드 UUID나 평문 AK/SK가 아닙니다. 예: wksp_example001가져오기 또는 입력 방법: 워크스페이스 목록의 content.data[].uuid에서 가져오고, 사이트와 활성 상태를 확인합니다. |
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 원본 경로와 요청 본문 서명 버전이며, 생략한 후 이 페이지의 알고리즘을 계속 사용할 수 없습니다. 예: v20240417가져오기 또는 입력 방법: 이 페이지의 예시는 이 고정 버전을 사용하며, 예시 서명 알고리즘과 함께 사용됩니다. |
|
| X-Df-Access-Key | string | Y | 이 모듈의 목록은 r 또는 w 권한을 사용할 수 있으며, 나머지 세 항목은 GET 초기화를 포함해 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 초 문자열을 생성합니다. |
파라미터 보충 설명¶
사이트 수준 External API 자격 증명을 사용하며, 인증은 External API 서명 인증을 참고합니다. 목록은 r 또는 w 권한을 허용하며, 나머지 세 항목은 GET 초기화를 포함해 w 권한이 필요합니다. 모든 응답은 높은 권한의 자격 증명 평문을 반환할 수 있으므로 일반 프런트엔드 페이지의 마스킹 표시 규칙을 적용해서는 안 됩니다. 예시는 자리 표시자 값을 사용하며, 실제 자격 증명은 안전하게 보관해야 합니다. Key가 없어 새로 생성하는 분기는 flush 전에 반환 스냅샷을 가져오므로 id, callCount, lastCallAt가 null일 수 있습니다. Key가 이미 있는 분기는 기존 레코드 정보와 새 자격 증명을 반환합니다.
요청 예시¶
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/inner_accesskey/wksp_example001/refresh'
query = {}
data = None
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.id | integer 또는 null | 내부 레코드 일련번호이며, 인터페이스 호출에는 uuid를 사용합니다. 생성 스냅샷은 flush 전에 가져오므로 이 필드는 null일 수 있습니다. |
| content.uuid | string | API Key 레코드 UUID이며, 호출 자격 증명 ak/sk와 다릅니다. |
| content.status | integer | 내장 Key 상태이며, 이 모듈의 조회 및 삭제는 status=0을 선택합니다. |
| content.creator | string | 생성 주체이며, External에서 생성한 경우 일반적으로 external입니다. |
| content.updator | string | 수정 주체이며, 수정되지 않은 경우 비어 있을 수 있습니다. |
| content.createAt | integer | 생성 Unix 초입니다. |
| content.deleteAt | integer | 삭제 Unix 초이며, 삭제되지 않은 경우 일반적으로 -1입니다. |
| content.updateAt | integer | 수정 Unix 초이며, 아직 수정되지 않은 경우 일반적으로 -1입니다. |
| content.name | string | 내장 Key 이름이며, 초기화 시 inner입니다. |
| content.ak | string | 내장 시스템 Access Key 평문이며, 높은 권한의 자격 증명으로 보관해야 합니다. External 서명 AK가 아닙니다. |
| content.sk | string | 내장 시스템 Secret Key 평문이며, 높은 권한의 자격 증명으로 보관해야 합니다. External 서명 SK가 아닙니다. |
| content.workspaceUUID | string | 소속 워크스페이스 UUID입니다. |
| content.accountUUID | string | 바인딩된 계정 식별자이며, 초기화된 시스템 Key는 일반적으로 빈 문자열입니다. |
| content.createdWay | string | 생성 출처이며, 초기화는 일반적으로 manual입니다. 시스템 범위는 isSystem/businessType으로 구분합니다. |
| content.businessType | string | 이 모듈은 inner sys 유형만 관리합니다. |
| content.isSystem | integer | 이 모듈은 시스템 내장 Key만 관리하며, 초기화 시 1입니다. |
| content.isOwnerRole | integer | 초기화 시 1이며 Owner 역할 의미를 가집니다. 일반 수동 Owner Key와 별도로 관리됩니다. |
| content.remark | string | 기존 비고이며, 이 모듈에는 비고를 수정하는 요청 파라미터가 없습니다. |
| content.isBurnAfterReading | integer | 보존된 열람 후 소멸 표시이며, 이 모듈은 읽은 후 소멸을 수행하지 않으므로 이를 통해 자격 증명을 폐기하는 데 의존해서는 안 됩니다. |
| content.callCount | integer 또는 null | 영구 누적 호출 횟수이며, 비동기 통계이므로 실시간 카운트가 아닙니다. 생성 스냅샷은 flush 전에 null일 수 있습니다. |
| content.lastCallAt | integer 또는 null | 마지막 호출 Unix 초이며, 일반적으로 -1은 기록 없음을 의미합니다. 생성 스냅샷은 null일 수 있습니다. |
{
"code": 200,
"content": {
"id": 1001,
"uuid": "wsak_inner_example001",
"status": 0,
"creator": "external",
"updator": "external",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": 1785427200,
"name": "inner",
"ak": "<refreshed-inner-access-key>",
"sk": "<refreshed-inner-secret-key>",
"workspaceUUID": "wksp_example001",
"accountUUID": "",
"createdWay": "manual",
"businessType": "inner sys",
"isSystem": 1,
"isOwnerRole": 1,
"remark": "",
"isBurnAfterReading": 0,
"callCount": 0,
"lastCallAt": -1
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
Key가 없을 때 생성되는 스냅샷 예시:
{
"code": 200,
"content": {
"id": null,
"uuid": "wsak_inner_example001",
"status": 0,
"creator": "external",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "inner",
"ak": "<inner-access-key>",
"sk": "<inner-secret-key>",
"workspaceUUID": "wksp_example001",
"accountUUID": "",
"createdWay": "manual",
"businessType": "inner sys",
"isSystem": 1,
"isOwnerRole": 1,
"remark": "",
"isBurnAfterReading": 0,
"callCount": null,
"lastCallAt": null
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고합니다.
파라미터가 선언과 일치하지 않으면 공통 요청 오류를 반환합니다. 데이터베이스, 캐시 등의 일반 내부 예외는 최종적으로 500 ft.InternalServerError로 통일됩니다. 쓰기 요청이 실패한 후에는 영구 상태와 캐시를 먼저 확인해야 하며, 전혀 적용되지 않았다고 보장할 수 없습니다.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방식 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시 무효화 또는 명시적으로 처리되지 않은 내부 예외 | 내부 오류 | traceId를 저장하고, Key의 현재 상태와 실제 호출 결과를 먼저 확인한 후 재시도 여부를 결정합니다. 데이터베이스가 이미 커밋되었을 수 있으므로 오류 응답만으로 변경이 없었다고 판단해서는 안 됩니다. |