创建和读取报告

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

准备工作

  • 本指南中的示例需要使用包含活跃 资源的 Google Cloud project 进行分析。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. 安装 Python 客户端库 App Optimize API。

  2. 如需在本地开发环境中使用本页面上的 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)
  • 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"

后续步骤