App Optimize API で費用と使用率のデータを取得するには、まずレポートを作成します。このリソースは、分析するデータの永続的な定義として機能し、スコープ、ディメンション、期間、フィルタなどのパラメータを指定します。
レポートを作成すると、API はリクエストされたデータを非同期で生成します。次に、レポートのリソース名を使用して、結果のデータセットを取得します。
したがって、ワークフローは次のようになります。
- 条件を指定してレポートを作成します。
- システムはこのリクエストを非同期で処理します。
- オペレーションが完了したら、結果のデータを読み取ります。
このドキュメントでは、利用可能なディメンション、指標、フィルタリング オプションなど、App Optimize API レポートの構造と構成可能なパラメータについて詳しく説明し、返されるデータの形式について説明します。
費用と使用率の制限については、データを理解するをご覧ください。
レポートを定義する
レポートを作成するには、次の構成パラメータを使用して Report リソースを定義します。これらのパラメータについては、次のサブセクションで説明します。
| パラメータ | 型 | 説明 |
|---|---|---|
scopes |
配列 | 分析するプロジェクトまたは App Hub アプリケーション。スコープ要素は 1 つだけ指定する必要があります。 |
dimensions |
配列 | 取得してデータをグループ化する属性（時間ベースのグループ化を含む）。 |
metrics |
配列 | 返す特定の測定値。 |
filter |
文字列 | 時間範囲など、データを絞り込むための Common Expression Language（CEL）式。 |
スコープ
scopes フィールドは、App Optimize API が分析するリソースのセットを定義します。このフィールドは配列ですが、プロジェクトまたは App Hub アプリケーションのいずれか 1 つの要素を指定する必要があります。
project: Google Cloud プロジェクトを表す文字列。形式は次のとおりです。projects/PROJECT_IDPROJECT_IDは、 Google Cloud プロジェクトの ID に置き換えます。例:projects/my-project-1application: App Hub アプリケーションの完全なリソース名を表す文字列。次の形式にする必要があります。projects/PROJECT_ID/locations/LOCATION/applications/APPLICATION_ID次のように置き換えます。
PROJECT_ID: App Hub ホスト プロジェクトの ID。LOCATION: App Hub アプリケーションのリージョン（us-central1など）。APPLICATION_ID: App Hub アプリケーションの ID。
例:
projects/my-host-proj/locations/us-central1/applications/my-app
レポート作成リクエストの JSON 形式の scopes 配列の例を次に示します。単一のスコープ要素を示しています。
プロジェクト別のスコープ設定:
"scopes": [ { "project": "projects/my-project-1" } ]アプリケーションによるスコープ設定:
"scopes": [ { "application": "projects/my-host-proj/locations/us-central1/applications/my-app" } ]
ディメンション
ディメンションは、返されるデータとそのグループ化方法を決定します。たとえば、project と product_display_name を選択すると、出力には、データで見つかったプロジェクト名と商品名の値の組み合わせごとに 1 行が含まれます。
サポートされているディメンションの表は次のとおりです。
| ディメンション | タイプ | 説明 | 値の例 |
|---|---|---|---|
project |
STRING | Google Cloud プロジェクト ID | projects/my-project |
application |
STRING | App Hub アプリケーション。 | projects/my-project/locations/us-central1/applications/my-app |
service_or_workload |
STRING | App Hub サービスまたはワークロード。 | projects/my-project/locations/us-central1/applications/my-app/services/my-service |
resource |
STRING | 完全なリソース名。 | //compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/vm-1 |
resource_type |
STRING | API リソースタイプ。 | compute.googleapis.com/Instance |
location |
STRING | Google Cloud リージョンまたはマルチリージョン。 | us-east1 |
sku |
STRING | 請求 SKU ID。 | 4496-8C0D-228F |
product_display_name |
STRING | Google Cloud 商品名。 | Compute Engine |
month |
STRING | 年と月。 | 2024-01 |
day |
STRING | 年、月、日。 | 2024-01-10 |
hour |
STRING | 年、月、日、時。 | 2024-01-10T00 |
location ディメンションは、費用と使用量が割り当てられる Google Cloud リージョンまたはマルチリージョンを表します。このロケーションがどのように報告されるかは、レポートの範囲内のリソースのロケーション設定によって異なります。
us-central1-aなどの特定のゾーンにデプロイされたリソースの場合、費用と使用量は集計され、親リージョンに割り当てられます。この例では、locationディメンションにus-central1が表示されます。- リージョン（
us-central1など）にデプロイされたリソースの場合、locationディメンションにはその特定のリージョンが反映されます。 usなどのマルチリージョン用にデプロイまたは構成されたリソースの場合、locationディメンションにはそのマルチリージョンが反映されます。
時間ディメンション
結果を時間で集計するには、dimensions リストに month、day、hour などの時間ディメンションを 1 つ以上含めます。次の点にご注意ください。
- すべての時間ディメンションでは太平洋時間が使用され、夏時間（DST）が反映されます。
- 形式は ISO 8601 に準拠しています。
filterの期間が選択した時間ディメンションの粒度と完全に一致しない場合、期間は全期間をカバーするように拡張されます。たとえば、dimension: ["month"]を使用して 1 日の一部をフィルタすると、その月のデータ全体が含まれます。
指標
指標は、ディメンションで定義された各グループについて測定する定量的な値です。サポートされている指標は次のとおりです。
| 指標 | タイプ | 説明 |
|---|---|---|
cost |
RECORD | リクエストされた通貨での金銭的費用。 |
cpu_mean_utilization |
FLOAT64 | 平均 CPU 使用率（0.0 ～ 1.0）。 |
cpu_p95_utilization |
FLOAT64 | 95 パーセンタイルの CPU 使用率（0.0 ～ 1.0）。 |
cpu_usage_core_seconds |
INT64 | 実行された合計 CPU ワーク。 |
cpu_allocation_core_seconds |
INT64 | プロビジョニングされた合計 CPU 容量。 |
memory_mean_utilization |
FLOAT64 | 平均メモリ使用率（0.0 ～ 1.0）。 |
memory_p95_utilization |
FLOAT64 | 95 パーセンタイルのメモリ使用率（0.0 ～ 1.0）。 |
memory_usage_byte_seconds |
INT64 | 時間の経過に伴う合計メモリ使用量。 |
memory_allocation_byte_seconds |
INT64 | プロビジョニングされた合計メモリ（経時的）。 |
有効な組み合わせ
App Optimize API では、すべてのディメンションをすべての指標と組み合わせることはできません。次の表に、有効なディメンション セットの例と、それらで使用できる指標を示します。無効な組み合わせがリクエストされた場合、API はエラーを返します。有効な組み合わせについては、そのエラーを参照してください。
| ディメンション | cost 指標をサポート |
cpu_mean_utilization 指標をサポート |
|---|---|---|
application、product_display_name |
||
application |
||
location、product_display_name、project、resource、resource_type、sku |
||
location、product_display_name、project、resource、resource_type |
||
location、product_display_name、project、service_or_workload |
||
location、product_display_name、project、sku |
||
product_display_name、project |
||
product_display_name、resource_type |
||
product_display_name、resource |
||
product_display_name |
||
project |
フィルタ
filter フィールドを使用して、CEL 文字列でデータを絞り込みます。フィルタ式は、ディメンション テーブルに記載されている任意のフィールドを使用して作成できます。
フィルタリングは次の制約に準拠する必要があります。
- すべての文字列フィールド述語は、完全な文字列一致を使用する必要があります。例:
location == 'us-east1' - 同じ文字列フィールドを参照する複数の述語は、論理 OR 演算子
||を使用して結合する必要があります。例:location == 'us-east1' || location == 'us-west1' - 他のすべての述語は、論理 AND 演算子
&&を使用して結合する必要があります。 dayなどの時間ディメンションの述語で開始時間を指定する場合は、大なりイコール比較>=を使用する必要があります。- 終了時刻を指定する時間ディメンションの述語は、小なり比較
<を使用する必要があります。
期間
filter で時間ディメンション（month、day、hour）が省略されている場合、レポートは、前日の太平洋時間の午前 0 時を終了日とする 7 日間の範囲にデフォルト設定され、夏時間が考慮されます。期間の上限は現在の日付の 90 日前までで、開始時間は 90 日間の期間内に収まる必要があります。
たとえば、現在の太平洋標準時が 2026-01-05T12:00:00 の場合、デフォルトの範囲は 2025-12-29T00:00:00～2026-01-05T00:00:00 の太平洋標準時になります。期間の最も早い開始時間は 2025-10-07T00:00:00 です。
Cloud Run の指標は、現在の日付の 6 週間前までのデータのみ使用できます。
フィルタの使用例
CEL フィルタ文字列の構造例を次に示します。
特定のリソースタイプのレポートデータをフィルタするには、
resource_typeディメンションで==演算子を使用します。resource_type == 'compute.googleapis.com/Instance'1 つの場所のデータのみを含めるには、
locationディメンションでフィルタします。location == 'us-east1'特定のロケーションのリストのデータを含めるには、
||演算子を使用してlocationディメンションの条件を組み合わせます。location == 'us-east1' || location == 'us-west1'時間単位の粒度で特定の時間範囲内のデータを取得するには、
hourディメンションでフィルタできます。この例には、2024 年 1 月 1 日から 2024 年 2 月 1 日までのデータが含まれています。hour >= timestamp('2024-01-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')1 日単位でフィルタするには、
dayディメンションを使用します。日付の境界は太平洋時間で解釈されるため、オフセットを指定することが効果的な手法です。この例には、2024 年 3 月 15 日と 2024 年 3 月 16 日のすべてのデータが含まれます。day >= timestamp('2024-03-15T00:00:00-07:00') && day < timestamp('2024-03-17T00:00:00-07:00')同様に、
monthディメンションを使用してカレンダー月でフィルタすることもできます。この場合も、正確な境界については太平洋時間に注意してください。この例には、2025 年 10 月と 11 月のすべてのデータが含まれています。month >= timestamp('2025-10-01T00:00:00-07:00') && month < timestamp('2025-12-01T00:00:00-08:00')過去 72 時間のデータを取得するには、
hourディメンションでnow()関数とduration()関数を使用します。hour >= now() - duration('72h')過去 7 日間のデータを取得するには、
hourディメンションでduration()を使用します。hour >= now() - duration('168h')特定のカレンダー月（前月など）でフィルタリングするには、アプリケーション コードで開始タイムスタンプと終了タイムスタンプを計算する必要があります。次に、計算されたタイムスタンプを CEL 式に挿入します。概念的には、
dayディメンションでフィルタリングすると、次のようになります。day >= timestamp('START_OF_LAST_MONTH') && day < timestamp('START_OF_THIS_MONTH')次のように置き換えます。
START_OF_LAST_MONTH: 太平洋標準時で前月の初めを表す ISO 8601 タイムスタンプ文字列（例:2025-12-01T00:00:00-08:00）。START_OF_THIS_MONTH: 太平洋タイムゾーンの当月の初めを表す ISO 8601 タイムスタンプ文字列（2026-01-01T00:00:00-08:00など）。
これらの正確なタイムスタンプ文字列は、現在の日付、タイムゾーン（太平洋標準時）、夏時間の移行を考慮して、アプリケーション コードで計算する必要があります。
&&演算子を使用すると、文字列フィルタと時間フィルタを組み合わせることができます。この例では、特定の 2 か月間の 2 つの拠点をフィルタしています。(location == 'us-east1' || location == 'us-west1') && hour >= timestamp('2023-12-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')resource_type、project、dayベースの時間範囲を組み合わせた、より複雑な例を次に示します。resource_type == 'compute.googleapis.com/Instance' && project == 'projects/my-project' && day >= timestamp('2025-01-01T00:00:00-08:00') && day < timestamp('2025-02-01T00:00:00-08:00')
レポートのデータ構造
レポートを正常に読み取ると、サービスはデータを columns と rows として返します。
列
columns 配列は、rows に各フィールドが表示される順序で、データのスキーマを記述します。columns 配列内の各オブジェクトには、name、type があります。型が RECORD の場合は、ネストされた columns が含まれることもあります。
- リクエストしたディメンションは、型
STRINGのフィールドとして表示されます。 - リクエストした指標は、
costなどの複合型の場合、INT64、FLOAT64、RECORDなどの型を持つフィールドとして表示されます。
たとえば、REST API で dimensions: ["application", "product_display_name"] と metrics: ["cost", "cpu_mean_utilization"] をリクエストすると、App Optimize API は次のような columns 配列を生成します。
"columns": [
{
"name": "application",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "product_display_name",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "cost",
"type": "RECORD",
"mode": "NULLABLE",
"columns": [
{
"name": "currency_code",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "units",
"type": "INT64",
"mode": "NULLABLE"
},
{
"name": "nanos",
"type": "INT64",
"mode": "NULLABLE"
}
]
},
{
"name": "cpu_mean_utilization",
"type": "FLOAT64",
"mode": "NULLABLE"
}
]
行
rows フィールドには実際のデータが含まれます。各行は、単一のレコードを表す値の配列です。各内部配列内の値の順序は、columns 配列で定義されたフィールドの順序に直接対応します。
application、product_display_name、cost、cpu_mean_utilization が REST API からリクエストされた例を続けると、生成された rows 配列の単一行は次のようになります。
"rows": [
[
"//apphub.googleapis.com/projects/my-proj/locations/us-central1/applications/my-app",
"Compute Engine",
{
"currency_code": "USD",
"units": "12",
"nanos": 750000000
},
0.65
],
[
"//apphub.googleapis.com/projects/my-proj/locations/us-east1/applications/another-app",
"Cloud Storage",
{
"currency_code": "USD",
"units": "5",
"nanos": 200000000
},
0.15
]
]
次の表は、行配列内の値が columns 配列で定義されたスキーマにマッピングされる方法を、行配列内の値のインデックスを使用して視覚化したものです。
| 行内のインデックス | 対応する列 | タイプ | 値の例 |
|---|---|---|---|
| 0 | application |
STRING | "//apphub.googleapis.com/.../applications/my-app" |
| 1 | product_display_name |
STRING | "Cloud Storage" |
| 2 | cost |
RECORD | { "currency_code": "USD", "units": "10", ... } |
| 3 | cpu_mean_utilization |
FLOAT64 | 0.65 |
rows リストの各要素は配列です。値の順序は、columns 配列のフィールド定義の順序と一致します。したがって、任意の行配列のインデックス n の値は、columns 配列のインデックス n で定義された列に対応します。
費用指標の解釈
レポートに cost 指標が含まれている場合、標準の google.type.Money 型に基づいて、次のフィールドを含む RECORD として値が返されます。
| フィールド | タイプ | 説明 |
|---|---|---|
currency_code |
STRING | ISO 4217 で定められた 3 文字の通貨コードです（例: USD）。 |
units |
INT64 | 金額の整数部分。 |
nanos |
INT64 | 金額のナノ（10-9）単位。-999,999,999 ～+999,999,999 の範囲（両端を含む）にする必要があります。 |
完全な金銭的価値を取得するには、units フィールドと nanos フィールドを組み合わせます。nanos フィールドは、通貨値の小数部を表します。次に例を示します。
currency_codeが「USD」、unitsが106、nanosが321590000の場合: 値は 106 + (321,590,000 / 1,000,000,000) = 106.32159 USD です。currency_codeが「EUR」、unitsが5、nanosが750000000の場合: 値は 5 +（750,000,000 / 1,000,000,000）= 5.75 ユーロです。
通常、標準の通貨形式ライブラリを使用して、適切な通貨記号を含むわかりやすい形式でこの値を表示します。
API から返されるデータの詳細と制限事項については、データを理解するをご覧ください。
レポートの有効期限
各レポートは、レポートの作成から 24 時間後に App Optimize API サービスから自動的に削除されます。この期間を過ぎると、レポートとそのデータを API で取得できなくなります。レポートの有効期限を確認するには、レポートのメタデータを取得して expireTime フィールドを表示します。