此页面由 Cloud Translation API 翻译。

使用 Cloud Billing Budget API

了解如何向 Cloud Billing Budget API 发送一些简单的请求。

如需查看完整的方法列表，请参阅 REST API 或 RPC API 参考文档。

准备工作

在阅读本指南之前，请先完成以下事项：

识别您的 Cloud Billing 账号 ID

对于每个 Cloud Billing Budget API 调用，您需要有 Cloud Billing 账号 ID。

转到 Google Cloud 控制台“管理结算账号”页面。
在“我的结算账号”标签页中，按名称和 ID 显示 Cloud Billing 账号列表。找到要用于管理预算的账号的结算账号 ID。

“管理结算”页的屏幕截图，其中显示了结算账号 ID 的位置。

主要预算概念

您可以将预算应用于整个结算账号，也可以使用精细预算过滤条件进行范围限制（过滤）以监控特定费用切片。
应用于整个 Cloud Billing 账号的预算包括使用该结算账号支付的所有 Google Cloud 项目的费用。
如果您对 Cloud Billing 账号的访问权限有限或没有访问权限，则可以为您拥有的项目创建单项目预算。如果您是 Cloud Billing 账号级用户，则可以使用预算中的 OwnershipScope 字段来创建项目级用户无法修改的单项目预算。
您可以使用过滤条件缩小预算的范围，例如组织、文件夹、项目、服务以及适用于 Cloud Billing 账号的其他预算过滤条件的子集。
您可以指定预算的时间段。默认情况下，预算会监控一个日历月内产生的费用。使用 Cloud Billing Budget API 中提供的 usage_period 过滤条件，您可以将预算时间段配置为 CalendarPeriod 或 CustomPeriod，从而允许您创建预算以监控超出默认日历月的时间范围，例如季度、一年，或您指定的自定义日期范围。
您可以将预算金额设为您指定的总额，也可以根据上一个日历时间段的支出确定预算金额。
您可以设置用来触发电子邮件提醒通知的预算阈值规则。当您的费用（实际费用或预测费用）超过预算的一定百分比（基于您设置的规则）时，系统会向您指定的收件人发送提醒电子邮件。
您可以设置预算的通知规则，以便为预算提醒指定电子邮件收件人，以及启用使用 Pub/Sub 发送程序化通知。
您可以使用 Pub/Sub 主题发送程序化通知（例如，将预算消息转发给其他媒介 [例如 Slack] 或自动执行费用管理任务）。

配额限制：每个 Cloud Billing 账号一次最多可以关联数千个预算。如需了解当前限制和其他信息，请参阅配额和限制。

调用 API

以下示例展示了如何向 Cloud Billing Budget API 发送一些简单的请求。

列出预算

此 API 方法会列出可用于特定 Cloud Billing 账号的所有预算。

REST

在使用任何请求数据之前，请先进行以下替换：

billing-account-id：预算适用的 Cloud Billing 账号 ID。
project-id：已启用 Cloud Billing Budget API 的 Google Cloud 项目。

HTTP 方法和网址：

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。您可以在创建预算时从 createBudget 输出获取预算 ID；如果列出所有预算，则可以从 listBudgets 输出获取预算 ID。

在使用任何请求数据之前，请先进行以下替换：

billing-account-id：此预算适用的 Cloud Billing 账号 ID。
budget-id：您要获得的预算的 ID。
project-id：已启用 Cloud Billing Budget API 的 Google Cloud 项目。

HTTP 方法和网址：

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)

注意：以下命令假定您已使用您的用户账号通过运行 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/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 Billing 账号的 Cloud Billing 预算。

REST

此示例展示了如何为给定的 Cloud Billing 账号创建预算以便根据您指定的 Google Cloud 项目进行范围限制（过滤），以及如何在某个季度的日历时间段设置该预算。

在使用任何请求数据之前，请先进行以下替换：

projects/budget-scope-project-id：您要设置为预算范围 (budgetFilter) 的 Google Cloud 项目 ID。
billing-account-id：此预算适用的 Cloud Billing 账号 ID。
api-user-project-id：已启用 Cloud Billing Budget API 的 Google Cloud 项目。

HTTP 方法和网址：

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)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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 Billing 账号 ID。
budget-id：要更新的预算的 ID。
api-user-project-id：已启用 Cloud Billing Budget API 的 Google Cloud 项目。

HTTP 方法和网址：

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)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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 Billing 账号 ID。
budget-id：要删除的预算的 ID。
project-id：已启用 Cloud Billing Budget API 的 Google Cloud 项目。

HTTP 方法和网址：

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)

注意：以下命令假定您已使用您的用户账号通过运行 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 DELETE `
    -Headers $headers `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{}

设置