オンライン 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 | 1 ページあたりの件数。デフォルトは 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 | レコードのステータス。本インターフェースは未削除の可視レコードのみを返します。 |
| content.pageInfo | object | ページネーション情報。 |
| content.pageInfo.pageIndex | integer | 現在のページ番号。1 から始まります。 |
| content.pageInfo.pageSize | integer | 1 ページあたりの件数。 |
| content.pageInfo.count | integer | 現在のページで返されたレコード数。 |
| content.pageInfo.totalCount | integer | 条件を満たすレコードの総数。一部のインターフェースでは空ページで 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 | クエリパラメータが宣言されていない、または値がパラメータ表の制約を超えている | メッセージにフィールドまたはルールが示されます。 | パラメータ名、型、値の範囲を確認してください。 |