목록¶
GET /api/v1/workspace/accesskey/list
개요¶
페이징하여 삭제되지 않고 활성화된 수동 워크스페이스 API Key를 나열합니다.
호출 전 및 사용 단계¶
r 또는 w 권한의 External 자격 증명이 필요합니다. 항상 workspaceUUID를 전달하여 확인된 대상 워크스페이스만 조회하는 것이 좋습니다. 생략하거나 빈 문자열이면 이 서비스의 모든 조건에 맞는 Key를 워크스페이스 경계를 넘어 조회하고 평문 AK/SK를 반환하며, 로그인한 특정 워크스페이스로 자동 제한되지 않습니다. status=0이고 시스템이 아니며 accountUUID가 비어 있는 Key만 반환하며, 개인/Agent 바인딩 Key는 나열되지 않습니다. id 내림차순이며 pageIndex 기본값은 1, pageSize 기본값은 20입니다. 검색은 Key 이름만 일치시키고 앞뒤 공백을 제거합니다. 목록은 엔터티 필드를 직접 반환하며 역할, 권한 또는 creatorInfo를 포함하지 않습니다. 유효 권한이 필요하면 각 항목의 상세를 호출하십시오.
요청 헤더¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 원본 경로 및 요청 본문 서명 버전입니다. 생략한 뒤 이 페이지의 알고리즘을 계속 사용할 수 없습니다. 예: v20240417확인 또는 입력 방법: 이 페이지의 예시는 이 고정 버전을 사용하며 예시 서명 알고리즘과 함께 사용됩니다. |
|
| X-Df-Access-Key | string | Y | 이 모듈의 목록은 r 또는 w 권한을 사용할 수 있으며, GET 상세를 포함한 나머지 API는 모두 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 초 문자열을 생성합니다. |
Query 요청 매개변수¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| pageIndex | integer | 기본값 1, 최소 1. null 허용: False $minValue: 1 예: 1확인 또는 입력 방법: 1부터 시작하며 content.pageInfo.totalCount에 따라 다음 페이지로 진행합니다. |
|
| pageSize | integer | 기본값 20, 최대 100. null 허용: False $maxValue: 100 $minValue: 1 예: 20확인 또는 입력 방법: 클라이언트 필요에 따라 1~100 사이에서 선택합니다. |
|
| search | string | 선택 사항이며 이름에 포함 여부로 일치합니다. 생략하거나 공백이면 필터링하지 않습니다. null 허용: False 예: 예시확인 또는 입력 방법: 알려진 API Key 이름의 키워드를 입력합니다. |
|
| workspaceUUID | string | 선택적 워크스페이스 UUID입니다. 생략하거나 빈 문자열이면 모든 워크스페이스를 조회하며 특정 워크스페이스를 자동 선택하지 않습니다. 명시적으로 제공하는 것이 좋습니다. null 허용: False 예: wksp_example001확인 또는 입력 방법: 워크스페이스 목록의 content.data[].uuid에서 가져오고 워크스페이스 이름과 상태를 확인합니다. |
매개변수 추가 설명¶
사이트 수준 External API AK/SK를 사용하며, 서명 방식은 External API 서명 인증을 참조하십시오. 이 페이지에서 생성하는 워크스페이스 API Key와 External 서명 자격 증명은 동일한 자격 증명 세트가 아닙니다. External은 현재 AK/SK를 평문으로 반환하며 프런트엔드 페이지의 마스킹 정책을 적용하지 않습니다. 응답 예시는 모두 자리표시자 값을 사용하므로 실제 응답은 자격 증명으로 보관해야 합니다. 목록은 이미 영속화된 호출 통계를 읽으며, 프런트엔드 목록처럼 새로고침 대기 중인 통계 캐시를 병합하는 절차가 없으므로 통계가 지연될 수 있습니다.
요청 예시¶
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 = 'GET'
path = '/api/v1/workspace/accesskey/list'
query = {'workspaceUUID': 'wksp_example001', 'pageIndex': 1, 'pageSize': 20}
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.data | 객체 배열 | 현재 페이지 Key, 결과가 없으면 []입니다. |
| content.data[].id | integer 또는 null | 내부 레코드 순번이며 API 호출에는 uuid를 사용합니다. 생성 스냅샷은 flush 전에 가져오므로 이 필드는 null일 수 있습니다. |
| content.data[].uuid | string | API Key 레코드 UUID이며 호출 자격 증명 ak/sk와 다릅니다. |
| content.data[].status | integer | Key 상태: 0 활성화, 2 비활성화, 3 삭제됨. 목록/상세는 0만 반환하며, 삭제는 아직 삭제되지 않은 비활성화 Key도 처리할 수 있습니다. |
| content.data[].creator | string | 생성 주체이며 External에서 생성한 경우 일반적으로 external입니다. |
| content.data[].updator | string | 업데이트 주체이며 수정되지 않은 경우 비어 있을 수 있습니다. |
| content.data[].createAt | integer | 생성 Unix 초. |
| content.data[].deleteAt | integer | 삭제 Unix 초, 삭제되지 않은 경우 일반적으로 -1. |
| content.data[].updateAt | integer | 업데이트 Unix 초, 아직 수정되지 않은 경우 일반적으로 -1. |
| content.data[].name | string | API Key 표시 이름. |
| content.data[].ak | string | 워크스페이스 Access Key 호출 자격 증명 평문으로, 해당 워크스페이스의 OpenAPI 인증에 사용할 수 있습니다. 이 External 요청의 X-Df-Access-Key가 아닙니다. |
| content.data[].sk | string | 워크스페이스 Secret Key 평문이며 민감한 자격 증명으로 보관해야 합니다. 이 External 요청의 함께 사용하는 SK가 아닙니다. |
| content.data[].workspaceUUID | string | 소속 워크스페이스 UUID. |
| content.data[].accountUUID | string | 바인딩된 계정 UUID; 수동 워크스페이스 Key는 빈 문자열이며, 바인딩된 계정 Key의 유효 권한은 계정 역할에 따라 확인해야 합니다. |
| content.data[].createdWay | string | 출처 식별자, 예: manual, user, agent; 목록은 accountUUID가 비어 있지 않은 모든 Key를 제외합니다. |
| content.data[].businessType | string | 시스템 비즈니스 유형 식별자, 수동 Key는 일반적으로 비어 있습니다. |
| content.data[].isSystem | integer | 시스템 내장 Key 여부; 이 모듈의 조회/작업은 시스템 Key를 필터링합니다. |
| content.data[].isOwnerRole | integer | Owner 전용 Key 여부, 1은 예, 0은 아니요; 동일 워크스페이스에 삭제되지 않은 Owner Key가 최대 하나 있습니다. |
| content.data[].remark | string | 기존 비고; 이 External 공개 추가/수정 매개변수에는 remark가 포함되지 않습니다. |
| content.data[].isBurnAfterReading | integer | 보존된 열람 후 소멸 표시입니다. 이 모듈은 읽은 후 파기 기능을 수행하지 않으므로 이 값에 의존해 자격 증명을 철회해서는 안 됩니다. |
| content.data[].callCount | integer 또는 null | 영속 누적 호출 횟수입니다. 비동기 통계이므로 실시간 카운트가 아닙니다. 생성 스냅샷은 flush 전에 null일 수 있습니다. |
| content.data[].lastCallAt | integer 또는 null | 마지막 호출 Unix 초이며 일반적으로 -1은 아직 기록이 없음을 의미합니다. 생성 스냅샷은 null일 수 있습니다. |
| content.pageInfo.pageIndex | integer | 현재 페이지 번호. |
| content.pageInfo.pageSize | integer | 페이지당 항목 수. |
| content.pageInfo.count | integer | 이 페이지의 항목 수. |
| content.pageInfo.totalCount | integer | 필터링된 전체 항목 수. |
{
"code": 200,
"content": {
"data": [
{
"id": 1001,
"uuid": "wsak_example001",
"status": 0,
"creator": "external",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "예시 읽기 전용 API Key",
"ak": "<workspace-api-key>",
"sk": "<workspace-secret-key>",
"workspaceUUID": "wksp_example001",
"accountUUID": "",
"createdWay": "manual",
"businessType": "",
"isSystem": 0,
"isOwnerRole": 0,
"remark": "",
"isBurnAfterReading": 0,
"callCount": 0,
"lastCallAt": -1
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 20,
"count": 1,
"totalCount": 1
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
일치하는 Key가 없을 때:
{
"code": 200,
"content": {
"data": [],
"pageInfo": {
"pageIndex": 1,
"pageSize": 20,
"count": 0,
"totalCount": 0
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
다음 표는 확인된 요청 및 비즈니스 분기를 나열합니다. 일반 데이터베이스/캐시/감사 5xx는 전역 래퍼를 통해 ft.InternalServerError로 반환됩니다. 쓰기 API가 오류를 반환할 때 이름, Owner 플래그, 역할 또는 삭제 상태가 이미 저장되었을 수 있으므로 먼저 현재 상태를 조회한 후 다음 단계를 결정해야 합니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 선언된 검증 조건 위반 | 매개변수 파싱 실패 | 매개변수 위치, 필드 이름, 유형 및 값을 확인하십시오. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시 무효화, 감사 또는 처리되지 않은 필드 예외 | 내부 오류 | traceId를 보관하고 Key의 현재 이름, 역할 및 상태를 확인하십시오. 데이터가 먼저 커밋된 후 실패할 수 있으므로 500만 보고 적용되지 않았다고 판단할 수 없습니다. |