時系列の最新のデータポイントを照会する - - Alibaba Cloud ドキュメントセンター

リクエストパスとメソッド

リクエストパス	リクエストメソッド	説明
/api/query/last	POST	時系列の最新のデータポイントを照会します。

重要

この操作は OpenTSDB と完全に互換性があります。

リクエストパラメーター

JSON 形式のリクエストのパラメーター

パラメーター	タイプ	必須	説明	デフォルト値	例
queries	配列	はい	サブクエリの配列。	なし	詳細については、「JSON 形式のサブクエリのパラメーター」セクションをご参照ください。
timestamp	Long	いいえ	UNIX タイムスタンプ。単位：秒またはミリ秒。タイムスタンプを指定すると、指定したタイムスタンプの最新のデータポイントを照会できます。このパラメーターを空のままにすると、現在のタイムスタンプの最新のデータポイントを照会できます。	なし	1539763573
hint	マップ	いいえ	クエリヒント。	なし	詳細については、「パラメーター：hint」セクションをご参照ください。
limit	マップ	いいえ	照会する最新のデータポイントの制限。	なし	詳細については、「パラメーター：limit」セクションをご参照ください。

JSON 形式のサブクエリのパラメーター

メトリックまたは TSUID に基づいてサブクエリを実行できます。メトリックに基づいてデータを照会する場合は、metric パラメーターと tags パラメーターを使用してクエリ条件を指定します。 TSUID に基づいてデータを照会する場合は、tsuid パラメーターを使用してクエリ条件を指定します。 tsuid パラメーターは、時系列の一意の ID を指定します。メトリッククエリと TSUID クエリをサブクエリのリストに含めることができます。

メトリッククエリ

パラメーター	タイプ	必須	説明	デフォルト値	例
metric	文字列	はい	照会する最新のデータポイントのメトリック。	なし	cpu.usage
tags	文字列	いいえ	照会する最新のデータポイントのタグ。	なし	host_name=host1
hint	マップ	マップ	クエリヒント。	なし	詳細については、「パラメーター：hint」セクションをご参照ください。

重要

クエリ条件を指定するには、tags パラメーターのみを使用できます。 filters パラメーターはサポートされていません。

TSUID クエリ

パラメーター	タイプ	必須	説明	デフォルト値	例
tsuid	文字列	はい	最新のデータポイントを照会する時系列の TSUID。	なし	00005B00005C0000F000005D0000EE00005E0000EF

重要

/api/search/lookup 操作を実行して、時系列の TSUID を照会できます。
TSDB 高可用性版の場合、リクエストで tsuid パラメーターを指定できます。ただし、このパラメーターの構成は有効になりません。高可用性版で /api/search/lookup を使用する場合、TSDB は時系列の TSUID を返しません。

JSON 形式のサンプルリクエスト

目的：

各時系列の最新のデータポイントを照会します。最初のサブクエリでは、metric パラメーターは cpu.usage に設定され、tags パラメーターは host_name: host1 に設定されています。

2 番目のサブクエリでは、tsuids は 00005B00005C00002E00005D0000EE00005E0000EF と 00005B00005C0000F000005D0000EE00005E0000EF に設定され、各時系列の最新のデータポイントが照会されます。

リクエスト行： POST/api/query/last

リクエスト本文：

{
    "queries" : [
        {
            "metric":"cpu.usage",
            "tags" : {
                "host_name": "host1"  // host_name を host1 に設定します。
            }
        },
        {
            "tsuids": [
                "00005B00005C00002E00005D0000EE00005E0000EF",
                "00005B00005C0000F000005D0000EE00005E0000EF"
            ]
        }
    ]
}

レスポンスの説明

HTTP ステータスコード 200 が返された場合、クエリは成功です。結果は、指定されたクエリ条件を満たす時系列の最新のデータポイントが返されたことを示します。結果は JSON 形式です。クエリ条件を満たす時系列がない場合は、空のセットが返されます。次の表に、レスポンスパラメーターを示します。

パラメーター	説明
metric	メトリック名。
timestamp	最新のデータポイントのタイムスタンプ。
value	メトリックの値。
tags	データポイントのタグペア。タグは、タグキーとタグ値で構成されます。
tsuid	データポイントが存在する時系列の ID。

サンプルリクエスト：

[{
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 30.3,
    "tags": {
        "host_name": "host1"
    },
    "tsuid": "00005B00005C00001D",
}, {
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 25.6,
    "tags": {
        "host_name": "host2",
        "cluster": "cluster1", // cluster を cluster1 に設定します。
        "zone": "zone1" // zone を zone1 に設定します。
    },
    "tsuid": "00005B00005C00002E00005D0000EE00005E0000EFE",
}, {
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 43.1,
    "tags": {
        "host_name": "host3",
        "cluster": "cluster1", // cluster を cluster1 に設定します。
        "zone": "zone1" // zone を zone1 に設定します。
    },
    "tsuid": "00005B00005C0000F000005D0000EE00005E0000EF",
}]

パラメーター：hint

シナリオ

ほとんどの場合、クエリヒントはクエリの応答時間を短縮するために使用されます。たとえば、タグ A とタグ B が指定されており、タグ B にヒットする時系列が明らかにタグ A にヒットする時系列に含まれているとします。この場合、タグ A にヒットする時系列からはデータは読み取られません。タグ A にヒットする時系列のセットとタグ B にヒットする時系列のセットの共通部分は、タグ B にヒットする時系列のセットと等しくなります。

形式の説明

現在の TSDB バージョンでは、ヒントで tagk パラメーターのみを使用してクエリインデックスを制限できます。
tagk パラメーターで指定されたタグキーと値のペアでは、タグキーのタグ値は同じでなければなりません。有効な値：0 と 1。タグ値が 0 の場合、タグキーに対応するインデックスは使用されません。タグ値が 1 の場合、タグキーに対応するインデックスが使用されます。

リリースノート

クエリヒント機能は TSDB V2.6.1 以降でサポートされています。

サンプルリクエスト

サブクエリに適用されるヒント

{
  "queries": [
    {
      "metric": "sys.cpu.nice", // metric を sys.cpu.nice に設定します。
      "tags": {
        "host": "web01" // host を web01 に設定します。
      },
      "hint": {
        "tagk": {
          "dc": 1 // dc を 1 に設定します。
        }
      }
    }
  ]
}

クエリ全体に適用されるヒント

{
  "queries": [
    {
      "metric": "sys.cpu.nice", // metric を sys.cpu.nice に設定します。
      "tags": {
        "host": "web01" // host を web01 に設定します。
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 1 // dc を 1 に設定します。
    }
  }
}

例外

tagk パラメーターで指定されたキーと値のペアのタグ値に 0 と 1 の両方が含まれている場合、エラーが返されます。

{
  "start": 1346846400,
  "end": 1346846400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice", // metric を sys.cpu.nice に設定します。
      "tags": {
        "dc": "lga", // dc を lga に設定します。
        "host": "web01" // host を web01 に設定します。
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 1, // dc を 1 に設定します。
      "host": 0 // host を 0 に設定します。
    }
  }
}

次のエラーメッセージが返されます。

{
    "error": {
        "code": 400,
        "message": "ヒントの値は 0 または 1 のみで、0 と 1 の両方があってはなりません", // ヒントの値は 0 または 1 のみで、0 と 1 の両方があってはなりません
        "details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
    }
}

tagk パラメーターで指定されたキーと値のペアのタグ値が 0 または 1 でない場合、エラーが返されます。

{
  "start": 1346846400,
  "end": 1346846400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice", // metric を sys.cpu.nice に設定します。
      "tags": {
        "dc": "lga", // dc を lga に設定します。
        "host": "web01" // host を web01 に設定します。
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 100 // dc を 100 に設定します。
    }
  }
}

次のエラーメッセージが返されます。

{
    "error": {
        "code": 400,
        "message": "ヒントの値は 0 または 1 のみで、「100」が渡されたことが検出されました", // ヒントの値は 0 または 1 のみで、「100」が渡されたことが検出されました
        "details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
    }
}

パラメーター：limit

制限： limit パラメーターを指定して、複数の最新のデータポイントを照会できます。リクエストで limit パラメーターを指定しない場合、各時系列は最新のデータポイントを 1 つだけ返します。

JSON 形式のリクエストのパラメーター

パラメーター	タイプ	必須	説明	デフォルト値	例
size	整数	はい	各時系列の最新のデータポイントの最大数。	なし	5
from	Long	はい	データが照会される時間範囲の開始。	なし	1346846400

例

4 つの時系列を書き込みます。各時系列には 2 つのデータポイントがあります。

[{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv1"},"timestamp":1514736040, "value":1}, // testmetric1_tagk を testmetric1_tagv1 に設定します。
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv1"},"timestamp":1514736050, "value":2}, // testmetric2_tagk を testmetric2_tagv1 に設定します。
{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv1"},"timestamp":1514736060, "value":3}, // testmetric1_tagk を testmetric1_tagv1 に設定します。
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv1"},"timestamp":1514736070, "value":4}, // testmetric2_tagk を testmetric2_tagv1 に設定します。
{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv2"},"timestamp":1514736080, "value":5}, // testmetric1_tagk を testmetric1_tagv2 に設定します。
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv2"},"timestamp":1514736090, "value":6}, // testmetric2_tagk を testmetric2_tagv2 に設定します。
{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv2"},"timestamp":1514736100, "value":7}, // testmetric1_tagk を testmetric1_tagv2 に設定します。
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv2"},"timestamp":1514736110, "value":8}] // testmetric2_tagk を testmetric2_tagv2 に設定します。

size パラメーターは 2 に設定されています。1514736040 から 1514736100 のタイムスタンプ範囲では、7 つのデータポイントが使用可能です。

{
    "timestamp": 1514736100,
    "limit": {
        "size": 2, // size を 2 に設定します。
        "from": 1514736040
    },
    "queries": [
        {
            "metric": "testmetric" // metric を testmetric に設定します。
        }
    ]
}

次のコードは、クエリ結果を示しています。時間範囲では、各時系列のデータポイントは最大 2 つです。

[
    {
        "metric": "testmetric",
        "timestamp": 1514736060000,
        "value": 3.0,
        "tags": {
            "testmetric1_tagk": "testmetric1_tagv1"
        },
        "tsuid": "0200000200000200****",
        "version": 0,
        "dps": {
            "1514736040000": 1.0,
            "1514736060000": 3.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736100000,
        "value": 7.0,
        "tags": {
            "testmetric1_tagk": "testmetric1_tagv2"
        },
        "tsuid": "0400000200000200****",
        "version": 0,
        "dps": {
            "1514736080000": 5.0,
            "1514736100000": 7.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736070000,
        "value": 4.0,
        "tags": {
            "testmetric2_tagk": "testmetric2_tagv1"
        },
        "tsuid": "0E00000200000300****",
        "version": 0,
        "dps": {
            "1514736050000": 2.0,
            "1514736070000": 4.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736090000,
        "value": 6.0,
        "tags": {
            "testmetric2_tagk": "testmetric2_tagv2"
        },
        "tsuid": "1000000200000300****",
        "version": 0,
        "dps": {
            "1514736090000": 6.0
        }
    }
]