Hourly および Monthly Usage Attribution API への移行
サマリー
このガイドでは、使用量属性 API (v1) から v2 API への移行方法を説明します。v1 API は非推奨であり、月次 API (使用量属性を取得する) とファイルベース API (使用可能な日次カスタムレポートのリストを取得する、指定した日次カスタムレポートを取得する、使用可能な月次カスタムレポートのリストを取得する、指定した月次カスタムレポートを取得する) の 2 種類あります。このガイドを使用するには、現在使用している v1 API の以下のセクションを見つけ、対応する v2 API に移行するための指示に従います。
注: このドキュメントで v1 や v2 について言及する場合、URL パスのバージョンは参照されません。このドキュメントのすべての API は、それぞれのパスを持つ最初のバージョンであるため、URL パスには v1 を使用します。
月次 API
この API は、月次使用量属性を提供します。
v2 月次使用量属性 API 月次使用量属性を取得する も月次使用量属性を提供し、タグの組み合わせによるクエリをサポートしています。
v1 API と v2 API の違い、および v2 API への移行に関する推奨事項については、以下のセクションを参照してください。
ページ区切り
v1 API では、クエリパラメーター offset と limit を用いてページ送りを構成することができます。metadata.pagination.total_number_of_records の値は、全ページのレコード数の合計を提供します。
v2 API では、クエリパラメーター next_record_id でページ区切りの設定を行います。次のページの開始値は metadata.pagination.next_record_id で返されます。レスポンスに含まれるレコードの総数などはありません。
v2 API に移行するには、API ドキュメントページに記載されているように next_record_id を使ってページを進めてください。
タグの内訳
v1 API では、使用量データは同じレスポンスの中でタグごとに別々に分解されます。そのため、同じリソースが a、b、c などの複数のタグで別々にカウントされ、一見すると重複したデータになっていることがあります。
v2 API では、tag_breakdown_keys パラメーターにタグの構成を指定することで、タグの内訳を選択することができます。タグは 1 つずつ指定することも、複数のタグをカンマ区切りで指定することも可能です。複数のタグを指定すると、それらのタグの組み合わせでフィルタリングされた使用量が返されます。
v2 API に移行するには、tag_breakdown_keys パラメーターに使用するタグを指定します。v1 API と同じ内訳を取得するには、各タグに対して個別のリクエストを行います。
集計
v1 API では、aggregates セクションにすべての可能なレコードの合計が含まれ、データが 3 つの異なるタグに渡って 3 倍になるため、結果として実際の合計が 3 倍になります。例:
{
"field": "infra_host_usage",
"value": 293880,
"agg_type": "sum"
},
v2 API では、aggregates セクションには、使用したタグの組み合わせのレコードの合計のみが格納されます。例:
{
"field": "infra_host_usage",
"value": 97960,
"agg_type": "sum"
},
v2 API に移行する場合、これらの値は要求された月の組織の使用量の合計を表すので、集計を使用してください。
10 進数値
v1 API では、一部の使用量は 10 進数で返されます。例:
"cws_containers_usage": 1105642.92
v2 API では、使用量は整数値で返されます。例:
"cws_containers_usage": 1105643
整数値から 10 進数値への変換はできません。整数値は 10 進数を丸めた値となります。
製品ファミリー
v1 API では、サーバーレスモニタリングの使用量は以下の下にあります。
lambda_functions_usagelambda_functions_percentagelambda_invocations_usagelambda_invocations_percentage
v2 API では、サーバーレスモニタリングの使用量は以下の下にあります。
functions_usagefunctions_percentageinvocations_usageinvocations_percentage
これらの使用量タイプは機能的に同等で、唯一の違いは新しいフィールド名です。
ファイルベース API
この API セットは、日次および月次の使用量属性データの ZIP ファイルをダウンロードするためのリンクを提供します。
この API は、利用可能なダウンロードのリストを生成します。ファイルダウンロードは廃止されたため、この API に代わるものはありません。
この API は、指定された日の全製品の使用量属性データの zip ファイルをダウンロードするためのリンクを返します。zip ファイルには、各プロダクトのTSV (タブ区切り値) ファイルが含まれています。
時間単位使用量属性を取得する API では、これと同じデータが提供されます。
v1 API と v2 API の違い、および v2 API への移行に関する推奨事項については、以下のセクションを参照してください。
レスポンスフォーマット
v1 API では、レスポンスに製品ごとの TSV ファイルを含む ZIP ファイルへのリンクが含まれます。
v2 API では、レスポンスとして使用量属性データを JSON 形式で返します。
v2 API に移行するためには、プロセスで JSON 形式のデータを扱う必要があります。必要に応じて JSON データに変換を施し、ニーズに合った形式を作成することができます。
タグの内訳
v1 API では、使用量データは選択されたすべてのタグで分解されます。
v2 API では、tag_breakdown_keys にタグの構成をカンマ区切りで指定することで、タグの内訳を選択することができます。
v2 API に移行するには、tag_breakdown_keys クエリパラメーターに選択したすべてのタグを指定します。
タグキー
v1 API では、選択されたタグキーは TSV ファイルのヘッダーとして表示されます。例:
public_id formatted_timestamp env service total_usage
abc123 2022-01-01 00:00:00 prod web 100
...
v2 API では、選択されたタグは、レスポンスの使用量配列の各項目の tags オブジェクトのキーとなります。例:
...
"tags": {
"service": [
"web"
],
"env": [
"prod"
]
},
...
v2 API に移行する場合は、各レスポンス行の tags オブジェクトから取得します。
タグ値
v1 API では、リソースが同じタグを複数回持つ場合、タグの列にパイプ (|) で区切られた文字列として表示されます。
例:
public_id formatted_timestamp env service total_usage
abc123 2022-01-01 00:00:00 prod authentication|web 100
...
v2 API では、tags オブジェクトの各タグキーに対応する値は配列です。あるリソースに同じタグが複数回設定されている場合、このリストには複数のアイテムが存在することを示します。
例:
...
"tags": {
"service": [
"authentication",
"web"
],
"env": [
"prod"
]
},
...
v2 API に移行するためには、同じタグが複数回適用されたリソースをプロセスで処理する必要があります。
v2 レスポンスの配列に含まれるタグの値は、v1 レスポンスのパイプで区切られた文字列と同じ順番で現れるため、配列をパイプ文字で結合すれば v1 レスポンスと同じタグ値を生成することができます。
合計使用量
v1 API では、CSV ヘッダーの中で、使用量の合計を total_usage と呼びます。
v2 API では、使用量の合計は total_usage_sum と呼ばれ、使用量配列の各オブジェクトのキーとなります。
v2 API に移行する場合は、キー total_usage_sum を使用して使用量を抽出します。
総使用量データ型
v1 API は CSV を使用しており、データ型を指定する方法がありません (ただし、総使用量は常に数値です)。
v2 API では、総使用量は整数値です。
v2 API に移行するには、総使用量を整数値で扱います。
時間フォーマット
v1 API では、時刻は YYYY-MM-DD hh:mm:ss というフォーマットで表されます。
v2 API では、時刻は YYYY-MM-DDThh というフォーマットで表されます。
v1 フォーマットのデータは、分と秒の値が常に 0 になります (データは 1 時間単位です)。v2 フォーマットのデータはパースして、v1 フォーマットのパースされた時刻と同等に扱うことができます。
子オーガニゼーション
v1 API では、このファイルは親組織に設定されたタグ構成のデータのみを含みます。タグの構成は子組織にも適用されるため、このファイルには親組織の子組織がすべて含まれます。
v2 API では、もし include_descendants=true パラメーターが与えられると (これがデフォルトです)、レスポンスは親組織とそのすべての子組織のデータを含みます。これは、親組織から子組織へ継承されたタグ構成からのすべてのデータを含み、また、それらの子組織に直接設定されたすべてのタグ構成も含まれます。与えられたタグ構成の起源は tag_config_source フィールドから判別することができます。
v2 API に移行するには、include_descendants=true パラメーターを渡します。v1 のレスポンスと同じ値を取得するには、親組織からのタグ構成の tag_config_source と一致しないレスポンス内のレコードをフィルターで除外します。
データ範囲
v1 API では、データは一度に 1 日分ずつ返されます。日付はリクエストの record_id パラメーターで指定します。
v2 API では、start_hr と end_hr パラメーターを使用して、一度に 24 時間までの任意の時間枠でデータを取得することができます。
v2 API に移行するには、start_hrを希望日の午前 0 時 (00 時)、end_hr を翌日の午前 0 時としたデータをリクエストします。
ページ区切り
v1 API では、データはページは区切られません。そのため、ファイルサイズが非常に大きくなることがあります。
v2 API では、データはページ区切りされます。レスポンスが複数のページを占める場合、次のページを取得するための ID が metadata.pagination.next_record_id フィールドで提供されます。これをクエリパラメーター next_record_id で指定すると、次のページを取得することができます。
v2 API に移行するには、指定された日の全ページを取得します。
データカーディナリティ
v1 API では、データは 3 つのタグすべてで分解されます。
v2 API では、クエリパラメーター tag_breakdown_keys で指定されたとおりにデータが分解されます。
v2 API に移行するには、パラメーター tag_breakdown_keys に選択したすべてのタグを指定します。
使用量タイプ名
v1 API では、ファイル名は daily_<product>_<date>.tsv となります。
v2 API では、使用量タイプには常に _usage というサフィックスが付きます。
v2 API に移行するには、すべての使用量に _usage というサフィックスを付けます。
使用量名の変更
v1 API には、以下のファイルが含まれています。
apminfralambda_invocationslambda_functionsprofiled_containersnpmprofiled_hosts
v2 API では、対応する使用量タイプは以下の通りです。
apm_host_usageinfra_host_usageinvocations_usagefunctions_usageprofiled_container_usagenpm_host_usageprofiled_host_usage
v2 API に移行するには、指定された使用量タイプを更新後の名称にマッピングします。
時系列使用量タイプ
v1 API では、時系列ファイルは標準時系列とカスタム時系列の両方の使用量を含んでいます。
v2 API では、custom_timeseries_usage という使用量タイプが 1 つ存在します。
Datadog はカスタム時系列の使用量に対してのみ請求しますので、標準時系列の使用量は必要ありません。
Synthetics 使用量タイプ
v1 API では、Synthetics ファイルに API テストとブラウザテストの両方の使用量が含まれています。
v2 API では、api_usage と browser_usage という 2 種類の Synthetics の使用量タイプが用意されています。
v2 API に移行するには、Synthetic の使用量を取得するために新しい使用量タイプを使用します。
この API は、利用可能なダウンロードのリストを生成します。ファイルダウンロードは廃止されたため、この API に代わるものはありません。
この API は、指定された月の全製品の使用量属性データの ZIP ファイルをダウンロードするためのリンクを返します。ZIP ファイルには、各製品の TSV ファイルと、各タグのサマリーファイルが含まれています。この 2 種類のファイルを複製するためのアプローチを以下に説明します。
製品別時間単位データファイル
時間単位データファイルは、monthly_<product>_<date>.tsv という命名形式を使用しています。各製品ファイルは、指定した日次カスタムレポートを取得するから入手できる日次の zip ファイルを連結したものです。
時間単位使用量属性を取得する API では、これと同じデータが提供されます。
時間単位データファイルは、指定した日次カスタムレポートを取得するで利用できるファイルと非常によく似ているため、時間範囲に関する推奨事項を除き、同じガイドが適用されます。v1 の月次ファイルから移行するには、その月の各日の全ページをリクエストします。v2 API では、リクエストは一度に 24 時間に制限されています。
タグ別月次サマリーファイル
月次サマリーファイルは、summary_<tag>_<date>.tsv というファイル名形式を採用しています。これらのファイルは、各タグについて、その月のすべての使用量のロールアップを提供します。月次使用量属性を取得する API はこれと同じデータを提供します。
v1 API と v2 API の違い、および v2 API への移行に関する推奨事項については、以下のセクションを参照してください。
レスポンスフォーマット
v1 API のレスポンスには、選択された各タグの TSV ファイルを含む ZIP ファイルへのリンクが含まれます。
v2 API のレスポンスは、使用量属性データを JSON 形式で返します。
v2 API に移行するためには、プロセスで JSON 形式のデータを扱う必要があります。必要に応じて JSON データに変換を施し、ニーズに合った形式を作成することができます。
タグの内訳
v1 API では、選択されたタグごとに個別の TSV ファイルが存在します。
v2 API では、tag_breakdown_keys にタグの構成をカンマ区切りで指定することで、タグの内訳を選択することができます。
v2 API に移行するには、tag_breakdown_keys で各タグを個別に指定してリクエストします。
タグ値
v1 API では、リソースに同じタグを複数回付けられている場合、タグの列にパイプ (|) で区切られた文字列として表示されます。
例:
month public_id team infra_host_usage ....
2022-01 abc123 billing|sre 100
...
v2 API では、tags オブジェクトの各タグキーに対応する値は配列です。あるリソースに同じタグが複数回付けられている場合、このリストには複数のアイテムが存在します。
例:
...
"tags": {
"team": [
"billing",
"sre"
]
},
...
v2 API に移行するためには、同じタグが複数回適用されたリソースをプロセスで処理する必要があります。
v2 レスポンスの配列に含まれるタグの値は、v1 レスポンスのパイプで区切られた文字列と同じ順番で現れるため、配列をパイプ文字で結合すれば v1 レスポンスと同じタグ値を生成することができます。
合計使用量
v1 API では、ファイルの 2 行目に全タグの使用量を集計しています。
v2 API では、レスポンスの metadata.aggregates セクションに、すべてのタグの使用量が集計されます。
v2 API に移行するには、metadata.aggregates セクションから使用量の合計を取得します。
使用量データ型
v1 API では、一部の使用量は 10 進数で返されます。例:
v2 API では、使用量は整数値で返されます。例:
"container_usage": 55
整数値から 10 進数値への変換はできません。整数値は 10 進数を丸めた値となります。
子オーガニゼーション
v1 API では、このファイルは親組織に設定されたタグ構成のデータのみを含みます。タグの構成は子組織にも適用されるため、このファイルには親組織の子組織がすべて含まれます。
v2 API では、もし include_descendants=true パラメーターが与えられると (これがデフォルトです)、レスポンスは親組織とそのすべての子組織のデータを含みます。これは、親組織から子組織へ継承されたタグ構成からのすべてのデータを含み、また、それらの子組織に直接設定されたすべてのタグ構成も含まれます。与えられたタグ構成の起源は tag_config_source フィールドから判別することができます。
サーバーレスモニタリング使用量
v1 API では、サーバーレスモニタリングの使用量は以下の名前を使用します。
lambda_functions_usagelambda_functions_percentagelambda_invocations_usagelambda_invocations_percentage
v2 API では、サーバーレスモニタリングの使用量は以下の名前を使用します。
functions_usagefunctions_percentageinvocations_usageinvocations_percentage
v2 API に移行するには、更新されたフィールド名でサーバーレスモニタリングの使用量を探します。これらの使用量は、機能的に同等であり、唯一の違いは新しいフィールド名です。
その他の参考資料
