생성¶
POST /api/v1/role/add
개요¶
현재 API Key 워크스페이스에서 사용자 지정 역할을 생성하고 권한 집합을 저장합니다.
호출 전 준비 및 사용 단계¶
먼저 역할 이름과 최소 필요 권한을 확인한 후 name과 비어 있지 않은 keys를 제출합니다. desc는 생략할 수 있습니다. 생성 시 구성원이나 API Key가 해당 역할에 자동으로 바인딩되지 않으며, 이후 구성원 권한 부여 등의 인터페이스에서는 반환된 uuid를 사용합니다. 서버는 중복을 제거하고 선택 가능한 권한을 확장하며 routine.defaultAccess를 자동으로 추가합니다. 생성 응답은 최종 권한 목록을 직접 반환하지 않으므로 역할 상세의 permissions를 다시 조회하세요. workspace/cloudAccount/cloudBilling/rumApp 등 레거시 와일드카드 그룹의 경우 새로 공개된 관리자 권한이 기존 와일드카드 그룹으로 인해 자동 부여되지 않으므로, 선택 가능 범위에 따라 해당 리프 키를 명시적으로 제출해야 합니다. 시간 초과 후에는 동일한 이름의 역할이 이미 생성되었는지 먼저 조회하여 중복 요청을 피하세요.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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 | Y | 권한 키 문자열 배열입니다. 생성 시 필수이며, 수정 시 선언상 선택 사항이지만 실제로는 사용 가능한 권한을 하나 이상 제공해야 합니다. 업데이트 시 기존 권한을 전체 교체하며 추가하지 않습니다. null 허용: False 예: ["anomaly.issueManage"]가져오기 또는 입력 방법: 콘솔의 역할 관리에서 현재 사용자 지정 역할로 선택할 수 있는 권한을 확인하세요. 동일 유형 사용자 지정 역할의 역할 상세에 있는 content.permissions를 참고하여 업무 필요에 따라 구체적인 리프 키를 선택할 수도 있습니다. 시스템 역할 전용 권한을 그대로 복사하지 마세요. |
| name | string | Y | 역할 이름으로, 생성/수정 모두 필수이며 최대 256자입니다. null 허용: False 최대 길이: 256 예: 异常协作处理가져오기 또는 입력 방법: 먼저 역할 목록에서 현재 워크스페이스에서 조회 가능한 역할을 확인하고 사용 중이지 않은 이름을 선택하세요. |
추가 파라미터 설명¶
생성 성공 후 역할 상세를 통해 실제 권한을 확인하며, 역할 목록은 워크스페이스 구성원 목록 등 권한 부여 흐름에서 선택할 수 있습니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/role/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"异常协作处理","desc":"允许处理异常追踪问题。","keys":["anomaly.issueManage"]}'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.id | integer 또는 null | 레코드 번호. 생성 시 제출 전에 구성되어 null일 수 있으므로 리소스 작업에는 uuid를 사용하세요. |
| content.uuid | string | 생성된 role_ 역할 UUID. |
| content.workspaceUUID | string | 소속 워크스페이스. |
| content.name | string | 역할 이름. |
| content.desc | string | 역할 설명. |
| content.isSystem | integer | 생성된 사용자 지정 역할은 0입니다. |
| content.builtinRoleUUID | string | 관리 내장 템플릿 UUID. 일반 직접 생성 역할은 비어 있습니다. |
| content.isAllWorkspace | integer | 워크스페이스 간 내장 템플릿 적용 표시. 일반 직접 생성 역할은 0입니다. |
| content.status | integer | 레코드 상태. 생성 성공 시 0입니다. |
| content.creator | string | 생성 주체. |
| content.updator | string | 수정 주체. 초기에는 빈 문자열입니다. |
| content.createAt | integer | 생성 시간. Unix 초. |
| content.updateAt | integer | 수정 시간. Unix 초, 초기 -1. |
| content.deleteAt | integer | 삭제 시간. Unix 초, 미삭제 시 -1. |
| content.declaration | object 또는 null | 워크스페이스 공통 선언. |
{
"code": 200,
"content": {
"id": null,
"uuid": "role_example",
"workspaceUUID": "wksp_example",
"name": "异常协作处理",
"desc": "允许处理异常追踪问题。",
"isSystem": 0,
"builtinRoleUUID": "",
"isAllWorkspace": 0,
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785430800,
"updateAt": -1,
"deleteAt": -1,
"declaration": {}
},
"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를 제공하세요. |