목록 조회¶
GET /api/v1/workspace/list
개요¶
현재 사이트에서 확인할 수 있는 삭제되지 않은 워크스페이스를 페이지 단위로 나열합니다.
호출 전 및 사용 단계¶
먼저 이름 또는 UUID로 검색한 다음, 결과의 uuid를 사용하여 워크스페이스 상세, 할당량 또는 역할을 조회할 수 있습니다. 검색 결과에 여러 워크스페이스가 반환되면 이름과 UUID를 확인하세요. 필드 표와 예시는 자주 사용하는 필드를 보여줍니다. 인터페이스는 워크스페이스 자격 증명 정보를 반환할 수 있으므로, 로그와 티켓에는 문제 해결에 필요한 필드만 남기세요.
예시는 External API 서명 버전 v20240417을 사용합니다. 대상 사이트의 External API 주소, Access Key, Secret Key를 각각 DF_EXTERNAL_API_URL, DF_EXTERNAL_ACCESS_KEY, DF_EXTERNAL_SECRET_KEY로 설정하세요. 예시 ID는 실제 값으로 교체하세요.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 서명 버전이며, 아래 예시는 v20240417을 사용합니다. 예시: v20240417획득 또는 입력 방법: 예시와 동일하게 입력하며, 서명 알고리즘과 대응됩니다. |
|
| X-Df-Access-Key | string | Y | 요청 AK 정보 예시: <access-key>획득 또는 입력 방법: External API 관리자가 할당합니다. |
| X-Df-Signature | string | Y | 서명 정보 예시: <hex-signature>획득 또는 입력 방법: GET, nonce, 요청 경로 및 원본 쿼리 문자열, 타임스탬프, 빈 문자열로 구성된 텍스트를 Secret Key로 HMAC-SHA256 처리하여 16진수 결과를 사용합니다. |
| X-Df-Timestamp | string | Y | 요청 시점의 타임스탬프 예시: 1785456000획득 또는 입력 방법: 호출 시점의 현재 Unix 초를 입력합니다(예: date +%s 실행). |
| X-Df-Nonce | string | Y | 요청 시 생성하는 임시 코드 예시: b53b47e12e514616ad8cb1f17cb66dce획득 또는 입력 방법: 요청마다 새로운 임의 값을 생성합니다(예: uuid.uuid4().hex). |
Query 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| search | string | 이름, UUID의 부분 일치를 지원하며, 내부 숫자 ID는 전체 일치도 가능합니다. 생략하거나 비워 두면 키워드로 필터링하지 않습니다. null 허용: False 예시: 生产획득 또는 입력 방법: 콘솔 또는 관리 백엔드에서 확인 가능한 워크스페이스 이름, UUID 일부 또는 알고 있는 내부 숫자 ID를 입력합니다. |
|
| pageIndex | integer | 페이지 번호, 기본값 1. null 허용: False $minValue: 1 예시: 1획득 또는 입력 방법: 1부터 페이지마다 1씩 증가시키고 응답의 페이지 번호로 확인합니다. |
|
| pageSize | integer | 페이지당 항목 수, 기본값 10. 1에서 100까지 입력할 수 있습니다. null 허용: False $minValue: 1 $maxValue: 100 예시: 10획득 또는 입력 방법: 클라이언트에 필요한 페이지 크기를 정수로 입력합니다. |
파라미터 추가 설명¶
현재 대상 사이트에 할당된 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/list"
query = {'search': '生产', 'pageIndex': 1, 'pageSize': 10}
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[].uuid | string | 워크스페이스 UUID입니다. 이후 인터페이스의 workspace_uuid 경로 또는 workspaceUUID 요청 필드에 넣습니다. |
| content.data[].name | string | 워크스페이스 표시 이름입니다. |
| content.data[].desc | string | 워크스페이스 설명입니다. |
| content.data[].status | integer | 워크스페이스 상태입니다. |
| content.data[].timezone | string | 워크스페이스 시간대입니다(예: Asia/Shanghai). |
| content.data[].language | string | 워크스페이스 언어 설정입니다. |
| content.pageInfo | object | 페이지 정보입니다. |
| content.pageInfo.pageIndex | integer | 현재 페이지 번호이며 1부터 시작합니다. |
| content.pageInfo.pageSize | integer | 페이지당 항목 수입니다. |
| content.pageInfo.count | integer | 현재 페이지에서 반환된 레코드 수입니다. |
| content.pageInfo.totalCount | integer | 조건을 만족하는 워크스페이스 총수이며, 전체 페이지 수를 계산하는 데 사용합니다. |
{
"code": 200,
"content": {
"data": [
{
"uuid": "wksp_example",
"name": "生产监控",
"desc": "生产服务观测",
"status": 0,
"timezone": "Asia/Shanghai",
"language": "zh"
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 10,
"count": 1,
"totalCount": 1
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하세요.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 쿼리 파라미터가 선언되지 않았거나 값이 파라미터 표의 제약을 벗어남 | 메시지에 필드 또는 규칙이 표시됩니다. | 파라미터 이름, 유형, 값 범위를 확인하세요. |