複数値データポイントの書き込み - - Alibaba Cloud ドキュメントセンター

このトピックでは、複数値データポイントの書き込みモードとレスポンスについて説明します。

時系列データの複数値データモデル

複数値データモデルは、データソースに基づいて作成されます。各データエントリは、特定の時点の特定のデータソースに対して作成され、複数のメトリックフィールドの値が含まれます。たとえば、データエントリには、サーバーの cpu、mem、および load などのメトリックフィールドの値を含めることができます。これにより、これらのフィールドを同時に管理できます。

複数値データモデルを使用してデータを書き込む

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

リクエストパス	リクエストメソッド	説明
/api/mput	POST	複数のデータポイントを一度に書き込みます。

重要

単一値データポイントと複数値データポイントを書き込むには、異なる API オペレーションを呼び出す必要があります。単一値データポイントを書き込むには、/api/put オペレーションを呼び出します。複数値データポイントをクエリするには、/api/mquery オペレーションを呼び出します。単一値データポイントを書き込むには、/api/query オペレーションを呼び出します。

リクエストパラメーター

パラメーター	タイプ	必須	説明	デフォルト	例
summary	型指定なし	いいえ	サマリーを返すかどうかを指定します。	false	/api/mput?summary
details	型指定なし	いいえ	詳細を返すかどうかを指定します。	false	/api/mput?details
sync_timeout	整数	いいえ	タイムアウト期間。単位：ミリ秒。値 0 は、リクエストがタイムアウトできないことを指定します。	0	/api/mput/?sync&sync_timeout=60000
ignoreErrors	型指定なし	いいえ	書き込みエラーを無視して他のデータポイントの書き込みを続行するかどうかを指定します。	false	/api/mput/?ignoreErrors

説明

型指定なしパラメーターが指定されている場合、システムはその値を true と判断します。たとえば、summary パラメーターを true または false に設定したかどうかに関係なく、システムは summary パラメーターの値を true と判断します。
同じクエリに details パラメーターと summary パラメーターを含めると、API オペレーションは details パラメーターの値を返します。

リクエストコンテンツ

データポイントを JSON 形式で指定します。次の表に、データポイントのパラメーターを示します。

パラメーター	タイプ	必須	制限	説明	例
metric	文字列	はい	値には、英字、数字、および次の特殊文字のみを含めることができます：`-_./():,[]=‘#`	格納するメトリックの名前。	sys.cpu 説明高可用性エディションでは、メトリック名は最大 255 バイトの長さにすることができます。
timestamp	Long	はい	該当なし	秒またはミリ秒単位のタイムスタンプ。単位を決定するためのルールについては、このトピックの「タイムスタンプ単位」セクションを参照してください。	1499158925
fields	マップ	はい	フィールド名の制限は、メトリック名と同じです。フィールド値のデータ型は、STRING、NUMBER、または BOOLEAN である必要があります。	フィールドの値。	“fields” : {“speed” : 20.8, “level” : 4, “direction” : “East”, “description” : “Fresh breeze”}
tags	マップ	はい	値には、英字、数字、および次の特殊文字を含めることができます：`-_./():,[]=‘#`	タグのキーと値のペア。タグキーとタグ値は文字列です。少なくとも 1 つのタグキーと値のペアを指定します。	{"host":"web01"}。STRING データ型ではないタグキーとタグ値は、明示的に STRING 型に変換されます。

タイムスタンプ単位

このセクションでは、タイムスタンプの単位を決定するためのルールについて説明します。これらのルールは、次の API オペレーションに適用されます：/api/put、/api/mput、/api/query、および /api/mquery。/api/put および /api/mput はデータの書き込みに使用されます。/api/query および /api/mquery はデータのクエリに使用されます。タイムスタンプは、秒またはミリ秒単位で測定できます。Time Series Database（TSDB）は、数値に基づいてタイムスタンプの単位を決定するために、次のルールを使用します。

値が [4294968,4294967295] の範囲内にある場合、TSDB はタイムスタンプが秒単位で測定されていると判断します。この場合、対応する日時範囲は [1970-02-20 01:02:48, 2106-02-07 14:28:15] です。
値が [4294967296,9999999999999] の範囲内にある場合、単位はミリ秒です。この場合、日時範囲は [1970-02-20 01:02:47.296, 2286-11-21 01:46:39.999] です。
値が (-∞,4294968) または (9999999999999,+∞) の範囲内にある場合、タイムスタンプは無効です。

複数値データポイントの値の説明

STRING データ型の値にはすべての文字を含めることができ、JSON 形式で格納できます。文字列値のサイズは 20 KB を超えることはできません。

次のコードは、複数値データポイントを書き込む方法を示す例です。

リクエスト行：POST/api/mput。リクエスト本文：

[
{
"metric":"wind",
"fields":{
"speed":20.8,
"level":4,
"direction":"East",
"description":"Fresh breeze" // 新鮮な風
},
"tags":{
"sensor":"IOTE_8859_0001",
"city":"hangzhou",
"province":"zhejiang",
"country":"china"
},
"timestamp":1346846400
},
{
"metric":"wind",
"fields":{
"speed":40.2,
"level":6,
"direction":"South",
"description":"Fresh breeze" // 新鮮な風
},
"tags":{
"sensor":"IOTE_8859_0002",
"city":"hangzhou",
"province":"zhejiang",
"country":"china"
},
"timestamp":1346846401
}
]

書き込みモードとレスポンス

TSDB は 4 つの書き込みモードをサポートしています。各モードを使用するには、次の手順に基づいてリクエストパラメーターを設定します。

シンプルモード
api/mput オペレーションを呼び出すときにパラメーターを設定しない場合、このモードが使用されます。データが TSDB に正常に書き込まれた場合は、ステータスコード 204 が返されます。データの書き込みに失敗した場合、対応するエラーコードとエラーメッセージのみが返されます。
このモードは、一般的なビジネスの監視データのレポートに適しています。
統計モード
api/mput オペレーションを呼び出すときに summary パラメーターを設定すると、このモードが使用されます。データが TSDB に正常に書き込まれたかどうかに関係なく、success パラメーターと failed パラメーターが返されます。これは、ビジネスの統計情報を収集するのに役立ちます。success パラメーターは、書き込まれたデータポイントの数を示します。failed パラメーターは、書き込みに失敗したデータポイントの数を示します。
パラメーター
タイプ
説明
success
整数
正常に書き込まれたデータポイントの数。
failed
整数
書き込みに失敗したデータポイントの数。
サンプルポリシー：
```
{
    "failed":0,
    "success": 20
}
```
重要
- 統計モードでは、api/mput リクエストのデータポイントはすべて正常に書き込まれるか、すべて書き込みに失敗します。データ書き込みに失敗した場合、failed パラメーターはリクエストで指定されたデータポイントの数を示します。
- 複数値データポイントを書き込む場合、success パラメーターまたは failed パラメーターの値は、単一値データモデルに基づいて計算されます。これは、単一の複数値データポイントが複数回カウントされることを示します。複数値データポイントがカウントされる回数は、複数値データポイントのフィールドの数と同じです。
統計モードは、レポートされたデータの統計情報を必要とする一般的なビジネスの監視データのレポートに適しています。

詳細モード

詳細モードは、統計モードの拡張です。api/mput オペレーションを呼び出すときに details パラメーターを設定すると、このモードが使用されます。データが TSDB に正常に書き込まれたかどうかに関係なく、success、failed、および errors パラメーターが返されます。success パラメーターは、書き込まれたデータポイントの数を示します。failed パラメーターは、書き込みに失敗したデータポイントの数を示します。errors パラメーターは、書き込み失敗の直接の原因を示します。

パラメーター	タイプ	説明
success	整数	正常に書き込まれたデータポイントの数。
failed	整数	書き込みに失敗したデータポイントの数。
errors	配列	書き込みに失敗した最初のデータポイントの失敗の直接の原因。値は、データポイントに関する情報と失敗原因で構成される配列です。

重要

統計モードでは、api/mput リクエストのデータポイントはすべて正常に書き込まれるか、すべて書き込みに失敗します。errors の値には、書き込みに失敗した最初のデータポイントに関する情報と失敗の直接の原因のみが含まれます。書き込みに失敗したデータポイントの数を確認するには、failed パラメーターの値を確認します。

このモードは、レポートされたデータの統計情報と障害箇所の特定を必要とするビジネスの監視データのレポートに適しています。

フォールトトレラントモード

api/mput オペレーションを呼び出すときに ignoreErrors パラメーターを設定すると、このモードが使用されます。フォールトトレラントモードで TSDB にデータポイントのバッチを書き込むリクエストを送信すると、1 つのデータポイントの書き込み失敗は他のデータポイントの書き込みに影響を与えません。このモードでは、有効なデータポイントと無効なデータポイントが同じバッチに存在する場合でも、ほとんどのデータポイントを TSDB に書き込むことができます。書き込みに失敗したデータポイントは、レスポンスで列挙されます。レスポンスには、リクエストで details パラメーターを設定した場合に返されるのと同じパラメーターが含まれます。ただし、errors パラメーターには、書き込みに失敗した各データポイントの名前と失敗原因が含まれます。errors パラメーターの値に含まれていないデータポイントは、TSDB に正常に書き込まれました。

パラメーター	タイプ	説明
success	整数	正常に書き込まれたデータポイントの数。
failed	整数	書き込みに失敗したデータポイントの数。
errors	配列	書き込みに失敗した各データポイントと対応する失敗原因の配列。

重要

フォールトトレラントモードでは、バッチ内のすべてのデータポイントが書き込みに失敗したわけではない場合、ステータスコード 200 が返されます。基盤となるストレージの障害などの重大なエラーにより、バッチ内のすべてのデータポイントが書き込みに失敗した場合、200 以外のステータスコードが返されます。フォールトトレラントモードでは、failed パラメーターは書き込みに失敗したデータポイントの数を示します。

このモードは、レポートされたデータの整合性を確保し、障害を解決し、書き込みに失敗したデータポイントの再書き込みを実行する必要があるビジネスシナリオの監視データのレポートに適しています。