Cloud Billing Budget API の使用

簡単なリクエストを Cloud Billing Budget API に送信する方法について説明します。

すべてのメソッドの一覧については、REST API または RPC API のリファレンスドキュメントをご覧ください。

始める前に

このガイドを読む前に、次の手順を行ってください。

Cloud Billing Budget API の概要をご覧ください。
Cloud Billing Budget API の前提条件をご覧ください。
手順に沿って設定してください。

Cloud 請求先アカウント ID を特定する

すべての Cloud Billing Budget API 呼び出しで Cloud 請求先アカウント ID が必要です。

Google Cloud Console 請求先アカウントの管理ページに移動します。
[自分の請求先アカウント] タブに、Cloud 請求先アカウントのリストが名前と ID 順に表示されます。予算を管理するアカウントの請求先アカウント ID を探します。

請求先アカウント ID の場所を示す請求管理ページのスクリーンショット。

主な予算のコンセプト

予算は、請求先アカウント全体に適用できます。または、詳細な予算フィルタを使用して範囲を設定（フィルタ適用）して、費用の特定の部分のみをモニタリングすることもできます。
Cloud 請求先アカウント全体に適用される予算には、対象の請求先アカウントで支払われるすべての Google Cloud プロジェクトの費用が含まれます。
Cloud 請求先アカウントへのアクセス権がないか、制限されている場合は、自身が所有するプロジェクトの単一プロジェクト予算を作成できます。Cloud 請求先アカウントレベルのユーザーは、予算の OwnershipScope フィールドを使用して、プロジェクトレベルのユーザーが変更できない単一プロジェクト予算を作成できます。
フィルタを使用して、予算の範囲を組織、フォルダ、プロジェクト、サービスのサブセットなどに絞り込んだり、Cloud 請求先アカウントに適用された他の予算フィルタを使用できます。
予算の期間を指定できます。デフォルトでは、予算は暦月に発生した費用をモニタリングします。Cloud Billing Budget API で使用可能な usage_period フィルタを使用すると、予算の期間を CalendarPeriod または CustomPeriod に構成し、予算を作成してデフォルトの歴月を超える期間（例: 四半期、年、または指定したカスタムの日付範囲）についてモニタリングできます。
指定した合計額に予算額を設定するか、前回のカレンダー期間の支出額に基づいて予算額を設定できます。
予算に関するしきい値のルールを設定してメール通知アラートをトリガーできます。費用（実際の費用または予測費用）が、設定したルールに基づく予算のパーセンテージを超えると、指定した受信者にアラートメールが送信されます。
予算の通知ルールを設定して、予算アラートのメール受信者を指定し、Pub/Sub を使用したプログラムによる通知を有効にできます。
プログラムによる通知では、Pub/Sub トピックを使用できます（例: 予算メッセージを Slack などの他のメディアに転送する、コスト管理タスクを自動化するなど）。

割り当て上限: 個々の Cloud 請求先アカウントには、一度に数千件の予算を関連付けることができます。現在の上限と追加情報については、割り当てと上限をご覧ください。

API の呼び出し

次のサンプルは、Cloud Billing Budget API に簡単なリクエストを送信する方法を示しています。

予算の一覧表示

この API メソッドは、特定の Cloud 請求先アカウントで使用できるすべての予算を表示します。

REST

リクエストのデータを使用する前に、次のように置き換えます。

billing-account-id: 予算が適用される Cloud 請求先アカウント ID。
project-id: Cloud Billing Budget API が有効になっている Google Cloud プロジェクト。

HTTP メソッドと URL:

GET https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets

リクエストを送信するには、次のいずれかのオプションを開きます。

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "budgets": [
   {
      "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
      "displayName": "Forecasted spend budget with Service Filter",
      "budgetFilter": {
        "projects": [
          "projects/123456789"
        ],
        "services": [
          "services/A1E8-BE35-7EBC"
        ],
        "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
        "calendarPeriod": "MONTH"
      },
      "amount": {
        "lastPeriodAmount": {}
      },
      "thresholdRules": [
        {
          "thresholdPercent": 0.9,
          "spendBasis": "FORECASTED_SPEND"
        }
      ],
      "allUpdatesRule": {},
      "etag": "c9d6c011f6fa6b5c"
    }
  ]
}

予算の取得

この API メソッドは、特定の予算の詳細を取得します。

REST

このメソッドを呼び出すには、更新する予算の budget-id が必要です。予算 ID は、予算の作成時に createBudget の出力から取得できます。また、すべての予算のリストを表示した場合は、listBudgets の出力から取得できます。

リクエストのデータを使用する前に、次のように置き換えます。

billing-account-id: この予算が適用される Cloud 請求先アカウント ID。
budget-id: 取得する予算の ID。
project-id: Cloud Billing Budget API が有効になっている Google Cloud プロジェクト。

HTTP メソッドと URL:

GET https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id

リクエストを送信するには、次のいずれかのオプションを開きます。

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id"

PowerShell（Windows）

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "Forecasted spend budget with Service Filter",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "services": [
      "services/A1E8-BE35-7EBC"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
  },
  "amount": {
    "lastPeriodAmount": {}
  },
  "thresholdRules": [
    {
      "thresholdPercent": 0.9,
      "spendBasis": "FORECASTED_SPEND"
    }
  ],
  "allUpdatesRule": {},
  "etag": "c9d6c011f6fa6b5c"
}

予算の作成

この API メソッドは、指定された Cloud 請求先アカウントに適用される Cloud Billing 予算を作成します。

REST

このサンプルでは、指定した Google Cloud プロジェクトで範囲を限定（フィルタリング）して、所定の Cloud 請求先アカウントの予算を作成し四半期のカレンダー期間に対して設定する方法を示します。

リクエストのデータを使用する前に、次のように置き換えます。

projects/budget-scope-project-id: 予算の範囲（budgetFilter）として設定する Google Cloud プロジェクト ID。
billing-account-id: この予算が適用される Cloud 請求先アカウント ID。
api-user-project-id: Cloud Billing Budget API が有効になっている Google Cloud プロジェクト。

HTTP メソッドと URL:

POST https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets

リクエストの本文（JSON）:

{
  "displayName": "Keep my spending down",
  "budgetFilter": {
    "projects": [
      "projects/budget-scope-project-id"
    ],
    "calendar_period": "QUARTER"
  },
  "amount": {
    "lastPeriodAmount": {}
  },
  "thresholdRules": {
    "thresholdPercent": 0.8,
    "spendBasis": "CURRENT_SPEND"
  }
}

リクエストを送信するには、次のいずれかのオプションを開きます。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: api-user-project-id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "api-user-project-id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "Keep my spending down",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "creditTypesTreatment": "INCLUDE_ALL_CREDITS",
    "calendar_period": "QUARTER"
  },
  "amount": {
    "lastPeriodAmount": {}
  },
  "thresholdRules": {
    "thresholdPercent": 0.8,
    "spendBasis": "CURRENT_SPEND"
  },
  "allUpdatesRule": {},
  "etag": "f7928d8010160668"
}

予算の更新

この API メソッドを使用して、既存の Cloud Billing 予算を変更し、予算額、予算フィルタ（予算の範囲）、予算期間またはしきい値ルールを変更します。

REST

このサンプルは、既存の予算を更新して指定した Google Cloud プロジェクトでスコープ（フィルタ）を設定し、月単位の予算から四半期単位の予算へと予算の期間を更新する方法を示しています。

リクエストのデータを使用する前に、次のように置き換えます。

projects/budget-scope-project-id: 予算の範囲（budgetFilter）として設定する Google Cloud プロジェクト ID。
billing-account-id: この予算が適用される Cloud 請求先アカウント ID。
budget-id: 更新する予算の ID。
api-user-project-id: Cloud Billing Budget API が有効になっている Google Cloud プロジェクト。

HTTP メソッドと URL:

PATCH https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id

リクエストの本文（JSON）:

{
  "budget": {
    "displayName": "My fancy budget",
    "budgetFilter": {
      "projects": [
        "projects/budget-scope-project-id"
      ],
      "calendar_period": "QUARTER"
    },
   "amount": {
      "specifiedAmount": {
        "units": 500
      }
    },
    "thresholdRules": {
      "thresholdPercent": 0.8,
      "spendBasis": "CURRENT_SPEND"
    }
  }
}

リクエストを送信するには、次のいずれかのオプションを開きます。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: api-user-project-id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "api-user-project-id" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "My fancy budget",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "creditTypesTreatment": "INCLUDE_ALL_CREDITS",
    "calendar_period": "QUARTER"
  },
  "amount": {
    "specifiedAmount": {
      "units": 500
    }
  },
  "thresholdRules": {
    "thresholdPercent": 0.8,
    "spendBasis": "CURRENT_SPEND"
  },
  "allUpdatesRule": {},
  "etag": "f7928d8010160668"
}

予算を削除する

この API メソッドを使用して、既存の Cloud Billing 予算を削除します。

REST

リクエストのデータを使用する前に、次のように置き換えます。

billing-account-id: この予算が適用される Cloud 請求先アカウント ID。
budget-id: 削除する予算の ID。
project-id: Cloud Billing Budget API が有効になっている Google Cloud プロジェクト。

HTTP メソッドと URL:

DELETE https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id

リクエストを送信するには、次のいずれかのオプションを開きます。

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id"

PowerShell（Windows）

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{}

セットアップ