建立及讀取報表

瞭解如何建立 App Optimize 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

Google Cloud 主控台底部會開啟一個 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。

如要瞭解如何設定正式環境的驗證機制，請參閱 Google Cloud 驗證說明文件中的「 為在 Google Cloud上執行的程式碼設定應用程式預設憑證 」。

Python

  1. 安裝 App Optimize API 適用的 Python 用戶端程式庫。

  2. 如要在本機開發環境中使用本頁的 Python 範例，請安裝並初始化 gcloud CLI，然後使用您的使用者憑證設定應用程式預設憑證。

    1. 安裝 Google Cloud CLI。

    2. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

    3. 如果您使用本機殼層，請為使用者帳戶建立本機驗證憑證： 

      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 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

將 HTTP POST 要求傳送至 REST API 的projects.locations.reports資源路徑。

  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，直到 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"

後續步驟