목록¶
GET /api/v1/role/list
개요¶
대상 워크스페이스의 역할을 페이지 단위로 나열합니다.
호출 전 및 사용 단계¶
대상 워크스페이스의 API Key로 호출합니다. 목록에는 워크스페이스에 적용되는 시스템 내장, 관리 콘솔 내장 및 워크스페이스 사용자 정의 역할이 포함됩니다. 특정 역할을 찾을 때는 이름으로 필터링하고, 안정적인 식별자로 uuid를 읽습니다.
사이트 도메인 표에서 소속 사이트의 OpenAPI 주소를 선택합니다.
요청 헤더¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI Key 자격 증명입니다. 전체 키 값을 사용하며 API Key 레코드의 UUID는 사용하지 않습니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 이 API 권한이 있는 Key를 생성하거나 가져옵니다. |
Query 요청 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| search | string | 이름으로 부분 일치합니다. 생략하거나 공백을 전달하면 이름으로 필터링하지 않습니다. null 허용: False 예: 只读가져오기 또는 입력 방법: 콘솔 역할 관리 페이지에 표시되는 역할 이름 또는 그 일부를 사용합니다. |
|
| statMember | boolean | 소문자 true를 전달한 경우에만 멤버 수를 집계하고 각 역할에 memberCount를 추가합니다. 기본적으로 집계하지 않습니다. null 허용: False 예: true가져오기 또는 입력 방법: 역할 멤버 수를 표시해야 할 때 URL 쿼리 매개변수 statMember=true를 설정합니다. |
|
| pageSize | integer | 페이지당 항목 수이며 기본값은 100입니다. 양의 정수를 전달하세요. null 허용: False 예: 100가져오기 또는 입력 방법: 클라이언트에 필요한 페이지 크기에 맞게 정수를 입력합니다. |
|
| pageIndex | integer | 페이지 번호이며 기본값은 1입니다. null 허용: False 예: 1가져오기 또는 입력 방법: 1부터 시작하여 페이지마다 증가시키고, 응답의 페이지 번호로 확인합니다. |
매개변수 추가 설명¶
워크스페이스는 요청의 DF-API-KEY로 결정됩니다.
요청 예시¶
curl --get -H "DF-API-KEY: <DF-API-KEY>" \
"https://openapi.guance.com/api/v1/role/list" \
--data-urlencode "search=只读" \
--data-urlencode "statMember=true" \
--data-urlencode "pageIndex=1"
응답¶
HTTP 200, application/json.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.data | array<object> |
이 페이지의 결과이며, 레코드가 없으면 빈 배열입니다. |
| content.data[].id | integer | 역할 레코드 ID입니다. |
| content.data[].uuid | string | 역할 UUID이며, 이후 역할 상세를 조회할 때 이 필드를 사용합니다. |
| content.data[].name | string | 역할 이름입니다. |
| content.data[].desc | string | 역할 설명입니다. |
| content.data[].isSystem | integer | 1은 시스템 내장 역할, 0은 기타 역할을 나타냅니다. |
| content.data[].workspaceUUID | string | 역할이 속한 또는 적용되는 워크스페이스이며, 시스템 내장 역할은 비어 있을 수 있습니다. |
| content.data[].builtinRoleUUID | string | 관리 콘솔 내장 역할 템플릿 UUID이며, 템플릿이 없으면 비어 있습니다. |
| content.data[].isAllWorkspace | integer | 관리 콘솔 내장 역할이 모든 워크스페이스에 적용되는지 여부이며, 0은 아니요, 1은 예입니다. |
| content.data[].isManageBuiltinRole | boolean | 관리 콘솔을 통해 정의되고 적용된 내장 역할인지 여부입니다. |
| content.data[].creator | string | 생성자 식별자입니다. |
| content.data[].updator | string | 마지막 업데이트자 식별자입니다. |
| content.data[].createAt | integer | 생성 시간입니다. Unix 초입니다. |
| content.data[].updateAt | integer | 마지막 업데이트 시간입니다. Unix 초입니다. |
| content.data[].deleteAt | integer | 삭제 시간(Unix 초)이며, 삭제되지 않은 경우 -1입니다. |
| content.data[].status | integer | 역할 레코드 상태입니다. |
| content.data[].creatorInfo | object | 생성자 정보이며, 조회할 수 없으면 {}입니다. |
| content.data[].updatorInfo | object | 마지막 업데이트자 정보이며, 조회할 수 없으면 {}입니다. |
| content.data[].memberCount | integer | statMember=true인 경우에만 반환됩니다. 멤버 기준으로 중복을 제거하며, 역할을 직접 부여받은 멤버와 그룹을 통해 해당 역할을 획득한 멤버를 포함합니다. |
| pageInfo | object | 페이지 정보입니다. |
| pageInfo.pageIndex | integer | 현재 페이지 번호이며 1부터 시작합니다. |
| pageInfo.pageSize | integer | 페이지당 항목 수입니다. |
| pageInfo.count | integer | 현재 페이지에서 반환된 레코드 수입니다. |
| pageInfo.totalCount | integer | 조건을 충족하는 역할의 총수이며, 현재 페이지에 레코드가 없어도 총 페이지 수를 계산하는 데 사용할 수 있습니다. |
| content.declaration | object 또는 null | 워크스페이스의 공개 선언 데이터이며, 구성이 비어 있으면 null일 수 있습니다. |
{
"code": 200,
"content": {
"data": [
{
"id": 101,
"uuid": "role_example",
"name": "日志只读",
"desc": "查询应用日志",
"isSystem": 0,
"workspaceUUID": "wksp_example",
"builtinRoleUUID": "",
"isAllWorkspace": 0,
"isManageBuiltinRole": false,
"status": 0,
"creatorInfo": {},
"updatorInfo": {},
"memberCount": 2
}
],
"declaration": null
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE",
"pageInfo": {
"pageIndex": 1,
"pageSize": 100,
"count": 1,
"totalCount": 1
}
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 선언되지 않은 Query 매개변수를 전달함 | 메시지에서 유효하지 않은 매개변수를 나타냅니다. | 매개변수 표에 나열되지 않은 필드를 제거합니다. |