创建报告

App Optimize API 可通过生成报告来帮助您分析费用和资源利用率数据。如需获取此信息，您需要先通过发送 API 请求来创建报告。在此请求中，您可以定义数据的范围、应如何聚合或分组数据，以及要应用的所有过滤条件。

报告准备就绪后，您就可以读取数据了。

如需了解可用的范围、维度、指标和过滤条件，以及这些设置的有效组合，请参阅报告简介。

准备工作

本指南中的示例需要使用包含有效资源的项目进行分析。 Google Cloud App Optimize API 需要结算和利用率数据才能生成有意义的结果；针对新项目或空项目运行的报告将为空。

此项目由您选择，并由 PROJECT_ID 标识。为简单起见，在本指南中，您的项目将同时托管报告资源并提供数据范围。

App Optimize API 支持在一个项目中创建报告，以分析来自其他源项目或来自单项目或文件夹级边界中的应用的数据。如果您要针对 App Hub 应用（可能由多个项目组成）生成报告，则必须拥有该应用的所有关联项目的必需监控和结算权限，才能创建报告。
确保您将用于创建和管理报告资源的项目已启用 App Optimize API。在本文档的示例中，这是由 PROJECT_ID 标识的项目。

登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

安装 Google Cloud CLI。

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

gcloud init

验证您是否拥有完成本指南所需的权限。

安装 Google Cloud CLI。

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

gcloud init

验证您是否拥有完成本指南所需的权限。

所需的角色

如需获得使用本指南创建报告所需的权限，请让您的管理员为您授予包含有效资源的项目的以下 IAM 角色：

App Optimize Admin (roles/appoptimize.admin)
Monitoring Viewer (roles/monitoring.viewer)
Viewer (roles/viewer)（或授予 billing.resourceCosts.get 的其他角色）

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

如需详细了解 App Optimize API 所需的权限和角色，请参阅使用 IAM 进行访问权限控制。

创建报告

以下步骤介绍了如何开始创建报告。此示例会生成一份报告，帮助您了解所选项目过去一周的费用和平均 CPU 使用率。该报告会按每项资源细分这些信息，包括资源类型、所属的 Google Cloud 产品及其位置。

如需创建报告资源，请向 REST API 的 projects.locations.reports 资源路径发送 HTTP POST 请求。

请按照以下步骤创建报告。

使用以下 curl 命令发送请求。请求正文包含报告定义，包括所请求的范围、维度、指标和所有过滤条件。

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": [
      {
        "project": "projects/PROJECT_ID"
      }
    ],
    "dimensions": [
      "location",
      "product_display_name",
      "project",
      "resource",
      "resource_type"
    ],
    "metrics": [
      "cost",
      "cpu_mean_utilization"
    ],
    "filter": "hour >= now - duration(\"168h\")"
  }' \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/reports?report_id=REPORT_ID"

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
REPORT_ID：新报告的唯一 ID，例如 my-resource-cost-report-1。

该 API 会返回一个长时间运行的操作 (LRO) 对象。请注意响应中的 name 字段，您将使用该字段来检查操作的状态：

{
  "name": "projects/PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.appoptimize.v1beta.OperationMetadata"
  },
  "done": false
}

在响应中，done 字段为 false，表示报告生成正在进行中。

如需检查报告是否已准备就绪，请向在上一步中返回的操作 name 发送 GET HTTP 请求：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/operations/OPERATION_ID"

将 PROJECT_ID 和 OPERATION_ID 替换为 LRO 响应中的值。

检查响应以确定操作的状态：

如果报告仍在生成中，则响应将类似于初始 LRO 响应，其中 done 设置为 false。您应等待一小段时间（例如 5 到 15 秒），然后重复此步骤再次进行轮询。

报告生成完成后，响应将包含 "done": true，并在 response 字段中包含报告资源：

{
  "name": "projects/PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.appoptimize.v1beta.OperationMetadata"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.appoptimize.v1beta.Report",
    "name": "projects/PROJECT_ID/locations/global/reports/REPORT_ID",
    "dimensions": [
      "location",
      "product_display_name",
      "project",
      "resource",
      "resource_type"
    ],
    "scopes": [
      {
        "project": "projects/PROJECT_ID"
      }
    ],
    "filter": "hour >= now - duration(\"168h\")",
    "expireTime": "2026-02-05T18:50:25.273833857Z",
    "metrics": [
      "cost",
      "cpu_mean_utilization"
    ]
  }
}

如果 LRO 遇到错误，响应将包含 error 字段，而不是 response 字段，并提供有关失败的详细信息。

操作成功完成后，您可以读取报告的数据。

并发限制

创建报告时，App Optimize API 会从 Cloud Billing 获取费用数据，并从 Cloud Monitoring 获取报告中每个 target_project 的利用率数据。

对于范围限定为单个项目的报告，该项目就是目标项目。
对于 App Hub 应用，包含该应用中的服务或工作负载的每个项目都是目标项目。

App Optimize API 会强制执行一项并发配额，称为“并发 CreateReport 操作”，该配额允许每个目标项目最多同时发出 10 个报告数据请求。当您创建报告时，App Optimize API 会计算报告中的目标项目数量，并锁定所需数量的配额单位，直到创建报告的 LRO 完成为止。

由于系统级衡量时间安排，在几分钟内完成的报告可能不会计入并发限制。

您可以在 Google Cloud 控制台的配额和系统限制页面上查看当前的 API 活动并管理这些限制。

如果您计划同时创建多个报告，请考虑团队运行报告的时间以及 App Hub 应用的结构：

如果多个团队运行的报告包含相同的目标项目，您可以错开每个团队的报告创建开始时间。
应用可以包含多个项目中的资源，并且多个应用可以使用单个项目中的资源。同时为这些类型的应用创建报告会导致向目标项目发出多个请求。

例如，假设某个团队开发了一套用于学习创意艺术的应用，并提供标准版和高级版。下表的第一列显示了应用列表。在其余列中，对勾标记图标 () 表示相应项目包含所列应用的某些服务或工作负载。

应用	common-project	dance-project	draw-project	animate-project	music-project
dance-app
draw-app
music-app
animate-app
choreograph-app
storyteller-app
dance-premium-app
draw-premium-app
music-premium-app
animate-premium-app
choreograph-premium-app
storyteller-premium-app

如果您同时为所有列出的应用创建费用和利用率数据报告，则 App Optimize API 在某些项目中使用的并发限制单位数会超过一个。具体而言，共享项目 common-project 接收到 12 个费用和利用率数据请求。由于此数量超过了并发限制，因此 2 个数据请求将失败。

为防止出现此问题，该团队可以先针对应用的标准版本运行报告，然后再针对应用的付费版本运行报告。

后续步骤

如需了解维度、指标和过滤条件，请参阅报告简介。
探索管理报告的其他方法：

创建报告 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

所需的角色

创建报告

并发限制

后续步骤

创建报告