如要使用 App Optimize API 擷取費用和用量資料，請先建立報表。這個資源會做為您要分析的資料的持續定義，指定範圍、維度、時間範圍和篩選器等參數。
建立報表後，API 會非同步產生所要求的資料。接著，您可以使用報表的資源名稱擷取產生的資料集。
因此工作流程如下：
- 您可建立報表並指定條件。
- 系統會以非同步方式處理這項要求。
- 作業完成後，您會讀取結果資料。
本文詳細說明 App Optimize API 報表的結構和可設定的參數，包括可用的維度、指標和篩選選項，並說明傳回的資料格式。
如要瞭解費用和用量限制，請參閱「瞭解資料」。
定義報表
如要建立報表，請使用下列設定參數定義 Report 資源，這些參數會在下一個小節中說明：
| 參數 | 類型 | 說明 |
|---|---|---|
scopes |
陣列 | 要分析的專案或 App Hub 應用程式。您必須提供一個範圍元素。 |
dimensions |
陣列 | 要擷取及分組資料的屬性，包括以時間為準的分組。 |
metrics |
陣列 | 要傳回的特定測量值。 |
filter |
字串 | 用於縮小資料範圍的一般運算語言 (CEL) 運算式，包括時間範圍。 |
範圍
scopes 欄位定義 App Optimize API 要分析的資源集。雖然這個欄位是陣列，但您必須指定一個元素，可以是專案或 App Hub 應用程式：
project：代表 Google Cloud 專案的字串。格式必須如下：projects/PROJECT_ID將
PROJECT_ID替換為專案 ID。 Google Cloud 例如：projects/my-project-1。application：字串，代表應用程式中心的應用程式完整資源名稱。格式必須如下：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，輸出內容會針對資料中找到的每個專案和產品名稱值的不重複組合，各包含一列。
下表列出支援的維度：
| 維度 | 類型 | 說明 | 範例值 |
|---|---|---|---|
project |
STRING | 專案 ID。 Google Cloud | 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。請注意：
- 所有時間維度均採用太平洋時間，並會隨日光節約時間 (DST) 進行調整。
- 格式遵循 ISO 8601。
- 如果
filter中的時間範圍與所選時間維度的精細程度不完全一致，系統會擴大範圍，涵蓋完整週期。舉例來說，如果使用dimension: ["month"]篩選某天的部分時段，系統會納入整個月的資料。
指標
指標是您想針對維度定義的每個群組評估的量化值。支援的指標如下：
| 指標 | 類型 | 說明 |
|---|---|---|
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)，報表會預設為七天範圍，並以太平洋時間前一天的午夜為結尾，且會考量日光節約時間。日期範圍最長可回溯至目前日期前 90 天，且開始時間必須在 90 天內。
舉例來說，如果目前的太平洋時間是 2026-01-05T12:00:00，預設範圍就是太平洋時間 2025-12-29T00:00:00 到 2026-01-05T00:00:00。時間範圍的最早開始時間為 2025-10-07T00:00:00。
Cloud Run 指標僅提供目前日期前六週的資料。
篩選器範例
以下舉例說明如何建構 CEL 篩選條件字串：
如要依特定資源類型篩選報表資料，請在
resource_type維度上使用==運算子：resource_type == 'compute.googleapis.com/Instance'如要只納入單一位置的資料，請依
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')如要篩選整天，請使用
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')如要取得過去七天的資料，可以使用
duration()和hour維度：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。
您需要在應用程式程式碼中計算這些確切的時間戳記字串，並考量目前日期、時區 (太平洋時區) 和日光節約時間轉換。
您可以使用
&&運算子合併字串和時間篩選器。 這個範例會篩選特定兩個月期間內的兩個地點：(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 陣列中定義的欄位順序。
繼續以從 REST API 要求 application、product_display_name、cost 和 cpu_mean_utilization 的範例來說明，產生的 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 三碼貨幣代碼，例如「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 美元。如果
currency_code為「EUR」，units為5，且nanos為750000000： 值為 5 + (750,000,000 / 1,000,000,000) = 5.75 歐元。
您通常會使用標準貨幣格式設定程式庫，以方便使用者閱讀的格式顯示這個值，包括適當的貨幣符號。
如要進一步瞭解 API 傳回的資料，以及相關限制，請參閱「瞭解資料」一文。
回報過期
系統會在報表建立 24 小時後，自動從 App Optimize API 服務中刪除報表。期限過後，您就無法透過 API 擷取報表和資料。如要查看報表的排定到期時間，請取得報表的中繼資料，然後查看 expireTime 欄位。