建立及讀取報表

瞭解如何建立 App Optimize API 支出報表、監控報表產生作業，以及在報表完成後讀取資料。 Google Cloud在本快速入門指南中，您將使用 REST API。

事前準備

本指南中的範例需要 Google Cloud 含有有效資源的專案，才能進行分析。App Optimize API 需要帳單和使用情形資料，才能產生有意義的結果；針對新專案或空白專案執行的報表會是空白。

這個專案是由您選擇，並以 PROJECT_ID 識別。為簡化作業，在本指南中，您的專案會同時代管報表資源並提供資料範圍。

App Optimize API 支援在一個專案中建立報表，分析來自不同來源專案或單一專案或資料夾層級界線內應用程式的資料。如果您要產生應用程式中樞應用程式的報表 (這類應用程式可能由多個專案組成)，您必須對應用程式的所有相關聯專案具備必要的監控和帳單權限，才能建立報表。
請確認您用於建立及管理報表資源的專案已啟用 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 角色：

應用程式最佳化管理員 (roles/appoptimize.admin)
檢視者 (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，直到 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 總覽」。