报告简介

如需使用 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 替换为您的 Google Cloud 项目的 ID。例如 projects/my-project-1。
application：一个字符串，表示 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，则输出中会包含一行数据，对应于数据中找到的项目和商品名称值的每个唯一组合。

下表列出了支持的维度：

维度	类型	说明	示例值
`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。请注意：

所有时间维度均使用太平洋时间，并会根据夏令时 (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），报告默认采用从太平洋时间午夜结束的 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'
```
如需仅包含来自单个位置的数据，请按 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')
```
如需获取过去 7 天的数据，您可以将 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 的字段。
您请求的指标会显示为具有 INT64、FLOAT64 等类型的字段，对于 cost 等复杂类型，则显示为 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 指标，则返回的值为 RECORD，其中包含以下字段（基于标准 google.type.Money 类型）：

字段	类型	说明
`currency_code`	STRING	由 3 个字母组成的 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 字段。