목록¶
GET /api/v1/workspace/inner_accesskey/list
개요¶
각 워크스페이스에서 활성 상태인 inner sys 시스템 Key를 페이지 단위로 조회합니다.
호출 전 준비 및 사용 단계¶
대상 워크스페이스의 내장 자격 증명을 읽기 전용으로 확인하려면 workspaceUUIDs를 명시적으로 전달하는 것이 좋습니다. 이 Query 매개변수는 영문 쉼표로 연결된 문자열이며 JSON 배열이 아닙니다. 각 항목의 앞뒤 공백은 제거하고 빈 항목은 무시합니다. 생략하거나 최종적으로 비어 있으면 이 서비스의 모든 워크스페이스에서 활성 상태인 inner sys Key를 조회합니다. 레코드 id 기준 내림차순으로 정렬합니다. 기본값은 pageIndex=1, pageSize=50이며 최대 100입니다. search는 실제로 Access Key 평문 포함 일치로 검색하며 이름이나 SK로는 검색하지 않습니다. 목록은 id를 제외한 전체 Key 엔터티를 반환하며 AK/SK를 포함합니다. 역할이나 권한 요약은 반환하지 않습니다. 일치하는 항목이 없으면 빈 목록을 반환하며 워크스페이스를 찾을 수 없다는 오류는 발생하지 않습니다.
요청 헤더¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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 초 문자열을 생성합니다. |
Query 요청 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| pageIndex | integer | 기본값은 1이며 최소값은 1입니다. null 허용: False $minValue: 1 예: 1조회 또는 입력 방법: 처음에는 1로 설정하고 이후 content.pageInfo에 따라 페이지 번호를 진행합니다. |
|
| pageSize | integer | 기본값은 50이며 최대값은 100입니다. null 허용: False $maxValue: 100 $minValue: 1 예: 50조회 또는 입력 방법: 클라이언트 요구에 따라 1~100 범위에서 선택합니다. |
|
| search | string | 선택 사항입니다. 앞뒤 공백을 제거한 후 AK 포함 일치로 검색합니다. 생략하거나 공백만 있으면 필터링하지 않습니다. name/SK로는 일치시키지 않습니다. null 허용: False 예: known-ak-part조회 또는 입력 방법: 기존 내장 Key 목록 응답의 ak 또는 안전하게 저장한 Access Key에서 키워드를 가져옵니다. |
|
| workspaceUUIDs | commaArray | 선택 사항인 CSV 문자열입니다. 생략하거나 빈 문자열이거나 빈 항목만 있으면 모든 워크스페이스를 조회합니다. 단일 워크스페이스에는 대괄호를 추가하지 않습니다. null 허용: False 예: wksp_example001조회 또는 입력 방법: 워크스페이스 목록에서 하나 이상의 워크스페이스 uuid를 가져와 영문 쉼표로 연결합니다. |
매개변수 추가 설명¶
사이트 수준 External API 자격 증명을 사용하며 인증은 External API 서명 인증을 참조합니다. 목록은 r 또는 w 권한을 사용할 수 있으며, 나머지 세 항목은 GET 초기화를 포함해 w 권한이 필요합니다. 모든 응답은 높은 권한의 자격 증명 평문을 반환할 수 있으므로 일반 프런트엔드 페이지의 마스킹 표시 규칙을 적용해서는 안 됩니다. 예제는 자리 표시자 값을 사용하며 실제 자격 증명은 안전하게 보관해야 합니다.
요청 예제¶
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/inner_accesskey/list'
query = {'workspaceUUIDs': 'wksp_example001', 'pageIndex': 1, 'pageSize': 50}
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[].uuid | string | API Key 레코드 UUID이며 호출 자격 증명 ak/sk와 다릅니다. |
| content.data[].status | integer | 내장 Key 상태입니다. 이 모듈의 조회 및 삭제에서는 status=0을 선택합니다. |
| 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 | 내장 Key 이름이며 초기화 시 inner입니다. |
| content.data[].ak | string | 내장 시스템 Access Key 평문이며 높은 권한의 자격 증명으로 보관해야 합니다. External 서명 AK가 아닙니다. |
| content.data[].sk | string | 내장 시스템 Secret Key 평문이며 높은 권한의 자격 증명으로 보관해야 합니다. External 서명 SK가 아닙니다. |
| content.data[].workspaceUUID | string | 소속 워크스페이스 UUID입니다. |
| content.data[].accountUUID | string | 바인딩된 계정 식별자이며 초기화된 시스템 Key에서는 일반적으로 빈 문자열입니다. |
| content.data[].createdWay | string | 생성 출처입니다. 초기화 시 일반적으로 manual이며 시스템 범위는 isSystem/businessType으로 구분합니다. |
| content.data[].businessType | string | 이 모듈은 inner sys 유형만 관리합니다. |
| content.data[].isSystem | integer | 이 모듈은 시스템 내장 Key만 관리하며 초기화 시 1입니다. |
| content.data[].isOwnerRole | integer | 초기화 시 1이며 Owner 역할 의미를 가집니다. 일반 수동 Owner Key와 별도로 관리합니다. |
| content.data[].remark | string | 기존 비고입니다. 이 모듈에는 비고를 수정하는 요청 매개변수가 없습니다. |
| 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": [
{
"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": 0,
"lastCallAt": -1
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 50,
"count": 1,
"totalCount": 1
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
일치하는 Key가 없을 때:
{
"code": 200,
"content": {
"data": [],
"pageInfo": {
"pageIndex": 1,
"pageSize": 50,
"count": 0,
"totalCount": 0
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조합니다.
매개변수가 선언과 일치하지 않으면 공통 요청 오류를 반환합니다. 데이터베이스, 캐시 등의 일반 내부 예외는 최종적으로 500 ft.InternalServerError로 통일됩니다. 쓰기 요청이 실패한 후에는 영속 상태와 캐시를 먼저 확인해야 하며, 전혀 반영되지 않았다고 보장할 수 없습니다.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반한 경우 | 매개변수 구문 분석 실패 | 매개변수 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시 무효화 또는 명시적으로 처리되지 않은 내부 예외 | 내부 오류 | traceId를 저장하고 Key의 현재 상태와 실제 호출 결과를 먼저 확인한 후 재시도 여부를 결정합니다. 데이터베이스에 이미 커밋되었을 수 있으므로 오류 응답만으로 변경이 없었다고 판단해서는 안 됩니다. |