スクリプト開発 / コネクターオブジェクト `DFF.CONN` / DataKit、DataWay

DataKit、DataWay のコネクター操作オブジェクトは、主にデータ書き込みメソッドを提供します。

DFF.CONN(...) のパラメータは次のとおりです：

DataKitDataWay

パラメータ	型	必須 / デフォルト値	説明
`connector_id`	str	必須	コネクター ID
`source`	str	`None`	コネクターの Source を上書き注意：`"mysql"` などのコレクター名を入力しないでください（混同を避けるため）
`timeout`	int/float	`10`	現在の操作オブジェクトのデフォルト HTTP リクエストタイムアウト時間（秒）
`split_size`	int	`100`	ラインプロトコル一括書き込み時の1リクエストあたりのデータポイント数

パラメータ	型	必須 / デフォルト値	説明
`connector_id`	str	必須	コネクター ID
`token`	str	`None`	コネクターの Token を上書き
`timeout`	int/float	`10`	現在の操作オブジェクトのデフォルト HTTP リクエストタイムアウト時間（秒）
`split_size`	int	`100`	ラインプロトコル一括書き込み時の1リクエストあたりのデータポイント数

一般的なデータ送信は、.write_by_category(...)、.write_by_category_many(...) メソッドを使用してください
一般的に DQL 文を実行するには、.query(...) メソッドを使用してください
GET リクエストを直接送信するには、.get(...) メソッドを使用してください
POST リクエストを直接送信するには、.post_json(...) メソッドを使用してください
ラインプロトコルデータを直接送信するには、.post_line_protocol(...) メソッドを使用してください

本コネクターは本質的に HTTP リクエストのラッパーです

DataKit と DataWay の間では、ほとんどのインターフェースが完全に同じです。

DataKit、DataWay のインターフェースは頻繁に変わるため、本コネクターはすべてのインターフェースを一対一でカプセル化しているわけではありません

異なるバージョンの DataKit、DataWay では、送信データに対する要件や制約が異なる場合があるため、関連ドキュメントを読んだ上で本コネクターを使用してください

詳細ドキュメントは次を参照してください：

TrueWatch ドキュメント / DataKit

`.write_by_category(...)`

DataKit、DataWay に特定タイプのデータを書き込むためのパラメータは次のとおりです：

パラメータ	型	必須 / デフォルト値	説明
`category`	str	必須	データ型。詳細は TrueWatch ドキュメント / DataKit API を参照
`measurement`	str	必須	メトリックセット名
`tags`	dict	`None`	タグ。キー名とキー値はどちらも文字列である必要があります
`fields`	dict	必須	メトリクス。キー名は文字列である必要があります。値は文字列、整数、浮動小数点数、ブール値、または要素型が一致する上記の型のリストを指定できます。
`timestamp`	int/long/float	{現在時間}	タイムスタンプ。秒/ミリ秒/マイクロ秒/ナノ秒をサポートします。
`headers`	dict	`None`	リクエストヘッダーパラメータ
`timeout`	int/float	`None`	今回のリクエストのタイムアウト時間。省略時は操作オブジェクトのデフォルト値を使用します。

パラメータ headers は 3.3.0 で追加されました。

例
tags   = { 'host': 'web-01' }
fields = { 'cpu' : 10 }
status_code, result = datakit.write_by_category(category='metric', measurement='ホスト監視', tags=tags, fields=fields)

`.write_by_category_many(...)`

write_by_category(...) のバッチ版。パラメータは次のとおりです：

パラメータ	型	必須 / デフォルト値	説明
`category`	str	必須	データ型。詳細は TrueWatch ドキュメント / DataKit API を参照
`data`	list	必須	データポイントリスト
`data[#].measurement`	str	必須	メトリックセット名
`data[#].tags`	dict	`None`	タグ。キー名とキー値はどちらも文字列である必要があります
`data[#].fields`	dict	必須	メトリクス。キー名は文字列である必要があります。値は文字列、整数、浮動小数点数、ブール値、または要素型が一致する上記の型のリストを指定できます。
`data[#].timestamp`	int/long/float	{現在時間}	タイムスタンプ。秒/ミリ秒/マイクロ秒/ナノ秒をサポートします。
`headers`	dict	`None`	リクエストヘッダーパラメータ
`timeout`	int/float	`None`	今回のリクエストのタイムアウト時間。省略時は操作オブジェクトのデフォルト値を使用します。

パラメータ headers は 3.3.0 で追加されました。

例
data = [
    {
        'measurement': 'ホスト監視',
        'tags'       : { 'host' : 'web-01' },
        'fields'     : { 'value': 10 }
    },
    {
        'measurement': 'ホスト監視',
        'tags'       : { 'host' : 'web-02' },
        'fields'     : { 'value': 20 }
    }
]
status_code, result = datakit.write_by_category_many(category='metric', data=data)

`.write_metric(...)` / `.write_point(...)`

.write_metric(...) は .write_by_category(category='metric', ...) と等価です。.write_point(...) は旧版互換のエイリアスです。

例
status_code, result = datakit.write_metric(measurement='ホスト監視', tags={'host': 'web-01'}, fields={'cpu': 10})

`.write_metric_many(...)` / `.write_metrics(...)` / `.write_points(...)`

.write_metric_many(...) は .write_by_category_many(category='metric', ...) と等価です。.write_metrics(...) と .write_points(...) は旧版互換のエイリアスです。

例
data = [
    {
        'measurement': 'ホスト監視',
        'tags'       : { 'host' : 'web-01' },
        'fields'     : { 'value': 10 }
    },
    {
        'measurement': 'ホスト監視',
        'tags'       : { 'host' : 'web-02' },
        'fields'     : { 'value': 20 }
    }
]
status_code, result = datakit.write_metrics(data=data)

`.write_logging(...)` / `.write_logging_many(...)`

.write_logging(...) は .write_by_category(category='logging', ...) と等価です。.write_logging_many(...) は対応するバッチ版です。

`.query(...)`

このメソッドは DataKit、DataWay API DQL クエリインターフェースのパラメータをサポートしています

詳細ドキュメントは TrueWatch ドキュメント / DataKit API ドキュメントを参照してください

このメソッドは HTTP リクエストのラッパーにすぎません

このメソッドは本質的に DataKit、DataWay に HTTP リクエストを送信するだけで、戻り値の内容は DataKit、DataWay およびバックエンドのデータソースに依存します。

戻り値の結果に疑問がある場合は、requests を直接使用して DataKit、DataWay にリクエストを送信してみてください：

requests を使用してインターフェースを呼び出す
def query():
    domain = '<Domain>'
    token  = '<Token>'

    url = f'https://{domain}/v1/query/raw?token={token}'
    body = {
        'queries': [
            {
                # DQL 文
                'query': 'M::`cpu`:(`load5s`) BY `host`',

                # 直近 1 時間
                'time_range': [
                    _DFF_TRIGGER_TIME_MS - 3600 * 1000,
                    _DFF_TRIGGER_TIME_MS,
                ],
            }
        ],
        'token': token
    }

    resp = requests.post(url, json=body)
    print(resp.status_code)
    print(resp.text)

DataKit、DataWay を介して DQL 文を実行する際のパラメータは次のとおりです：

パラメータ	型	必須 / デフォルト値	説明
`dql`	str	必須	DQL 文
`dict_output`	bool	`False`	データを自動的に `dict` に変換するかどうか。
`raw`	bool	`False`	元のレスポンスを返すかどうか。有効にすると `dict_output` パラメータは無効になります。
`all_series`	bool	`False`	`slimit` と `soffset` を使用して自動的にページングし、すべてのタイムラインを取得するかどうか。
`token`	str	`None`	DataKit でのみ使用されるワークスペース Token。DataWay では操作オブジェクトを取得する際に Token を設定してください
`timeout`	int/float	`None`	今回のリクエストのタイムアウト時間。省略時は操作オブジェクトのデフォルト値を使用します。
`{DataKit、DataWay ネイティブパラメータ}`	-	-	`queries[0].{DataKit、DataWay ネイティブパラメータ}` に透過的に渡されます

all_series を有効にすると、1 ページあたり固定で 500 件のタイムラインをクエリします。メトリクスクエリは最大 20 ページ、その他のクエリは最大 5 ページをリクエストします。

DataWay はクエリ実行前に Token を保持している必要があります。コネクター設定または DFF.CONN(..., token='...') で設定してください。.query(...) に token を重複して渡さないでください。

例
import time
import json

@DFF.API('Run DQL via DataKit')
def run_dql_via_datakit():
    datakit = DFF.CONN('datakit')

    # DataKit のネイティブパラメータ `time_range` を使用し、直近 1 時間のデータに制限します
    time_range = [
        int(time.time() - 3600) * 1000,
        int(time.time()) * 1000,
    ]

    # クエリを実行し、dict 形式でデータを返します
    status_code, result = datakit.query(dql='O::HOST:(host,load,create_time)', dict_output=True, time_range=time_range)
    print(json.dumps(result))

出力例
{
  "series": [
    [
      {
        "time": 1622463105293,
        "host": "iZbp152ke14timzud0du15Z",
        "load": 2.18,
        "create_time": 1622429576363,
        "tags": {}
      },
      {
        "time": 1622462905921,
        "host": "ubuntu18-base",
        "load": 0.08,
        "create_time": 1622268259114,
        "tags": {}
      },
      {
        "time": 1622461264175,
        "host": "shenrongMacBook.local",
        "load": 2.395508,
        "create_time": 1622427320834,
        "tags": {}
      }
    ]
  ]
}

例
import time
import json

@DFF.API('Run DQL via DataKit')
def run_dql_via_datakit():
    datakit = DFF.CONN('datakit')

    # raw パラメータを追加し、DQL クエリの元の値を取得します
    time_range = [
        int(time.time() - 3600) * 1000,
        int(time.time()) * 1000,
    ]

    # クエリを実行し、DataKit の元の戻り値形式でデータを返します
    status_code, result = datakit.query(dql='O::HOST:(host,load,create_time)', raw=True, time_range=time_range)
    print(json.dumps(result, indent=2))

出力例
{
  "content": [
    {
      "series": [
        {
          "name": "HOST",
          "columns": [
            "time",
            "host",
            "load",
            "create_time"
          ],
          "values": [
            [
              1622463165152,
              "iZbp152ke14timzud0du15Z",
              1.92,
              1622429576363
            ],
            [
              1622462905921,
              "ubuntu18-base",
              0.08,
              1622268259114
            ],
            [
              1622461264175,
              "shenrongMacBook.local",
              2.395508,
              1622427320834
            ]
          ]
        }
      ],
      "cost": "1ms",
      "total_hits": 3
    }
  ]
}

`.get(...)`

本メソッドは汎用的な処理方法です

具体的なパラメータ形式や内容などについては、TrueWatch ドキュメント / DataKit API を参照してください。

DataKit、DataWay に GET リクエストを送信します。パラメータは次のとおりです：

パラメータ	型	必須 / デフォルト値	説明
`path`	str	必須	リクエストパス
`query`	dict	`None`	リクエスト URL パラメータ
`headers`	dict	`None`	リクエストヘッダーパラメータ
`timeout`	int/float	`None`	今回のリクエストのタイムアウト時間。省略時は操作オブジェクトのデフォルト値を使用します。

(status_code, result) を返します。レスポンスボディが JSON として解析できる場合は result は対応するオブジェクト、それ以外の場合はテキストまたは元の内容です。

`.post_json(...)`

本メソッドは汎用的な処理方法です

具体的なパラメータ形式や内容などについては、TrueWatch ドキュメント / DataKit API を参照してください。

DataKit、DataWay に JSON 形式で POST リクエストを送信します。パラメータは次のとおりです：

パラメータ	型	必須 / デフォルト値	説明
`path`	str	必須	リクエストパス
`json_obj`	dict/list	必須	送信する JSON オブジェクト
`query`	dict	`None`	リクエスト URL パラメータ
`headers`	dict	`None`	リクエストヘッダーパラメータ
`timeout`	int/float	`None`	今回のリクエストのタイムアウト時間。省略時は操作オブジェクトのデフォルト値を使用します。

パラメータ path はバージョン 1.6.8 で最初のパラメータに変更されました

(status_code, result) を返します。

`.post_line_protocol(...)`

本メソッドは汎用的な処理方法です

具体的なパラメータ形式や内容などについては、TrueWatch ドキュメント / DataKit API を参照してください。

DataKit、DataWay にラインプロトコル形式で POST リクエストを送信します。パラメータは次のとおりです：

パラメータ	型	必須 / デフォルト値	説明
`path`	str	必須	リクエストパス
`points`	dict/list	必須	単一のデータポイントまたはデータポイントのリスト
`points[#].measurement`	str	必須	メジャーメント名
`points[#].tags`	dict	`None`	タグ。キー名と値はどちらも文字列である必要があります
`points[#].fields`	dict	必須	フィールド。キー名は文字列である必要があります。値には文字列、整数、浮動小数点数、ブール値、または要素の型が一致する上記の型のリストを使用できます
`points[#].timestamp`	int/long/float	{現在時刻}	タイムスタンプ。秒/ミリ秒/マイクロ秒/ナノ秒に対応
`query`	dict	`None`	リクエスト URL パラメータ
`headers`	dict	`None`	リクエストヘッダーパラメータ
`timeout`	int/float	`None`	今回のリクエストのタイムアウト時間。省略時は操作オブジェクトのデフォルト値を使用します。

パラメータ path はバージョン 1.6.8 で最初のパラメータに変更されました

バッチデータは split_size ごとに分割して送信されます。本メソッドは最後の分割リクエストの (status_code, result) を返します。いずれかの分割リクエストが失敗した場合は例外をスローし、後続の送信を停止します。

スクリプト開発 / コネクターオブジェクト DFF.CONN / DataKit、DataWay

.write_by_category(...)

.write_by_category_many(...)

.write_metric(...) / .write_point(...)

.write_metric_many(...) / .write_metrics(...) / .write_points(...)

.write_logging(...) / .write_logging_many(...)

.query(...)

.get(...)

.post_json(...)

.post_line_protocol(...)

スクリプト開発 / コネクターオブジェクト `DFF.CONN` / DataKit、DataWay

`.write_by_category(...)`

`.write_by_category_many(...)`

`.write_metric(...)` / `.write_point(...)`

`.write_metric_many(...)` / `.write_metrics(...)` / `.write_points(...)`

`.write_logging(...)` / `.write_logging_many(...)`

`.query(...)`

`.get(...)`

`.post_json(...)`

`.post_line_protocol(...)`