생성¶
POST /api/v1/workspace/accesskey/add
개요¶
지정한 워크스페이스의 API Key를 생성하고 역할을 연결합니다.
호출 전 및 사용 단계¶
External 자격 증명에 대한 w 권한이 필요합니다. 먼저 워크스페이스의 활동 상태를 확인하고 대상 역할 UUID를 확보하십시오. 항상 비어 있지 않은 roleUUIDs를 명시적으로 제공할 것을 권장하며, 생략하면 관리자 Key가 생성되고, []도 인증 폴백으로 인해 관리자 권한을 얻을 수 있습니다. 생성은 이름 기준으로 멱등하지 않으므로 중복된 이름은 오류를 반환합니다. 타임아웃 발생 시 먼저 목록을 조회하여 생성 여부를 확인하십시오. 일반적으로 non-Owner 역할을 사용합니다. 현재 External 구현은 owner도 허용합니다. 즉, Owner 전용 Key만 생성하고 다른 역할 값은 무시하며, 동일 워크스페이스에는 삭제되지 않은 Owner Key가 최대 하나만 존재합니다. 성공하면 새 자격 증명과 역할 요약을 반환하며, id/호출 통계 등 생성 스냅샷 필드는 null일 수 있고 이후 상세 조회에서 영속화된 정보를 얻을 수 있습니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| roleUUIDs[*] | string | 단일 역할 UUID 문자열이며, 역할은 대상 워크스페이스의 허용 범위에 속해야 합니다. 예시: role_example001획득 또는 입력 방법: 워크스페이스 역할 목록에서 대상 워크스페이스의 실제 역할 uuid를 얻습니다. 명확한 최소 권한 사용자 정의 역할 또는 내장 readOnly/general 등을 사용할 것을 권장합니다. |
|
| name | string | Y | 필수 표시 이름이며 최대 256자입니다. 비어 있지 않고 중복되지 않는 문자열을 제공하십시오. null 허용: False 최대 길이: 256 예시: 示例只读API Key획득 또는 입력 방법: 먼저 API Key 목록에서 대상 워크스페이스의 기존 이름을 확인합니다. |
| roleUUIDs | array | 선택 사항이며, 생략하면 기본적으로 wsAdmin 관리자 역할이 됩니다. 확인된 비어 있지 않은 최소 권한 역할을 명시적으로 전달할 것을 권장합니다. 명시적 []로는 권한 없는 Key를 얻을 수 없습니다. 인증 시 유효한 역할 연결이 없으면 wsAdmin으로 폴백될 수 있으므로 빈 배열로 권한을 철회할 수 없습니다. null은 허용되지 않습니다.null 허용: False 예시: ["role_example001"]획득 또는 입력 방법: 워크스페이스 역할 목록에서 대상 워크스페이스의 실제 역할 uuid를 얻습니다. 명확한 최소 권한 사용자 정의 역할 또는 내장 readOnly/general 등을 사용할 것을 권장합니다. |
|
| workspaceUUID | string | Y | 필수 생성 대상 워크스페이스 UUID이며, 활동 상태 status=0인 기존 워크스페이스여야 합니다. 생략하거나 비우거나 null로 설정할 수 없습니다. null 허용: False 예시: wksp_example001획득 또는 입력 방법: 워크스페이스 목록의 content.data[].uuid에서 대상 워크스페이스를 얻고 확인합니다. |
파라미터 추가 설명¶
사이트 수준 External API AK/SK를 사용하며 서명 방식은 External API 서명 인증을 참조하십시오. 본 페이지에서 생성하는 워크스페이스 API Key와 External 서명 자격 증명은 동일한 자격 증명 세트가 아닙니다. External은 현재 AK/SK 평문을 반환하므로 프런트 페이지의 마스킹 정책을 적용하지 않습니다. 응답 예시는 모두 자리 표시자 값을 사용하므로 실제 응답은 자격 증명에 따라 보관해야 합니다. 본 인터페이스에는 accountUUID, createdWay, remark 또는 열람 후 소멸 등의 공개 입력 파라미터가 없으므로 계정에 바인딩된 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/accesskey/add'
query = {}
data = {'workspaceUUID': 'wksp_example001', 'name': '示例只读API Key', 'roleUUIDs': ['role_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.id | integer 또는 null | 내부 레코드 일련번호이며, 인터페이스 호출에는 uuid를 사용합니다. 생성 스냅샷은 flush 전에 획득되므로 이 필드는 null일 수 있습니다. |
| content.uuid | string | API Key 레코드 UUID이며 호출 자격 증명 ak/sk와 다릅니다. |
| content.status | integer | Key 상태: 0 활성화, 2 비활성화, 3 삭제됨. 목록/상세는 0만 반환하며, 삭제는 삭제되지 않은 비활성화 Key도 처리할 수 있습니다. |
| 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 | API Key 표시 이름. |
| content.ak | string | 워크스페이스 Access Key 호출 자격 증명 평문으로, 해당 워크스페이스의 OpenAPI 인증에 사용할 수 있으며 본 External 요청의 X-Df-Access-Key가 아닙니다. |
| content.sk | string | 워크스페이스 Secret Key 평문이며 민감한 자격 증명으로 보관해야 합니다. 본 External 요청의 함께 제공되는 SK가 아닙니다. |
| content.workspaceUUID | string | 소속 워크스페이스 UUID. |
| content.accountUUID | string | 바인딩된 계정 UUID이며, 수동 워크스페이스 Key는 빈 문자열입니다. 계정 바인딩 Key의 유효 권한은 계정 역할에 따라 확인해야 합니다. |
| content.createdWay | string | 출처 식별자(예: manual, user, agent)이며, 목록에서는 accountUUID가 비어 있지 않은 모든 Key를 제외합니다. |
| content.businessType | string | 시스템 비즈니스 유형 식별자이며 수동 Key는 일반적으로 비어 있습니다. |
| content.isSystem | integer | 시스템 내장 Key 여부이며, 본 모듈의 조회/작업은 시스템 Key를 필터링합니다. |
| content.isOwnerRole | integer | Owner 전용 Key 여부, 1은 예, 0은 아니요. 동일 워크스페이스에는 삭제되지 않은 Owner Key가 최대 하나만 존재합니다. |
| content.remark | string | 기존 비고이며, 본 External 공개 추가/수정 파라미터에는 remark가 포함되지 않습니다. |
| content.isBurnAfterReading | integer | 보존된 열람 후 소멸 플래그이며, 본 모듈은 읽은 후 파기하지 않으므로 이를 의존해 자격 증명을 철회해서는 안 됩니다. |
| content.callCount | integer 또는 null | 영속 누적 호출 횟수이며 비동기 집계이므로 실시간 카운트가 아닙니다. 생성 스냅샷은 flush 전에 null일 수 있습니다. |
| content.lastCallAt | integer 또는 null | 마지막 호출 Unix 초이며 일반적으로 -1은 기록 없음을 의미합니다. 생성 스냅샷은 null일 수 있습니다. |
| content.roleInfo | 객체 배열 | 생성 시 연결된 역할 요약이며, 명시적 []는 []를 반환할 수 있으므로 이를 근거로 유효 권한이 비어 있다고 판단할 수 없습니다. |
| content.roleInfo[].uuid | string | 역할 UUID. |
| content.roleInfo[].name | string | 역할 이름. |
{
"code": 200,
"content": {
"id": null,
"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": null,
"lastCallAt": null,
"roleInfo": [
{
"uuid": "role_example001",
"name": "示例最小权限角色"
}
]
},
"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을 전체 요청 본문으로 사용하지 마십시오. |
| 401 | ft.WKSPNotExistOrReleased | 대상 워크스페이스가 존재하지 않거나 활동 상태 status=0이 아님 | 워크스페이스가 존재하지 않음/또는 이미 해제됨 | 워크스페이스 목록에서 유효한 워크스페이스를 선택하십시오. |
| 400 | ft.AKNameRepeat | 대상 워크스페이스에 동일한 이름의 삭제되지 않은 API Key가 이미 존재 | 동일한 이름의 AK가 이미 존재 | 먼저 이름을 조회하십시오. 기존 Key를 변경하려면 수정을 사용해야 하며, 중복 생성으로 멱등 성공을 대체할 수 없습니다. |
| 400 | ft.AKOnwerRepeat | 동일 워크스페이스에 삭제되지 않은 다른 Owner Key가 이미 존재 | 소유자 AK가 이미 존재 | 기존 Owner Key를 먼저 확인하고, 중복 생성이나 동시 권한 상승으로 여러 Owner Key를 만들지 마십시오. |
| 400 | ft.InvalidRoleUUID | 역할 UUID가 대상 워크스페이스의 유효한 역할 집합에 없음 | 유효하지 않은 역할 UUID: {} | 대상 워크스페이스의 역할 목록에서 다시 선택하십시오. 수정 인터페이스는 이름이나 Owner 플래그를 이미 저장했을 수 있으므로, 이 400이 발생한 후에도 먼저 현재 상태를 읽어야 합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시 무효화, 감사 또는 처리되지 않은 필드 예외 | 내부 오류 | traceId를 보관하고 Key의 현재 이름, 역할 및 상태를 확인하십시오. 데이터가 먼저 커밋된 후 실패할 수 있으므로 500만으로 적용되지 않았다고 판단할 수 없습니다. |