创建和读取报告

了解如何创建应用优化 API 报告来查看 Google Cloud支出、监控报告的生成情况，以及在报告准备就绪后读取生成的数据。在本快速入门指南中，您可以使用 REST API 或 Python 客户端库。

准备工作

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

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

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

  • 确保您将用于创建和管理报告资源的项目已启用 App Optimize API。

gcloud

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

激活 Cloud Shell

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

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

Python

  1. 安装 App Optimize API 的 Python 客户端库。

  2. 如需在本地开发环境中使用本页面上的 Python 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭据设置应用默认凭据。

    1. 安装 Google Cloud CLI。

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

    3. 如果您使用的是本地 shell，请为您的用户账号创建本地身份验证凭证： 

      gcloud auth application-default login

      如果您使用的是 Cloud Shell，则无需执行此操作。

      如果系统返回身份验证错误，并且您使用的是外部身份提供方 (IdP)，请确认您已 使用联合身份登录 gcloud CLI。

    如需了解详情，请参阅 Google Cloud 身份验证文档中的 为本地开发环境设置 ADC。

    如需了解如何为生产环境设置身份验证，请参阅 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)
  • Viewer (roles/viewer)（或其他授予 billing.resourceCosts.get 的角色）

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

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

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

创建报告

此示例会生成一份报告，其中包含您所选 PROJECT_ID 内的总支出。该报告会按所用的每种Google Cloud 产品（例如 Compute Engine 和 Cloud Storage）以及按特定 SKU 和位置细分费用。此报告涵盖过去三天的数据。

如需创建报告资源，请按照您偏好的方法对应的说明操作：

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,sku \
  --metrics=cost \
  --report-filter='hour >= now - duration("72h")' \
  --scopes=project=projects/PROJECT_ID

替换以下内容：

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

该命令会等待报告创建操作完成，然后返回创建的报告资源。

Python

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

from google.cloud import appoptimize_v1beta

project_id = "PROJECT_ID"
report_id = "REPORT_ID"

# Create the App Optimize client and prepare a request for a new report
client = appoptimize_v1beta.AppOptimizeClient()
report = appoptimize_v1beta.Report(
    dimensions=['location', 'product_display_name', 'project', 'sku'],
    metrics=['cost'],
    filter='hour >= now - duration("72h")',
    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,
)

# Request the creation of the report and wait until the process is done
operation = client.create_report(request=request)
print("Waiting for report creation 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 请求。

  1. 如需发送请求，请使用以下 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",
      "sku"
    ],
    "metrics": [
      "cost"
    ],
    "filter": "hour >= now - duration(\"72h\")"
  }' \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/reports?report_id=REPORT_ID"

    替换以下内容：

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

    该 API 会返回一个长时间运行的操作 (LRO) 对象，用于表示报告生成过程。以下是示例回答：

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

    "done": false 状态表示报告仍在生成中。请记下 OPERATION_ID，因为您会在下一步中使用此值。

  2. 由于生成报告可能需要一些时间，因此您需要轮询 LRO，直到它指示生成过程已完成并且报告的数据已可供下载。

    如需检查生成过程的状态，请向操作的资源名称发送 HTTP GET 请求：

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

    检查回答。如果 "done" 为 false，请等待 5 到 15 秒，然后重复此步骤。如果 "done" 为 true，则表示报告已准备就绪。

    以下是操作完成后的响应示例：

    {
  "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",
    "scopes": [
      {
        "project": "projects/PROJECT_ID"
      }
    ],
    "dimensions": [
      "location",
      "product_display_name",
      "project",
      "sku"
    ],
    "metrics": [
      "cost"
    ],
    "filter": "hour >= now - duration(\"72h\")",
    "expireTime": "2026-02-04T22:05:05Z"
  }
}

读取报告数据

如需检索报告数据，请按照您喜欢的方法对应的说明操作：

gcloud

使用以下 gcloud beta app-optimize reports read 命令来提取报告的数据。

gcloud beta app-optimize reports read REPORT_ID \
  --project=PROJECT_ID \
  --location=global

Python

以下 Python 代码使用 AppOptimizeClient.read_report() 来提取报告的数据。

from google.cloud import appoptimize_v1beta

project_id = "PROJECT_ID"
report_id = "REPORT_ID"
name = f"projects/{project_id}/locations/global/reports/{report_id}"

# Create the App Optimize client and read your report's data
client = appoptimize_v1beta.AppOptimizeClient()
request = appoptimize_v1beta.ReadReportRequest(
        name=name,
)
result = client.read_report(request=request)

# Display the report's data
print(result)

REST

LRO 完成后，使用 REST API 的 :read 自定义方法：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/reports/REPORT_ID:read"

API 的响应包含报告数据行和列定义。 以下是成功响应的示例：

{
  "rows": [
    [
      "us-central1",
      "Compute Engine",
      "projects/PROJECT_ID",
      "6EC2-384A-47D9",
      {
        "currency_code": "USD",
        "units": "25",
        "nanos": 750000000
      }
    ],
    [
      "us-central1",
      "Cloud Storage",
      "projects/PROJECT_ID",
      "9ADA-9ADC-2FBE",
      {
        "currency_code": "USD",
        "units": "5",
        "nanos": 100000000
      }
    ],
    [
      "europe-west1",
      "Compute Engine",
      "projects/PROJECT_ID",
      "6EC2-384A-47D9",
      {
        "currency_code": "USD",
        "units": "18",
        "nanos": 500000000
      }
    ],
    [
      "us-central1",
      "Compute Engine",
      "projects/PROJECT_ID",
      "F61D-4D51-AAFC",
      {
        "currency_code": "USD",
        "units": "12",
        "nanos": 200000000
      }
    ]
  ],
  "columns": [
    {
      "name": "location",
      "type": "STRING",
      "mode": "NULLABLE"
    },
    {
      "name": "product_display_name",
      "type": "STRING",
      "mode": "NULLABLE"
    },
    {
      "name": "project",
      "type": "STRING",
      "mode": "NULLABLE"
    },
    {
      "name": "sku",
      "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"
        }
      ]
    }
  ],
  "next_page_token": ""
}

包含大量行的报告会进行分页。如需处理多个页面，请参阅读取报告的数据。

如需了解 cost 字段中的值，请参阅解读费用指标。 如需详细了解相关数据并了解其限制，请参阅了解数据。

清理

App Optimize API 会在报告创建 24 小时后自动将其删除。如需尽快删除报告，请按照您偏好的方法对应的说明操作：

gcloud

使用 gcloud beta app-optimize reports delete 命令可移除报告。

gcloud beta app-optimize reports delete REPORT_ID \
  --project=PROJECT_ID \
  --location=global

Python

以下代码使用 AppOptimizeClient.delete_report() 移除报告。

from google.cloud import appoptimize_v1beta

project_id = "PROJECT_ID"
report_id = "REPORT_ID"

name = f"projects/{project_id}/locations/global/reports/{report_id}"
client = appoptimize_v1beta.AppOptimizeClient()
request = appoptimize_v1beta.DeleteReportRequest(name=name)
client.delete_report(request=request)
print(f"Deleted report: {name}")

REST

向报告的资源端点发送 HTTP DELETE 请求：

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

后续步骤