콘텐츠로 이동

수정



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 관리 백오피스 애플리케이션의 기본 제공 역할을 수정하려고 함 유효하지 않은 작업 해당 관리 백오피스에서 해당 기본 제공 역할을 관리하거나 워크스페이스 사용자 정의 역할을 선택하세요.

문서 평가

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