목록 조회¶
GET /api/v1/workspace/{workspace_uuid}/role/list
개요¶
대상 워크스페이스의 역할을 페이지 단위로 조회합니다.
호출 전 준비 및 사용 단계¶
워크스페이스 UUID를 지정합니다. 목록에는 워크스페이스에 적용되는 시스템 내장 역할, 관리 콘솔 내장 역할, 워크스페이스 사용자 지정 역할이 포함됩니다. 특정 역할을 찾아야 할 때는 이름으로 필터링하고, uuid를 안정적인 식별자로 읽습니다.
예시에서는 External API 서명 버전 v20240417을 사용합니다. 대상 사이트의 External API 주소, Access Key 및 Secret Key를 각각 DF_EXTERNAL_API_URL, DF_EXTERNAL_ACCESS_KEY, DF_EXTERNAL_SECRET_KEY로 설정합니다. 예시 ID는 실제 값으로 바꾸십시오.
라우트 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| workspace_uuid | string | Y | 대상 워크스페이스 UUID입니다. 예시: wksp_example가져오기 또는 입력 방법: 워크스페이스 목록 응답의 content.data[].uuid에서 가져와 원래 값을 사용합니다. |
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 서명 버전이며, 아래 예시에서는 v20240417을 사용합니다. 예시: v20240417가져오기 또는 입력 방법: 예시와 동일하게 입력하며, 서명 알고리즘과 대응됩니다. |
|
| X-Df-Access-Key | string | Y | 요청 AK 정보입니다. 예시: <access-key>가져오기 또는 입력 방법: External API 관리자가 할당합니다. |
| X-Df-Signature | string | Y | 서명 정보입니다. 예시: <hex-signature>가져오기 또는 입력 방법: Secret Key로 GET, nonce, 요청 경로 및 원본 쿼리 문자열, 타임스탬프, 빈 문자열로 구성된 텍스트에 HMAC-SHA256을 수행하고 16진수 결과를 사용합니다. |
| X-Df-Timestamp | string | Y | 요청 시점의 타임스탬프입니다. 예시: 1785456000가져오기 또는 입력 방법: 호출 시점의 현재 Unix 초를 입력합니다. 예: date +%s 실행. |
| X-Df-Nonce | string | Y | 요청 시 생성되는 임시 코드입니다. 예시: b53b47e12e514616ad8cb1f17cb66dce가져오기 또는 입력 방법: 각 요청마다 새 임의 값을 생성합니다. 예: uuid.uuid4().hex. |
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부터 시작하여 페이지마다 증가시키고, 응답의 페이지 번호로 확인합니다. |
파라미터 추가 설명¶
현재 대상 사이트에 할당된 External API 서명 자격 증명을 사용합니다.
요청 예시¶
import hmac
import os
import time
import uuid
from urllib.parse import urlencode
import requests
server = os.environ["DF_EXTERNAL_API_URL"].rstrip("/")
path = "/api/v1/workspace/wksp_example/role/list"
query = {'search': '只读', 'statMember': 'true', 'pageIndex': 1}
if query:
path += "?" + urlencode(query)
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
payload = " ".join(("GET", nonce, path, timestamp, ""))
signature = hmac.digest(os.environ["DF_EXTERNAL_SECRET_KEY"].encode(), payload.encode(), "sha256").hex()
headers = {
"X-Df-Access-Key": os.environ["DF_EXTERNAL_ACCESS_KEY"],
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-SVersion": "v20240417",
"X-Df-Signature": signature,
}
result = requests.get(server + path, headers=headers, timeout=15)
result.raise_for_status()
data = result.json()["content"]
응답¶
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 초 단위입니다. 발생하지 않은 경우 -1일 수 있습니다. |
| content.data[].deleteAt | integer | 삭제 시간이며 Unix 초 단위입니다. 삭제되지 않은 경우 -1입니다. |
| content.data[].status | integer | 역할 레코드 상태입니다. |
| content.data[].creatorInfo | object | 생성자 정보이며, 조회할 수 없으면 {}입니다. |
| content.data[].updatorInfo | object | 마지막 업데이트자 정보이며, 조회할 수 없으면 {}입니다. |
| content.data[].memberCount | integer | statMember=true인 경우에만 반환됩니다. 구성원 기준으로 중복 제거되며, 직접 부여받은 구성원과 그룹을 통해 해당 역할을 획득한 구성원을 포함합니다. |
| content.pageInfo | object | 페이지 정보입니다. |
| content.pageInfo.pageIndex | integer | 현재 페이지 번호이며 1부터 시작합니다. |
| content.pageInfo.pageSize | integer | 페이지당 항목 수입니다. |
| content.pageInfo.count | integer | 현재 페이지에서 반환된 레코드 수입니다. |
| content.pageInfo.totalCount | integer | 조건을 충족하는 역할의 총수이며, 총 페이지 수를 계산하는 데 사용됩니다. |
{
"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
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 100,
"count": 1,
"totalCount": 1
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 선언되지 않은 Query 파라미터를 전달함 | 메시지에 유효하지 않은 파라미터가 표시됩니다. | 파라미터 표에 나열되지 않은 필드를 제거합니다. |