수정¶
POST /api/v1/role/{role_uuid}/modify
개요¶
워크스페이스 사용자 정의 역할의 이름, 선택적 설명 및 전체 권한 집합을 수정합니다.
호출 전 및 사용 단계¶
먼저 역할 상세를 조회하여 기존 권한을 저장한 다음, 전체 대상 keys와 필수 name을 제출합니다. keys는 기존 권한을 전체 교체합니다. 생략하거나 []를 전달하면 RolePermissionFormatInvalid가 발생하며, 모든 권한을 비우는 데 사용할 수 없습니다. desc를 생략하면 기존 값을 유지하고, 빈 문자열을 전달하면 비웁니다. 관리 백오피스 애플리케이션의 기본 제공 역할은 이 API를 통해 수정할 수 없습니다. 워크스페이스 사용자 정의 역할에 사용할 경우, 기존 멤버 및 API Key에 대한 권한 영향을 먼저 확인하세요. 권한 관계가 저장되면 연결된 계정과 API Key의 권한 캐시 새로 고침이 호출되며, 기존 역할 바인딩은 제거되지 않습니다. 실패 시 새 권한이 이미 저장되었을 수 있으므로 먼저 조회한 후 재시도하세요. 서버는 선택 가능한 권한의 중복을 제거하고 확장하며, routine.defaultAccess를 자동으로 추가합니다. 수정 성공 시 true만 반환하고 최종 권한 목록을 직접 반환하지 않으므로, 역할 상세의 permissions를 다시 조회하세요. workspace/cloudAccount/cloudBilling/rumApp 등 레거시 와일드카드 그룹의 경우, 새로 개방된 관리자 권한은 기존 와일드카드 그룹으로 인해 자동 부여되지 않으며, 선택 가능한 범위에 따라 해당 리프 키를 명시적으로 제출해야 합니다.
경로 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| role_uuid | string | Y | 워크스페이스 사용자 정의 역할 UUID입니다. 이름이나 관리 백오피스의 기본 제공 역할 템플릿 UUID로 대체하지 마세요. 예: role_example가져오기 또는 입력 방법: 역할 목록의 content.data[].uuid에서 대상 워크스페이스 사용자 정의 역할을 가져올 수 있으며, 역할 상세로 확인할 수 있습니다. |
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| keys[*] | string | 단일 권한 키이며 형식은 group.permission이고, 현재 사용자 정의 역할의 선택 가능 범위에 있어야 합니다. group.*는 허용된 범위에 따라 확장할 수 있으며, 리프 권한을 명시적으로 제출하는 것이 우선입니다. 예: anomaly.issueManage가져오기 또는 입력 방법: 콘솔 역할 관리에서 현재 사용자 정의 역할이 선택할 수 있는 권한을 확인하세요. 또는 동일한 유형의 사용자 정의 역할 역할 상세에 있는 content.permissions를 참고하여 업무 필요에 따라 구체적인 리프 키를 선택할 수 있습니다. 시스템 역할 전용 권한을 그대로 복사하지 마세요. |
|
| desc | string | 선택적 설명입니다. 생성 시 생략하면 빈 문자열이 되고, 수정 시 생략하면 원래 값을 유지하며, 빈 문자열을 전달하면 비울 수 있습니다. 런타임 선언 길이 상한은 3000자이지만 현재 저장 용량이 더 짧으므로 256자 이내로 유지하는 것이 좋습니다. 빈 문자열 허용: True null 허용: False 최대 길이: 3000 예: 允许处理异常追踪问题。가져오기 또는 입력 방법: 역할 용도에 따라 입력하세요. 현재 저장 용량과 일치하도록 256자 이내를 권장합니다. |
|
| keys | array | 권한 키 문자열 배열입니다. 생성 시 필수이며, 수정 시 선택 사항으로 선언되어 있지만 실제로는 사용 가능한 권한을 하나 이상 제공해야 합니다. 업데이트 시 기존 권한을 전체 교체하며 추가하지 않습니다. null 허용: False 예: ["anomaly.issueManage"]가져오기 또는 입력 방법: 콘솔 역할 관리에서 현재 사용자 정의 역할이 선택할 수 있는 권한을 확인하세요. 또는 동일한 유형의 사용자 정의 역할 역할 상세에 있는 content.permissions를 참고하여 업무 필요에 따라 구체적인 리프 키를 선택할 수 있습니다. 시스템 역할 전용 권한을 그대로 복사하지 마세요. |
|
| name | string | Y | 역할 이름이며 생성/수정 모두 필수이고 최대 256자입니다. null 허용: False 최대 길이: 256 예: 异常协作处理가져오기 또는 입력 방법: 먼저 역할 목록에서 현재 워크스페이스에 표시되는 역할을 확인하고, 사용 중이 아닌 이름을 선택하세요. |
파라미터 추가 설명¶
대상 역할이 존재하지 않을 때 현재 경로에서 일반 내부 오류가 발생할 수 있으며, NotFoundRole가 안정적으로 반환되지 않습니다. 먼저 역할 목록이나 상세를 통해 확인하세요. 호출 실패 후에는 상세와 실제 접근 결과로 적용 상태를 확인하세요.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/role/role_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"异常协作处理","keys":["anomaly.issueManage"]}'
응답¶
HTTP 200, application/json입니다. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | boolean | 수정 프로세스는 true를 반환하며, 최종 권한은 역할 상세에서 조회합니다. |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인하세요. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하세요. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 단일 JSON 객체를 제출하세요. |
| 406 | ft.RolePermissionFormatInvalid | keys가 생략되었거나 비어 있거나 유효한 권한이 없거나, 권한이 group.permission 형식이 아님 | 역할의 권한 형식 오류 | 현재 선택 가능한 권한 키를 하나 이상 제출하세요. 각 항목은 점(.)으로 구분된 두 개의 세그먼트를 사용합니다. |
| 406 | ft.RolePermissionInvalid | 권한 그룹 또는 하위 권한이 현재 사용자 정의 역할의 선택 가능 집합에 없음 | 역할의 권한이 유효하지 않음 | 콘솔의 선택 가능 범위 또는 동일한 유형의 사용자 정의 역할 권한 상세에서 다시 선택하세요. |
| 400 | ft.RoleNameExists | 현재 워크스페이스 표시 범위에 동일한 이름의 역할이 존재함 | 역할 이름 {}이(가) 이미 존재합니다 |
사용 중이 아닌 이름을 사용하세요. |
| 500 | ft.InternalServerError | 저장, 권한 새로 고침 또는 기타 내부 처리 실패 | 내부 오류 | 먼저 역할 상세를 조회하여 저장된 이름과 권한을 확인한 후 재시도 여부를 결정하세요. 계속 실패하면 traceId를 제공하세요. |
| 400 | ft.InvalidAction | 관리 백오피스 애플리케이션의 기본 제공 역할을 수정하려고 함 | 유효하지 않은 작업 | 해당 관리 백오피스에서 해당 기본 제공 역할을 관리하거나 워크스페이스 사용자 정의 역할을 선택하세요. |