创建和读取报告

了解如何创建支出 Google CloudApp Optimize API 报告、监控报告的生成情况，以及在报告数据准备就绪后读取这些数据。在本快速入门指南中，您将使用 REST 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 管理员 (roles/appoptimize.admin)
Viewer (roles/viewer)（或其他授予 billing.resourceCosts.get 的角色）

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

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

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

创建报告

此示例将创建一份报告，其中包含您选择的 PROJECT_ID中的总支出。该报告会按使用的每种 Google Cloud 产品（例如 Compute Engine 和 Cloud Storage）以及特定 SKU 和位置细分费用。该报告涵盖了最近三天的数据。

如需创建报告资源，请向 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",
      "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，因为您将在下一步中使用它。

由于报告生成可能需要一些时间，因此您需要轮询 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"
  }
}

读取报告数据

如需检索报告数据，请在 LRO 完成后使用 :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"

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

{
  "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 小时后自动删除该报告。如需更快地删除报告，请向报告的资源端点发送 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"

后续步骤

详细了解报告。
探索管理报告的其他方法：
- 列出报告。
- 获取报告的元数据。
- 删除报告。
参阅 App Optimize API 概览。