创建和读取报告

借助 App Optimize API，您可以生成有关 Google Cloud 费用和资源用量的报告，以帮助您优化支出。在此快速入门中，您将使用 Google Cloud CLI、Python 客户端库或 REST API 创建报告、监控报告生成情况并读取报告的数据。

准备工作

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

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

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

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

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

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

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

    后续步骤