일괄 삭제¶
POST /api/v1/workspace/accesskey/batch_delete
개요¶
UUID 배열로 API Key를 일괄 삭제합니다.
호출 전 확인 사항 및 사용 단계¶
w 권한의 External 자격 증명이 필요합니다. 요청에는 workspaceUUID 필터가 없으므로 동일한 배치에서 여러 워크스페이스가 조회될 수 있습니다. 각 Key의 워크스페이스, 이름 및 클라이언트 의존성을 항목별로 확인한 후 제출하십시오. 알 수 없거나 이미 삭제되었거나 시스템 Key인 경우 무시됩니다. 빈 배열은 어떤 Key도 삭제하지 않지만 그래도 성공할 수 있습니다. 배치에서 일치하는 Key 중 하나라도 Agent 소스에 바인딩된 경우 전체 배치가 거부되며, 이미 표시된 다른 Key를 먼저 제출하지 않습니다. 정상 흐름에서는 일치하는 Key를 소프트 삭제하고 해당 역할 연결을 정리하며, 제출 후 Key별로 AK/SK 무효화 캐시를 기록합니다. 캐시 예외가 발생하면 배치가 이미 삭제된 후에 500이 반환될 수 있습니다.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 원본 경로 및 요청 본문 서명 버전입니다. 생략한 후 이 페이지의 알고리즘을 계속 사용할 수 없습니다. 예: v20240417획득 또는 입력 방법: 이 페이지 예시는 이 고정 버전을 사용하며 예시 서명 알고리즘과 함께 사용됩니다. |
|
| X-Df-Access-Key | string | Y | 이 모듈의 목록은 r 또는 w 권한을 사용할 수 있습니다. 그 외 인터페이스(GET 상세 포함)는 모두 w 권한의 External 자격 증명이 필요합니다. 예: <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 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| akUUIDs[*] | string | 단일 Key 레코드 UUID이며, 평문 ak/sk도 아니고 워크스페이스 UUID도 아닙니다. 예: wsak_example001획득 또는 입력 방법: API Key 목록의 content.data[].uuid에서 단일 Key 레코드 UUID를 가져옵니다. |
|
| akUUIDs | array | Y | 필수 문자열 배열이며 null일 수 없습니다. []는 삭제하지 않으며, 중복 UUID는 동일 레코드만 조회합니다. 알 수 없거나 삭제되었거나 시스템 Key인 경우 무시합니다. null 허용: False 예: ["wsak_example001"]획득 또는 입력 방법: API Key 목록의 content.data[].uuid 또는 API Key 상세의 content.uuid에서 대상을 가져오고, 각 항목의 소속 워크스페이스를 확인합니다. |
파라미터 추가 설명¶
사이트 수준 External API AK/SK를 사용하며, 서명 방식은 External API 서명 인증을 참조하십시오. 이 페이지에서 생성하는 워크스페이스 API Key와 External 서명 자격 증명은 동일한 자격 증명 집합이 아닙니다. External은 현재 AK/SK 평문을 반환하며 프런트엔드 페이지의 마스킹 정책을 적용하지 않습니다. 응답 예시는 모두 자리 표시자 값을 사용하므로 실제 응답은 자격 증명으로 보관해야 합니다. 일괄 삭제와 단일 삭제 모두 삭제된 AK/SK를 사용하는 후속 OpenAPI 호출에 영향을 줍니다. 대체 자격 증명을 먼저 준비하십시오.
요청 예시¶
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/accesskey/batch_delete'
query = {}
data = {'akUUIDs': ['wsak_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 | 라우트는 고정적으로 true를 반환하며, 일치 수량이나 Key별 결과는 반환하지 않습니다. 빈 배열이거나 모든 UUID가 무시된 경우에도 true일 수 있습니다. |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
다음 표는 확인된 요청 및 비즈니스 분기를 나열합니다. 일반 데이터베이스/캐시/감사 5xx는 전역 래퍼를 거쳐 ft.InternalServerError로 반환됩니다. 쓰기 인터페이스가 오류를 반환할 때 이름, Owner 플래그, 역할 또는 삭제 상태가 이미 저장되었을 수 있으므로 먼저 현재 상태를 조회한 후 다음 단계를 결정해야 합니다.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다. | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 유형 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않습니다. | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아닙니다. | 일부 json 파일 형식 오류 | JSON 객체를 사용하고 배열이나 null을 전체 요청 본문으로 사용하지 마십시오. |
| 400 | ft.AgentWorkspaceAKCanNotDelete | 일치하는 배치에 createdWay=agent이고 계정이 바인딩된 Key가 포함되어 있습니다. | 에이전트에 바인딩된 API Key는 삭제할 수 없습니다. | 해당 Key를 제거하고 해당 에이전트 관리 진입점을 통해 처리합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시 무효화, 감사 또는 처리되지 않은 필드 예외 | 내부 오류 | traceId를 보관하고 Key의 현재 이름, 역할 및 상태를 확인합니다. 데이터가 먼저 커밋된 후 실패할 수 있으므로 500만으로 미적용으로 간주할 수 없습니다. |