콘텐츠로 이동

목록 조회



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 파라미터를 전달함 메시지에 유효하지 않은 파라미터가 표시됩니다. 파라미터 표에 나열되지 않은 필드를 제거합니다.

문서 평가

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