コンテンツにスキップ

オンライン 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 クエリパラメータが宣言されていない、または値がパラメータ表の制約を超えている メッセージにフィールドまたはルールが示されます。 パラメータ名、型、値の範囲を確認してください。

フィードバック

このページは役に立ちましたか?