Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

创建报告

借助 App Optimize API，您可以生成报告，分析单个项目或 App Hub 应用的费用和资源利用率数据。

概览

您可以通过发送 API 请求来创建报告，该请求定义了数据的范围、应如何聚合或分组数据，以及要应用的所有过滤条件。API 请求会创建一个长时间运行的操作 (LRO)，用于生成报告。

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

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

准备工作

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

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

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

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

gcloud

安装 Google Cloud CLI。

配置 gcloud CLI 以使用您的联合身份。

如需了解详情，请参阅使用联合身份登录 gcloud CLI。

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

gcloud init

初始化 gcloud CLI 后，对其进行更新并安装所需组件：

gcloud components update
gcloud components install beta

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

Python

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

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

REST

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

安装 Google Cloud CLI，然后使用联合身份登录 gcloud CLI。

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

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

所需的角色

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

App Optimize Admin (roles/appoptimize.admin)
Monitoring Viewer (roles/monitoring.viewer)
Cloud Hub Operator (roles//cloudhub.operator)（或授予 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 完成为止。

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

您可以在 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 个数据请求会失败。

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

后续步骤

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

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

概览

准备工作

gcloud

Python

REST

所需的角色

创建报告

gcloud

Python

REST

并发限制

后续步骤

创建报告