콘텐츠로 이동

생성



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만으로 적용되지 않았다고 판단할 수 없습니다.

문서 평가

이 페이지가 도움이 되었나요?