Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

创建报告

App Optimize API 可通过生成报告来帮助您分析费用和资源利用率数据。报告可以包含单个项目或单个 App Hub 应用的数据。

您首先需要发送 API 请求来创建报告。在此请求中，您可以定义数据的范围、数据的聚合或分组方式，以及要应用的任何过滤条件。

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

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

准备工作

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

在本指南中，标识为 PROJECT_ID 的项目提供了数据范围并托管了报告资源。

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

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

Verify that you have the permissions required to complete this guide.
选择标签页以了解您打算如何使用本文档中的示例：

gcloud

在 Google Cloud 控制台中，激活 Cloud Shell。

激活 Cloud Shell

Cloud Shell 会话随即会在控制台的底部启动，并显示命令行提示符。 Google Cloud Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟来完成初始化。

如需了解如何为生产环境设置身份验证，请参阅身份验证文档中的为在 Google Cloud 上运行的代码设置应用默认凭据。 Google Cloud

Python

安装 Python 客户端库 App Optimize API。
如需在本地开发环境中使用本页面上的 Python 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭证设置应用默认凭据。
1. 安装 Google Cloud CLI。
2. 如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。
3. 如果您使用的是本地 shell，请为您的用户账号创建本地身份验证凭证：
```
gcloud auth application-default login
```
  如果您使用的是 Cloud Shell，则无需执行此操作。
  
  如果返回了身份验证错误，并且您使用的是外部身份提供方 (IdP)，请确认您已使用联合身份登录 gcloud CLI。
如需了解详情，请参阅身份验证文档中的为本地开发环境设置 ADC Google Cloud

如需了解如何为生产环境设置身份验证，请参阅身份验证文档中的为在 Google Cloud 上运行的代码设置应用默认凭据。 Google Cloud

REST

如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭证。

安装 Google Cloud CLI。

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

如需了解详情，请参阅身份验证文档中的 Google Cloud 使用 REST 时进行身份验证。

如需了解如何为生产环境设置身份验证，请参阅身份验证文档中的为在 Google Cloud 上运行的代码设置应用默认凭据。 Google Cloud

所需的角色

如需获得使用本指南创建报告所需的权限，请让您的管理员为您授予包含活跃资源的项目中的以下 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 产品及其位置。

如需创建报告资源，请按照您首选方法的说明操作：

gcloud

使用以下 gcloud beta app-optimize reports create 命令创建报告。

gcloud beta app-optimize reports create REPORT_ID \
  --project=PROJECT_ID \
  --location=global \
  --dimensions=location,product_display_name,project,resource,resource_type \
  --metrics=cost,cpu_mean_utilization \
  --report-filter='hour >= now - duration("168h")' \
  --scopes=project=projects/PROJECT_ID

替换以下内容：

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

用于创建报告的命令会自动等待操作完成。

Python

以下 Python 代码使用 AppOptimizeClient.create_report() 创建报告。

from google.cloud import appoptimize_v1beta

project_id = "PROJECT_ID"
report_id = "REPORT_ID"

# Create the App Optimize client
client = appoptimize_v1beta.AppOptimizeClient()

# Initialize the report request
report = appoptimize_v1beta.Report(
    dimensions=['location', 'product_display_name', 'project', 'resource', 'resource_type'],
    metrics=['cost', 'cpu_mean_utilization'],
    filter='hour >= now - duration("168h")',
    scopes=[
        appoptimize_v1beta.Scope(project=f"projects/{project_id}"),
    ],
)
request = appoptimize_v1beta.CreateReportRequest(
    parent=f"projects/{project_id}/locations/global",
    report=report,
    report_id=report_id,
)

# Send the request and wait for completion
operation = client.create_report(request=request)
print("Waiting for operation to complete...")
response = operation.result()
print(response)

替换以下内容：

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

客户端库中的 operation.result() 方法会自动等待操作完成。无需手动轮询循环。

REST

向 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 完成为止。

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

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

如果您计划同时创建多个报告，请考虑您的团队何时运行报告以及 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 个数据请求失败。

为避免此问题，团队可以先运行应用标准版的报告，然后再运行高级版的报告。

后续步骤

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

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

准备工作

gcloud

Python

REST

所需的角色

创建报告

gcloud

Python

REST

并发限制

后续步骤

创建报告