費用上限予算リクエストを Cloud Billing Budget API に送信する方法について説明します。
メソッドの完全な一覧については、REST API リファレンス ドキュメントをご覧ください。
始める前に
このガイドを読む前に、次の手順を行ってください。
- Cloud Billing Budget API の概要をご覧ください。
- Cloud Billing Budget API の前提条件をご覧ください。
- 手順に沿って設定してください。
Cloud 請求先アカウント ID を特定する
すべての Cloud Billing Budget API 呼び出しで Cloud 請求先アカウント ID が必要です。費用の上限予算は、ファーストパーティのGoogle Cloud ユーザーと Cloud 請求先アカウントに限定されます。販売パートナーの請求先アカウントは対象外です。
- Google Cloud コンソールの [請求先アカウントの管理] ページに移動します。
- [請求先アカウント] タブに、Cloud 請求先アカウントの名前と ID のリストが表示されます。予算を管理するアカウントの [アカウント ID] の値を確認します。
費用の上限の予算に関する主なコンセプトと制限事項
利用額上限予算では、推定総費用を使用してアラートをトリガーし、利用額上限を適用します。利用額上限が解除されるまで、使用量と費用の発生がブロックされます。
利用額上限の予算フィールドの制限
予算に spendCap が設定されている場合、予算には厳格なフィールド制限が適用されます。Filters、BudgetAmount、ThresholdRule、NotificationsRule、OwnershipScope のフィールドレベルのコメントをご覧ください。
- billing-account-id: 費用上限予算は、ファーストパーティのGoogle Cloud ユーザーと Cloud 請求先アカウントに限定されます。販売パートナーの請求先アカウントは対象外です。
BudgetFiltersには次のパラメータを含める必要があります。- 利用額上限の予算は、1 つの Google Cloud プロジェクトと1 つの対象サービスに範囲設定（フィルタリング）された予算に限定されます。
- 利用額上限の予算の予算期間の期間は、
MONTHのCalendarPeriodに制限されます。 - 利用額上限の費用計算は総費用に基づいており、割引やクレジットは含まれません。
creditTypesTreatmentをEXCLUDE_ALL_CREDITSに設定する必要があります。 resourceAncestors、credit_types、subaccounts、labelsなど、その他の予算フィルタは費用上限ではサポートされておらず、空にする必要があります。
BudgetAmountはspecifiedAmountを使用する必要があります。入力時、currencyCodeは省略可能です。予算の作成時に指定する場合、通貨コードは Cloud 請求先アカウントの通貨と一致している必要があります。currencyCodeは出力で提供されます。ThresholdRulesには、thresholdPercentの値が0.5、0.8、1.0（50%、80%、100%）の 3 つのルールが含まれている必要があります。また、spendBasisはCURRENT_SPENDまたはBASIS_UNSPECIFIEDに設定されている必要があります（FORECASTED_SPENDは費用上限ではサポートされていません）。NotificationsRuleはenableProjectLevelRecipientsをtrueに設定する必要があります。他のNotificationsRuleパラメータはすべてサポートされていません。OwnershipScopeはOWNERSHIP_SCOPE_UNSPECIFIEDまたはALL_USERSに設定する必要があります（BILLING_ACCOUNTは費用上限ではサポートされていません）。費用上限予算を作成する場合は、
inputStateパラメータをCONFIGUREDに設定する必要があります。
利用額上限の予算で費用を管理する仕組み
推定費用を使用した費用の迅速な計算: 利用額上限額を迅速に適用するために、利用額上限予算では、推定費用の総額を使用してアラートをトリガーし、利用額上限を適用します。推定費用はサービスの正規価格に基づいて計算され、割引やクレジットは含まれません。
利用額上限がトリガーされた場合の利用と費用の発生の自動一時停止: 指定したプロジェクトで、特定のサービスの推定総使用料金が予算目標額を超えると、利用額上限がトリガーされ、予算期間の残りの期間に適用されます。予算の
outputStateパラメータはENFORCEDに設定されています。費用上限が適用されている間は、次のようになります。- 指定されたプロジェクトの特定のサービスに対するすべての新しい使用量（オンデマンド、従量課金制の使用量、確約利用割引（CUD）やプロビジョンド スループット（PT）などのコミットメントでカバーされる使用量を含む）が一時停止されます。
- 指定されたサービスの 処理中のリクエストはすべて完了まで処理され、必要に応じて料金が発生します。
- 利用額上限を設定しても、永続リソース（コンピューティング サービスやストレージ サービスなど）に関連付けられた進行中の固定使用量は一時停止されません。これらのリソースはアクティブなままで、引き続き料金が発生します。
- 重要: 適用状態の予算では、費用上限の予算の設定を編集したり、予算を削除したりすることはできません。強制予算を編集または削除する前に、まず利用額上限を手動で解除する必要があります。
利用額上限を解除してサービスと費用の使用を復元する: 利用額上限が適用されると、利用額上限が解除されるまで、指定されたプロジェクト内の特定のサービスの使用がブロックされます。利用額上限は次の方法で引き上げることができます。
利用額上限を自動的に引き上げる: 設定された利用額上限は、次の予算期間の開始時（通常は翌月の 1 日）に自動的に引き上げられます。利用額上限が自動的に引き上げられると、予算の利用額がゼロにリセットされ、利用額上限の状態が
CONFIGUREDにリセットされ、指定されたサービスのブロックが解除され、API 呼び出しの通常の機能が復元されます。利用額上限を手動で解除する: 利用額上限が適用されている同じ予算期間中に使用制限を解除する必要がある場合は、予算を編集して利用額上限を手動で解除できます。利用額上限を手動で解除すると、次のようになります。
利用額上限が引き上げられてからサービスが完全に通常機能に戻るまでに最大 1 時間かかることがあります。
利用額上限予算の自動リセット: 次の予算期間の開始時（通常は翌月の 1 日）に、すべての利用額上限予算が自動的にリセットされ、総費用（推定値）が 0 に設定され、利用額上限の状態が
CONFIGUREDに設定されます。
割り当て上限: 個々の Cloud 請求先アカウントには、一度に数千件の予算を関連付けることができます。現在の上限と追加情報については、割り当てと上限をご覧ください。
API の呼び出し
次のサンプルは、Cloud Billing Budget API にリクエストを送信して費用上限予算を管理する方法を示しています。
費用の上限予算を作成する
この API メソッドは、単一のプロジェクトと対象サービスに適用される Cloud Billing 費用の上限予算を作成します。
REST
このサンプルでは、特定のプロジェクトで Gemini API サービスを使用するための上限額予算を作成する方法を示します。予算は、指定した単一の Google Cloud プロジェクトと単一の 対象サービスに スコープ設定（フィルタリング）され、 月単位の予算額が $100 に設定されます。
リクエストのデータを使用する前に、次のように置き換えます。
projects/budget-scope-project-id: 予算の範囲（budgetFilter）として設定する Google Cloud プロジェクト ID。services/eligible-service_id: 予算の範囲（budgetFilter）として設定する対象のサービス ID のいずれか。この例では、Gemini API サービスのサービス IDAEFD-7695-64FAを使用しています。- billing-account-id: この予算が適用される Cloud 請求先アカウント ID。費用の上限予算は、ファーストパーティの Google Cloud お客様と Cloud 請求先アカウントに限定されます。販売パートナーの請求先アカウントは対象外です。
- 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": "My Gemini API Spend Cap",
"budgetFilter": {
"projects": [
"projects/budget-scope-project-id"
],
"services": [
"services/AEFD-7695-64FA"
],
"creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
"calendarPeriod": "MONTH"
},
"amount": {
"specifiedAmount": {
"units": "100",
"nanos": 0
}
},
"thresholdRules": [
{ "thresholdPercent": 0.5 },
{ "thresholdPercent": 0.8 },
{ "thresholdPercent": 1.0 }
],
"notificationsRule": {
"enableProjectLevelRecipients": true
},
"spendCap": {
"inputState": "CONFIGURED"
}
}
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{
"name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
"displayName": "My Gemini API Spend Cap",
"budgetFilter": {
"projects": [
"projects/123456789"
],
"services": [
"services/AEFD-7695-64FA"
],
"creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
"calendarPeriod": "MONTH"
},
"amount": {
"specifiedAmount": {
"currencyCode": "USD",
"units": "100"
}
},
"thresholdRules": [
{
"thresholdPercent": 0.5,
"spendBasis": "CURRENT_SPEND"
},
{
"thresholdPercent": 0.8,
"spendBasis": "CURRENT_SPEND"
},
{
"thresholdPercent": 1,
"spendBasis": "CURRENT_SPEND"
}
],
"notificationsRule": {
"enableProjectLevelRecipients": true
},
"etag": "1790365289674138",
"spendCap": {
"outputState": "CONFIGURED"
}
}
PATCH を使用して費用の上限を引き上げる
PATCH API メソッドを使用して、既存の Cloud Billing 費用上限予算を変更し、適用された費用上限を手動で引き上げます。
REST
このサンプルは、
SpendCap.inputState パラメータを AWAITING_NEXT_PERIOD に更新して、既存の予算の ENFORCED 費用上限を手動で引き上げる方法を示しています。
重要: spend_cap.output_state が ENFORCED の場合、まず UpdateBudget リクエストを送信して spend_cap.input_state を変更し、費用上限を引き上げる必要があります（たとえば、input_state を AWAITING_NEXT_PERIOD に設定すると、上限が引き上げられます）。予算が適用状態のときに他の予算フィールドを変更しようとすると、更新リクエストは FAILED_PRECONDITION で失敗します。
このメソッドを呼び出すには、更新する予算の budget-id が必要です。予算 ID は、予算の作成時に createBudget の出力から取得できます。また、すべての予算のリストを表示した場合は、listBudgets の出力から取得できます。
リクエストのデータを使用する前に、次のように置き換えます。
- billing-account-id: この予算が適用される Cloud 請求先アカウント ID。費用の上限予算は、ファーストパーティの Google Cloud お客様と Cloud 請求先アカウントに限定されます。販売パートナーの請求先アカウントは対象外です。
- 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?updateMask=spendCap.inputState
リクエストの本文（JSON）:
{
"spendCap": {
"inputState": "AWAITING_NEXT_PERIOD"
}
}
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{
"name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
"displayName": "My Gemini API Spend Cap",
"budgetFilter": {
"projects": [
"projects/123456789"
],
"services": [
"services/AEFD-7695-64FA"
],
"creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
"calendarPeriod": "MONTH"
},
"amount": {
"specifiedAmount": {
"currencyCode": "USD",
"units": "100"
}
},
"thresholdRules": [
{
"thresholdPercent": 0.5,
"spendBasis": "CURRENT_SPEND"
},
{
"thresholdPercent": 0.8,
"spendBasis": "CURRENT_SPEND"
},
{
"thresholdPercent": 1,
"spendBasis": "CURRENT_SPEND"
}
],
"notificationsRule": {
"enableProjectLevelRecipients": true
},
"etag": "1790365289674138",
"spendCap": {
"outputState": "AWAITING_NEXT_PERIOD",
"reconciling": true
}
}
PATCH を使用して費用上限予算を更新する
この API メソッドを使用して、既存の Cloud Billing 費用の上限予算を変更し、予算額と予算フィルタ（予算の範囲）を変更します。
REST
このサンプルは、既存の費用上限予算を更新して
予算額を変更する方法を示しています。
費用の上限の状態が AWAITING_NEXT_PERIOD の場合、このサンプルでは、
SpendCap.inputState パラメータを CONFIGURED に更新して、引き上げられた費用の上限をリセットする方法も示しています。
このメソッドを呼び出すには、更新する予算の budget-id が必要です。予算 ID は、予算の作成時に createBudget の出力から取得できます。また、すべての予算のリストを表示した場合は、listBudgets の出力から取得できます。
リクエストのデータを使用する前に、次のように置き換えます。
projects/budget-scope-project-id: 予算の範囲（budgetFilter）として設定する Google Cloud プロジェクト ID。services/eligible-service_id: 予算の範囲（budgetFilter）として設定する対象のサービス ID のいずれか。この例では、Gemini API サービスのサービス IDAEFD-7695-64FAを使用しています。- billing-account-id: この予算が適用される Cloud 請求先アカウント ID。費用の上限予算は、ファーストパーティの Google Cloud お客様と Cloud 請求先アカウントに限定されます。販売パートナーの請求先アカウントは対象外です。
- 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?updateMask=amount.specifiedAmount,spendCap.inputState
リクエストの本文（JSON）:
{
"displayName": "My Gemini API Spend Cap",
"budgetFilter": {
"projects": [
"projects/budget-scope-project-id"
],
"services": [
"services/AEFD-7695-64FA"
],
"creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
"calendarPeriod": "MONTH"
},
"amount": {
"specifiedAmount": {
"units": "500",
"nanos": 0
}
},
"thresholdRules": [
{ "thresholdPercent": 0.5 },
{ "thresholdPercent": 0.8 },
{ "thresholdPercent": 1.0 }
],
"notificationsRule": {
"enableProjectLevelRecipients": true
},
"spendCap": {
"inputState": "CONFIGURED"
}
}
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{
"name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
"displayName": "My Gemini API Spend Cap",
"budgetFilter": {
"projects": [
"projects/123456789"
],
"services": [
"services/AEFD-7695-64FA"
],
"creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
"calendarPeriod": "MONTH"
},
"amount": {
"specifiedAmount": {
"currencyCode": "USD",
"units": "500"
}
},
"thresholdRules": [
{
"thresholdPercent": 0.5,
"spendBasis": "CURRENT_SPEND"
},
{
"thresholdPercent": 0.8,
"spendBasis": "CURRENT_SPEND"
},
{
"thresholdPercent": 1,
"spendBasis": "CURRENT_SPEND"
}
],
"notificationsRule": {
"enableProjectLevelRecipients": true
},
"etag": "1790365289674138",
"spendCap": {
"outputState": "CONFIGURED"
}
}
予算の一覧表示
この API メソッドは、特定の Cloud 請求先アカウントで使用できるすべての予算を表示します。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- billing-account-id: 予算が適用される Cloud 請求先アカウント ID。費用の上限予算は、ファーストパーティの Google Cloud お客様と Cloud 請求先アカウントに限定されます。販売パートナーの請求先アカウントは対象外です。
- project-id: Cloud Billing Budget API が有効になっている Google Cloud プロジェクト。
HTTP メソッドと URL:
GET https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{
"budgets": [
{
"name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
"displayName": "Gemini API Spend Cap in My Project",
"budgetFilter": {
"projects": [
"projects/987654321"
],
"services": [
"services/AEFD-7695-64FA"
],
"creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
"calendarPeriod": "MONTH"
},
"amount": {
"specifiedAmount": {
"currencyCode": "USD",
"units": "500"
}
},
"thresholdRules": [
{
"thresholdPercent": 0.5,
"spendBasis": "CURRENT_SPEND"
},
{
"thresholdPercent": 0.8,
"spendBasis": "CURRENT_SPEND"
},
{
"thresholdPercent": 1,
"spendBasis": "CURRENT_SPEND"
}
],
"notificationsRule": {
"enableProjectLevelRecipients": true
},
"allUpdatesRule": {},
"etag": "17fc365289f74138c",
"spendCap": {
"outputState": "ENFORCED"
}
}
]
}
予算の取得
この API メソッドは、特定の予算の詳細を取得します。
REST
このメソッドを呼び出すには、更新する予算の budget-id が必要です。予算 ID は、予算の作成時に createBudget の出力から取得できます。また、すべての予算のリストを表示した場合は、listBudgets の出力から取得できます。
リクエストのデータを使用する前に、次のように置き換えます。
- billing-account-id: この予算が適用される Cloud 請求先アカウント ID。費用の上限予算は、ファーストパーティの Google Cloud お客様と Cloud 請求先アカウントに限定されます。販売パートナーの請求先アカウントは対象外です。
- 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
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{
"name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
"displayName": "Cloud Run Spend Cap in My Project",
"budgetFilter": {
"projects": [
"projects/987654321"
],
"services": [
"services/152E-C115-5142"
],
"creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
"calendarPeriod": "MONTH"
},
"amount": {
"specifiedAmount": {
"currencyCode": "USD",
"units": "450"
}
},
"thresholdRules": [
{
"thresholdPercent": 0.5,
"spendBasis": "CURRENT_SPEND"
},
{
"thresholdPercent": 0.8,
"spendBasis": "CURRENT_SPEND"
},
{
"thresholdPercent": 1,
"spendBasis": "CURRENT_SPEND"
}
],
"notificationsRule": {
"enableProjectLevelRecipients": true
},
"allUpdatesRule": {},
"etag": "c9d6c011f6fa6b5c",
"spendCap": {
"outputState": "CONFIGURED"
}
}
予算を削除する
この API メソッドを使用して、既存の Cloud Billing 予算を削除します。
REST
このメソッドを呼び出すには、更新する予算の budget-id が必要です。予算 ID は、予算の作成時に createBudget の出力から取得できます。また、すべての予算のリストを表示した場合は、listBudgets の出力から取得できます。
リクエストのデータを使用する前に、次のように置き換えます。
- 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
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{}