腳本開發 / 連接器對象 `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`	行協議批量寫入時每次請求的數據點數量

參數	類型	必須 / 默認值	説明
`connector_id`	str	必須	連接器 ID
`token`	str	`None`	覆蓋連接器 Token
`timeout`	int/float	`10`	當前操作對象的默認 HTTP 請求超時時間，秒
`split_size`	int	`100`	行協議批量寫入時每次請求的數據點數量

一般性上報數據，請使用 .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`	請求 Header 參數
`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`	請求 Header 參數
`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 時，每頁固定查詢 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`	請求 Header 參數
`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`	請求 Header 參數
`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`	請求 Header 參數
`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(...)`