Cloud Billing Budget API에 몇 가지 지출 한도 예산 요청을 보내는 방법을 알아봅니다.
전체 메서드 목록은 REST API 참고 문서를 참고하세요.
시작하기 전에
이 가이드를 읽기 전에 다음을 수행해야 합니다.
- Cloud Billing Budget API 개요를 읽어보세요.
- Cloud Billing Budget API 기본 요건을 읽어보세요.
- 설정 단계 수행
Cloud Billing 계정 ID 확인
모든 Cloud Billing Budget API 호출에 대해 Cloud Billing 계정 ID가 필요합니다. 지출 한도 예산은 퍼스트 파티Google Cloud 고객 및 Cloud Billing 계정으로 제한됩니다. 리셀러 결제 계정은 범위에서 제외됩니다.
- Google Cloud 콘솔 결제 계정 관리 페이지로 이동합니다.
- 내 결제 계정 탭에서 이름 및 ID별로 Cloud Billing 계정 목록이 표시됩니다. 예산을 관리하는 계정의 계정 ID 값을 찾습니다.
주요 지출 한도 예산 개념 및 제한사항
지출 한도 예산은 총 예상 비용을 사용하여 알림을 트리거하고 지출 한도를 적용하므로 지출 한도가 해제될 때까지 사용이 차단되고 비용이 발생하지 않습니다.
지출 한도 예산 필드 제한사항
spendCap이 예산에 설정되면 엄격한 필드 제한이 예산에 적용됩니다. Filters, BudgetAmount, ThresholdRule, NotificationsRule, OwnershipScope의 필드 수준 주석을 참고하세요.
- billing-account-id: 지출 한도 예산은 퍼스트 파티Google Cloud 고객 및 Cloud Billing 계정으로 제한됩니다. 리셀러 결제 계정은 범위에서 제외됩니다.
BudgetFilters에는 다음 매개변수가 포함되어야 합니다.- 지출 한도 예산은 단일 Google Cloud 프로젝트와 단일요건을 충족하는 서비스로 범위가 지정 (필터링)된 예산으로 제한됩니다.
- 지출 한도 예산의 예산 기간 기간은
MONTH의CalendarPeriod로 제한됩니다. - 지출 한도의 비용 계산은 총비용을 기준으로 하며 절감액과 크레딧은 포함되지 않습니다.
creditTypesTreatment을EXCLUDE_ALL_CREDITS로 설정해야 합니다. resourceAncestors,credit_types,subaccounts,labels등 다른 예산 필터는 지출 한도에 지원되지 않으며 비워야 합니다.
BudgetAmount은specifiedAmount을 사용해야 합니다. 입력 시currencyCode은 선택사항입니다. 예산을 만들 때 지정된 경우 통화 코드는 Cloud Billing 계정의 통화와 일치해야 합니다.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일)이 시작될 때 자동으로 해제됩니다. 지출 한도가 자동으로 해제되면 예산의 지출 금액이 0으로 재설정되고 지출 한도 상태가
CONFIGURED로 재설정되며 지정된 서비스가 차단 해제되어 API 호출이 정상적으로 복원됩니다.지출 한도 수동 해제: 지출 한도가 적용되는 동일한 예산 기간에 사용 차단을 되돌려야 하는 경우 예산을 수정하여 지출 한도를 수동으로 해제할 수 있습니다. 지출 한도를 수동으로 해제하면 다음과 같은 결과가 발생합니다.
- 지출 한도를 수동으로 해제하면 API 호출이 정상적으로 작동합니다.
- 지출 한도 상태를
AWAITING_NEXT_PERIOD로 설정하여 지출 한도를 수동으로 해제하면 지출 한도 금액을 늘리고inputState를CONFIGURED로 설정하기 위해 나중에 예산을 수정하지 않는 한 예산 기간의 나머지 기간 동안 지출 한도가 다시 트리거되지 않습니다.
지출 한도가 해제된 후 서비스가 완전히 정상으로 돌아오기까지 최대 1시간이 걸릴 수 있습니다.
지출 한도 예산 자동 재설정: 다음 예산 기간 (일반적으로 다음 달 1일)이 시작되면 모든 지출 한도 예산이 자동으로 재설정되어 총 예상 지출 금액이 0으로 설정되고 지출 한도 상태가
CONFIGURED로 설정됩니다.
할당량 제한: 각 개별 Cloud Billing 계정은 한 번에 수천 개의 예산을 연결할 수 있습니다. 현재 한도와 추가 정보는 할당량 및 한도를 참조하세요.
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: 이 예산이 적용되는 Google Cloud 결제 계정 ID 지출 한도 예산은 퍼스트 파티 Google Cloud 고객 및 Cloud Billing 계정으로 제한됩니다. 리셀러 결제 계정은 범위에서 제외됩니다.
- 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인 경우 먼저 spend_cap.input_state를 수정하는 UpdateBudget 요청을 보내 지출 한도를 해제해야 합니다(예: input_state을 AWAITING_NEXT_PERIOD로 설정). 이렇게 하면 한도가 해제됩니다. 예산이 강제 적용 상태일 때 다른 예산 필드를 수정하려고 하면 업데이트 요청이 FAILED_PRECONDITION 오류와 함께 실패합니다.
이 메서드를 호출하려면 업데이트할 예산의 budget-id가 필요합니다. 예산을 만들 때는 createBudget 출력에서, 예산을 모두 나열할 때는 listBudgets 출력에서 예산 ID를 가져올 수 있습니다.
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- billing-account-id: 이 예산이 적용되는 Google Cloud 결제 계정 ID 지출 한도 예산은 퍼스트 파티 Google Cloud 고객 및 Cloud Billing 계정으로 제한됩니다. 리셀러 결제 계정은 범위에서 제외됩니다.
- 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가 필요합니다. 예산을 만들 때는 createBudget 출력에서, 예산을 모두 나열할 때는 listBudgets 출력에서 예산 ID를 가져올 수 있습니다.
요청 데이터를 사용하기 전에 다음을 바꿉니다.
projects/budget-scope-project-id: 예산 범위(budgetFilter)로 설정하려는 Google Cloud 프로젝트입니다.services/eligible-service_id: 예산 범위(budgetFilter)로 설정하려는 사용 가능한 서비스 ID 중 하나입니다. 샘플에서는 Gemini API 서비스에 서비스 IDAEFD-7695-64FA을 사용합니다.- billing-account-id: 이 예산이 적용되는 Google Cloud 결제 계정 ID 지출 한도 예산은 퍼스트 파티 Google Cloud 고객 및 Cloud Billing 계정으로 제한됩니다. 리셀러 결제 계정은 범위에서 제외됩니다.
- 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 Billing 계정에 설정된 모든 예산을 나열합니다.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- billing-account-id: 예산이 적용되는 Google Cloud 결제 계정 ID 지출 한도 예산은 퍼스트 파티 Google Cloud 고객 및 Cloud Billing 계정으로 제한됩니다. 리셀러 결제 계정은 범위에서 제외됩니다.
- 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가 필요합니다. 예산을 만들 때는 createBudget 출력에서, 예산을 모두 나열할 때는 listBudgets 출력에서 예산 ID를 가져올 수 있습니다.
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- billing-account-id: 이 예산이 적용되는 Google Cloud 결제 계정 ID 지출 한도 예산은 퍼스트 파티 Google Cloud 고객 및 Cloud Billing 계정으로 제한됩니다. 리셀러 결제 계정은 범위에서 제외됩니다.
- 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가 필요합니다. 예산을 만들 때는 createBudget 출력에서, 예산을 모두 나열할 때는 listBudgets 출력에서 예산 ID를 가져올 수 있습니다.
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- billing-account-id: 이 예산이 적용되는 Google 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 응답이 표시됩니다.
{}