수정¶
POST /api/v1/workspace/accesskey/{ak_uuid}/modify
개요¶
API Key 이름을 수정하고 직접 역할 연결을 교체합니다.
호출 전 및 사용 단계¶
External 자격 증명에 대한 w 권한이 필요합니다. name은 필수이며, 역할만 변경하려는 경우에도 현재 이름을 전달해야 합니다. roleUUIDs를 생략하면 기존 역할 연결이 유지됩니다. 명시적 배열은 증분 추가가 아니라 전체 대상으로 교체합니다. []로 권한을 취소하지 마십시오. 유효한 연결이 없으면 인증이 wsAdmin으로 폴백될 수 있습니다. 자격 증명을 취소해야 하는 경우 Key를 삭제하십시오. owner를 포함하면 Owner 전용 Key로 변환되며 다른 대상 역할은 무시되고 공간당 최대 하나입니다. Owner에서 비Owner 배열로 전환하면 Owner 플래그가 취소됩니다. Agent 소스에 바인딩된 Key는 수정할 수 없습니다. 이름/Owner 플래그가 먼저 커밋된 후 역할 검증 및 업데이트가 수행되므로 InvalidRoleUUID 등의 400 오류가 발생해도 이미 이름이나 Owner 플래그가 변경되었을 수 있습니다. 먼저 상세 정보를 읽어 현재 상태를 확인한 후 다시 시도하십시오. 이 작업은 ak/sk를 로테이션하지 않습니다.
라우트 매개변수¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| ak_uuid | string | Y | API Key 레코드 UUID(일반적으로 wsak_ 접두사)이며 ak/sk 호출 자격 증명이 아닙니다. 이 External 경로는 UUID로 공간을 넘어 위치를 찾으므로 실행 전에 workspaceUUID를 확인하십시오. 예시: wsak_example001획득 또는 입력 방법: API Key 목록의 content.data[].uuid 또는 생성 성공 시 content.uuid에서 가져옵니다. |
요청 헤더¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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일 수 없습니다. null 허용: False 최대 길이: 256 예시: 示例API Key新名称획득 또는 입력 방법: API Key 상세에서 현재 name을 가져오고, 필요한 경우에만 새 이름으로 변경합니다. |
| roleUUIDs | array | 선택 사항입니다. 생략하면 기존 연결이 유지됩니다. 명시적 배열은 전체를 교체합니다. []는 연결을 지우지만 인증이 관리자로 폴백될 수 있으므로 권한 취소에 사용할 수 없습니다. owner는 특별한 권한 상승 의미를 가지며 null은 허용되지 않습니다. null 허용: False 예시: ["role_example001"]획득 또는 입력 방법: 공간 역할 목록에서 대상 공간의 실제 역할 uuid를 가져옵니다. 명시적인 최소 권한 사용자 정의 역할 또는 내장 readOnly/general 등을 사용하는 것이 좋습니다. |
매개변수 추가 설명¶
사이트 수준 External API AK/SK를 사용하며, 서명 방식은 External API 서명 인증을 참조하십시오. 이 페이지에서 생성하는 워크스페이스 API Key는 External 서명 자격 증명과 동일한 자격 증명 세트가 아닙니다. External은 현재 AK/SK를 평문으로 반환하며 프런트엔드 페이지의 마스킹 정책을 적용하지 않습니다. 응답 예제는 모두 자리 표시자 값을 사용하므로 실제 응답은 자격 증명으로 보관해야 합니다. 수정 후 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 = 'POST'
path = '/api/v1/workspace/accesskey/wsak_example001/modify'
query = {}
data = {'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 | 객체 배열 | 이번 응답의 역할 연결 요약입니다. Owner 전환 등의 분기에서는 []일 수 있으며, isOwnerRole과 함께 상세를 호출하여 유효 roles/permissions를 확인해야 합니다. |
| content.roleInfo[].uuid | string | 역할 UUID. |
| content.roleInfo[].name | string | 역할 이름. |
{
"code": 200,
"content": {
"id": 1001,
"uuid": "wsak_example001",
"status": 0,
"creator": "external",
"updator": "external",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": 1785427200,
"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,
"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을 전체 요청 본문으로 사용하지 마십시오. |
| 404 | ft.AKNotExistOrDelete | UUID에 해당하는 활성 비시스템 API Key가 없거나 Key가 이미 삭제/비활성화됨 | 지정한 AK가 존재하지 않거나 삭제되었습니다 | 목록에서 대상 uuid를 다시 가져오십시오. 목록은 바인딩 계정 Key를 표시하지 않으며 시스템 내장 Key는 이 진입점으로 관리할 수 없습니다. |
| 400 | ft.AKNameRepeat | 대상 공간에 동일한 이름의 삭제되지 않은 API Key가 이미 존재함 | 동일한 이름의 AK가 이미 존재합니다 | 먼저 이름을 조회하십시오. 기존 Key를 변경해야 하는 경우 수정을 사용하며, 중복 생성으로 멱등 성공을 대체해서는 안 됩니다. |
| 400 | ft.AKOnwerRepeat | 동일 공간에 삭제되지 않은 다른 Owner Key가 이미 존재함 | 소유자 AK가 이미 존재합니다 | 기존 Owner Key를 먼저 확인하고, 중복 생성 또는 동시 권한 상승으로 여러 Owner Key를 만들지 마십시오. |
| 400 | ft.InvalidRoleUUID | 역할 UUID가 대상 공간의 유효 역할 집합에 없음 | 유효하지 않은 역할 UUID: {} | 대상 공간 역할 목록에서 다시 선택하십시오. 수정 인터페이스는 이름 또는 Owner 플래그를 먼저 저장했을 수 있으므로 이 400 오류가 발생한 후에도 반드시 현재 상태를 먼저 읽어야 합니다. |
| 400 | ft.AgentWorkspaceAKCanNotModify | 대상이 createdWay=agent이고 계정에 바인딩된 Key임 | agent에 바인딩된 API Key는 수정할 수 없습니다 | 해당 Agent/계정 기능을 통해 관리하고 이 인터페이스로 이름이나 역할을 변경하지 마십시오. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시 무효화, 감사 또는 처리되지 않은 필드 예외 | 내부 오류 | traceId를 보존하고 Key의 현재 이름, 역할 및 상태를 확인하십시오. 데이터가 먼저 커밋된 후 실패할 수 있으므로 500만 보고 적용되지 않았다고 판단해서는 안 됩니다. |