온라인 DataKit 목록¶
GET /api/v1/datakit/list
개요¶
현재 사이트에서 확인 가능한 DataKit 보고 기록을 나열하며, 워크스페이스, 버전 및 활성 상태로 필터링할 수 있습니다.
호출 전 및 사용 단계¶
특정 워크스페이스의 DataKit을 확인해야 하는 경우 먼저 workspaceUUID를 가져온 후 페이지별로 조회하십시오. 온라인 필터링은 당일 보고 여부 및 사이트 활성 기간 임계값을 기준으로 합니다. 최근 일정 기간 동안 하트비트가 있었던 인스턴스를 필터링하려면 lastHeartbeatTime을 사용하십시오. 마지막 페이지를 초과하면 data가 비어 있고 totalCount가 0으로 반환될 수 있으므로, 클라이언트는 빈 페이지에서 종료할 수 있습니다.
예제에서는 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>가져오기 또는 입력 방법: 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 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| workspaceUUID | string | 대상 워크스페이스 UUID. null 허용: False 예: wksp_example가져오기 또는 입력 방법: 워크스페이스 목록 응답의 content.data[].uuid에서 가져와 원래 값을 사용합니다. |
|
| version | string | 원본 버전 문자열로 정확히 일치시킵니다. null 허용: False 예: 1.70.0가져오기 또는 입력 방법: DataKit 설치 정보 또는 과거 목록의 content.data[].version에서 전체 버전 번호를 가져옵니다. |
|
| search | string | 대소문자를 구분하지 않는 퍼지 매칭을 사용합니다. null 허용: False 예: web-01가져오기 또는 입력 방법: DataKit 보고에 이미 있는 호스트 이름, 런타임 ID, IP 또는 선택한 필드의 일부 값을 입력합니다. |
|
| searchKeys | string | search가 적용될 때의 일치 필드입니다. 기본값은 hostName, extend.ip, extend.runtime_id입니다. null 허용: False 예: hostName,extend.ip,extend.runtime_id가져오기 또는 입력 방법: 필요에 따라 hostName, os, arch, version 또는 extend 아래 필드에서 선택하여 쉼표로 연결합니다. |
|
| isOnline | boolean | 생략하면 당일 활성 조건으로 필터링하지 않습니다. null 허용: False 예: true가져오기 또는 입력 방법: 당일 활성 기록을 조회하려면 true를, 임계값에 도달하지 않았거나 당일 보고되지 않은 기록을 조회하려면 false를 전달할 수 있습니다. |
|
| lastHeartbeatTime | integer | 최근 몇 초 이내에 보고가 있었는지, 최소 1입니다. 서버 현재 시각을 기준으로 역산합니다. null 허용: False $minValue: 1 예: 600가져오기 또는 입력 방법: 하트비트 관찰 기간을 초로 환산합니다. 예를 들어 최근 10분을 조회하려면 600을 전달합니다. |
|
| pageIndex | integer | 페이지 번호, 기본값 1. null 허용: False $minValue: 1 예: 1가져오기 또는 입력 방법: 1부터 시작하여 페이지별로 증가시키고 응답의 페이지 번호로 확인합니다. |
|
| pageSize | integer | 페이지당 항목 수, 기본값 50. 양의 정수를 전달하십시오. null 허용: False $minValue: 1 예: 50가져오기 또는 입력 방법: 클라이언트에 필요한 페이지 크기에 맞는 정수를 입력하십시오. |
파라미터 추가 설명¶
현재 대상 사이트에 할당된 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/datakit/list"
query = {'workspaceUUID': 'wksp_example', 'search': 'web-01', 'lastHeartbeatTime': 600}
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 | DataKit 보고 기록 ID. |
| content.data[].workspaceUUID | string | 소속 워크스페이스 UUID. |
| content.data[].workspaceName | string 또는 null | 소속 워크스페이스 이름, 일치하지 않으면 null입니다. |
| content.data[].hostName | string | 보고된 호스트 이름. |
| content.data[].os | string | 운영 체제. |
| content.data[].arch | string | 아키텍처. |
| content.data[].version | string | DataKit 버전 번호. |
| content.data[].lastUpdateTime | integer | 마지막 보고 시간, Unix 초. |
| content.data[].onlineTime | integer | 기록된 활성 기간, 당일 활성 여부 판단에 사용됩니다. |
| content.data[].usageCores | integer | 보고된 코어 수. |
| content.data[].extend | object 또는 null | 수집 시 보고된 확장 속성이며, 실제 배포에 따라 IP, runtime_id 등을 포함할 수 있습니다. |
| content.data[].status | integer | 기록 상태. 이 API는 삭제되지 않은 표시 가능한 기록만 반환합니다. |
| content.pageInfo | object | 페이지 정보. |
| content.pageInfo.pageIndex | integer | 현재 페이지 번호, 1부터 시작합니다. |
| content.pageInfo.pageSize | integer | 페이지당 항목 수. |
| content.pageInfo.count | integer | 현재 페이지에서 반환된 기록 수. |
| content.pageInfo.totalCount | integer | 조건을 충족하는 기록의 총수. 일부 API에서는 빈 페이지가 0을 반환할 수 있습니다. 호출 설명을 참조하십시오. |
{
"code": 200,
"content": {
"data": [
{
"id": 1,
"workspaceUUID": "wksp_example",
"workspaceName": "生产监控",
"hostName": "web-01",
"os": "linux",
"arch": "amd64",
"version": "1.70.0",
"lastUpdateTime": 1785456000,
"onlineTime": 900,
"usageCores": 4,
"extend": {
"ip": "192.0.2.10"
},
"status": 0
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 50,
"count": 1,
"totalCount": 1
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 조회 파라미터가 선언되지 않았거나 숫자 값이 파라미터 표의 제약 조건을 벗어남 | 메시지에서 필드 또는 규칙을 지적합니다. | 파라미터 이름, 유형 및 값 범위를 확인하십시오. |