0
# Budget Data Models
1

2
Core data structures for defining budgets, amounts, time periods, and filtering rules. These Protocol Buffer-based message classes represent the fundamental budget configuration and constraints.
3

4
## Capabilities
5

6
### Budget Class
7

8
The primary budget object representing a complete budget configuration with spending plans and notification rules.
9

10
```python { .api }
11
class Budget:
12
    """
13
    A budget is a plan that describes what you expect to spend on Cloud projects,
14
    plus the rules to execute as spend is tracked against that plan.
15

16
    Attributes:
17
        name (str): Output only. Resource name of the budget
18
            (billingAccounts/{billingAccountId}/budgets/{budgetId})
19
        display_name (str): User data for display name in UI
20
            (must be ≤ 60 characters)
21
        budget_filter (Filter): Optional. Filters that define which resources
22
            are used to compute actual spend against the budget amount
23
        amount (BudgetAmount): Required. Budgeted amount
24
        threshold_rules (List[ThresholdRule]): Optional. Rules that trigger
25
            alerts when spend exceeds specified percentages
26
        notifications_rule (NotificationsRule): Optional. Rules to apply to
27
            notifications sent based on budget spend (v1 only)
28
        etag (str): Optional. Etag to validate the budget's version when updating
29
    """
30
    name: str
31
    display_name: str  
32
    budget_filter: Filter
33
    amount: BudgetAmount
34
    threshold_rules: List[ThresholdRule]
35
    notifications_rule: NotificationsRule  # v1 only
36
    etag: str
37
```
38

39
### Budget Amount Configuration
40

41
Classes for configuring budget amounts, supporting both fixed amounts and dynamic amounts based on previous periods.
42

43
```python { .api }
44
class BudgetAmount:
45
    """
46
    The budgeted amount for each usage period.
47
    
48
    This is a union field - exactly one of the following must be set:
49
    - specified_amount: A specified amount to use as the budget
50
    - last_period_amount: Use the amount of last period as the budget
51
    """
52
    # Union field "budget_amount": exactly one of the following
53
    specified_amount: Money
54
    last_period_amount: LastPeriodAmount
55

56
class LastPeriodAmount:
57
    """
58
    Describes a budget amount that is based on the amount spent in the
59
    previous period (month, quarter, year, or custom period).
60
    
61
    This creates a dynamic budget that adjusts based on historical spending.
62
    """
63
    pass  # No additional fields - presence indicates using last period amount
64
```
65

66
### Filtering and Time Periods
67

68
Configuration for defining which resources and time periods are included in budget calculations.
69

70
```python { .api }
71
class Filter:
72
    """
73
    A filter for a budget, limiting the scope of the cost to calculate.
74

75
    Attributes:
76
        projects (List[str]): Optional. Set of projects in the form
77
            projects/{project}, specifying that usage from only these
78
            projects should be included in the budget
79
        resource_ancestors (List[str]): Optional. Set of folders and
80
            organizations, specifying that usage from these containers
81
            should be included in the budget
82
        credit_types_treatment (CreditTypesTreatment): Optional. How to treat
83
            credits in budget calculations  
84
        credit_types (List[str]): Optional. Set of credit type display names
85
            to include in the budget. If credit_types_treatment is 
86
            INCLUDE_SPECIFIED_CREDITS, this field is required
87
        services (List[str]): Optional. Set of services to include in budget
88
        subaccounts (List[str]): Optional. Set of subaccounts to include
89
        labels (MutableMapping[str, struct_pb2.ListValue]): Optional. Set of key/value pairs
90
            for resource labels
91
        calendar_period (CalendarPeriod): Optional. Specifies a calendar period
92
        custom_period (CustomPeriod): Optional. Specifies a custom time period
93
    """
94
    projects: List[str]
95
    resource_ancestors: List[str] 
96
    credit_types_treatment: CreditTypesTreatment
97
    credit_types: List[str]
98
    services: List[str]
99
    subaccounts: List[str]
100
    labels: MutableMapping[str, struct_pb2.ListValue]
101
    calendar_period: CalendarPeriod
102
    custom_period: CustomPeriod
103

104
    class CreditTypesTreatment(Enum):
105
        """How to treat credits in budget calculations."""
106
        CREDIT_TYPES_TREATMENT_UNSPECIFIED = 0
107
        INCLUDE_ALL_CREDITS = 1  # Include all credit types
108
        EXCLUDE_ALL_CREDITS = 2  # Exclude all credit types
109
        INCLUDE_SPECIFIED_CREDITS = 3  # Include only specified credits
110

111
class CustomPeriod:
112
    """
113
    All date times begin at midnight UTC and end at the specified end date.
114

115
    Attributes:
116
        start_date (Date): Required. Start date of the budget period
117
        end_date (Date): Optional. End date of the budget period
118
    """
119
    start_date: Date
120
    end_date: Date
121

122
class CalendarPeriod(Enum):
123
    """
124
    A CalendarPeriod represents the abstract concept of a time period 
125
    that has a canonical start.
126

127
    Values:
128
        CALENDAR_PERIOD_UNSPECIFIED (0): Calendar period is unset
129
        MONTH (1): A month, starting on the first day of each month
130
        QUARTER (2): A quarter, starting on January 1, April 1, July 1, October 1
131
        YEAR (3): A year, starting on January 1
132
    """
133
    CALENDAR_PERIOD_UNSPECIFIED = 0
134
    MONTH = 1
135
    QUARTER = 2  
136
    YEAR = 3
137
```
138

139
### Threshold and Alert Rules
140

141
Configuration for spending thresholds that trigger notifications and alerts.
142

143
```python { .api }
144
class ThresholdRule:
145
    """
146
    ThresholdRule contains a definition of a threshold for a budget.
147

148
    Attributes:
149
        threshold_percent (float): Required. The percentage of the budget to
150
            be spent. Value must be between 0.0 and 1.0
151
        spend_basis (Basis): Optional. Type of basis used to calculate
152
            threshold spend
153
    """
154
    threshold_percent: float  # Non-negative number (0.5 = 50%)
155
    spend_basis: Basis
156

157
    class Basis(Enum):
158
        """The type of basis used to calculate threshold spend."""
159
        BASIS_UNSPECIFIED = 0
160
        CURRENT_SPEND = 1  # Use current spend as basis for comparison
161
        FORECASTED_SPEND = 2  # Use forecasted spend (only with calendar periods)
162
```
163

164
## Common Types
165

166
Additional types used throughout the budget system. These are imported from Google's Protocol Buffer libraries:
167

168
```python { .api }
169
# Import these types from Google's protobuf libraries:
170
from google.type import money_pb2, date_pb2
171
from google.protobuf import field_mask_pb2, struct_pb2
172
from typing import MutableMapping, MutableSequence
173

174
class Money:  # From google.type.money_pb2
175
    """
176
    Represents an amount of money with its currency type.
177

178
    Attributes:
179
        currency_code (str): The three-letter currency code defined in ISO 4217
180
        units (int): The whole units of the amount
181
        nanos (int): Number of nano (10^-9) units of the amount
182
    """
183
    currency_code: str  # e.g., "USD", "EUR"
184
    units: int
185
    nanos: int
186

187
class Date:  # From google.type.date_pb2
188
    """
189
    Represents a whole or partial calendar date.
190

191
    Attributes:
192
        year (int): Year of the date (1-9999, or 0 for unknown)
193
        month (int): Month of the year (1-12, or 0 for unknown)
194
        day (int): Day of the month (1-31, or 0 for unknown)
195
    """
196
    year: int
197
    month: int
198
    day: int
199

200
class FieldMask:  # From google.protobuf.field_mask_pb2
201
    """
202
    A field mask to specify the fields to be updated.
203

204
    Attributes:
205
        paths (List[str]): The set of field mask paths
206
    """
207
    paths: List[str]
208
```
209

210
## Usage Examples
211

212
### Creating a Basic Budget
213

214
```python
215
from google.cloud.billing import budgets
216
from google.type import money_pb2, date_pb2
217

218
# Create a monthly budget for $1000
219
budget = budgets.Budget(
220
    display_name="Monthly Project Budget",
221
    amount=budgets.BudgetAmount(
222
        specified_amount=money_pb2.Money(
223
            currency_code="USD",
224
            units=1000,
225
            nanos=0
226
        )
227
    ),
228
    budget_filter=budgets.Filter(
229
        projects=["projects/my-project-id"],
230
        calendar_period=budgets.CalendarPeriod.MONTH,
231
        credit_types_treatment=budgets.Filter.CreditTypesTreatment.EXCLUDE_ALL_CREDITS
232
    ),
233
    threshold_rules=[
234
        budgets.ThresholdRule(
235
            threshold_percent=0.8,  # 80%
236
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
237
        ),
238
        budgets.ThresholdRule(
239
            threshold_percent=1.0,  # 100%
240
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
241
        )
242
    ]
243
)
244
```
245

246
### Creating a Budget with Custom Period
247

248
```python
249
from google.cloud.billing import budgets
250
from google.type import date_pb2, money_pb2
251
from google.protobuf import struct_pb2
252

253
# Create a budget for a specific quarter
254
budget = budgets.Budget(
255
    display_name="Q1 2024 Budget",
256
    amount=budgets.BudgetAmount(
257
        specified_amount=money_pb2.Money(
258
            currency_code="USD",
259
            units=5000
260
        )
261
    ),
262
    budget_filter=budgets.Filter(
263
        projects=["projects/project-1", "projects/project-2"],
264
        custom_period=budgets.CustomPeriod(
265
            start_date=date_pb2.Date(year=2024, month=1, day=1),
266
            end_date=date_pb2.Date(year=2024, month=3, day=31)
267
        ),
268
        services=["services/compute.googleapis.com"],
269
        labels={
270
            "environment": struct_pb2.ListValue(values=[
271
                struct_pb2.Value(string_value="production"),
272
                struct_pb2.Value(string_value="staging")
273
            ]),
274
            "team": struct_pb2.ListValue(values=[
275
                struct_pb2.Value(string_value="backend")
276
            ])
277
        }
278
    ),
279
    threshold_rules=[
280
        budgets.ThresholdRule(
281
            threshold_percent=0.5,  # 50%
282
            spend_basis=budgets.ThresholdRule.Basis.FORECASTED_SPEND
283
        )
284
    ]
285
)
286
```
287

288
### Creating a Budget Based on Last Period
289

290
```python
291
from google.cloud.billing import budgets
292

293
# Create a budget that uses last month's spend as the budget amount
294
budget = budgets.Budget(
295
    display_name="Dynamic Monthly Budget",
296
    amount=budgets.BudgetAmount(
297
        last_period_amount=budgets.LastPeriodAmount()
298
    ),
299
    budget_filter=budgets.Filter(
300
        resource_ancestors=["organizations/123456789"],
301
        calendar_period=budgets.CalendarPeriod.MONTH,
302
        credit_types_treatment=budgets.Filter.CreditTypesTreatment.INCLUDE_ALL_CREDITS
303
    ),
304
    threshold_rules=[
305
        budgets.ThresholdRule(
306
            threshold_percent=0.9,  # 90%
307
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
308
        )
309
    ]
310
)
311
```
312

313
### Updating a Budget with Field Mask
314

315
```python
316
from google.cloud.billing import budgets
317
from google.protobuf import field_mask_pb2
318

319
# Update only the display name and threshold rules
320
budget.display_name = "Updated Budget Name"
321
budget.threshold_rules = [
322
    budgets.ThresholdRule(
323
        threshold_percent=0.75,  # 75%
324
        spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
325
    )
326
]
327

328
# Create field mask to specify which fields to update
329
update_mask = field_mask_pb2.FieldMask(
330
    paths=["display_name", "threshold_rules"]
331
)
332

333
# Update the budget
334
client = budgets.BudgetServiceClient()
335
updated_budget = client.update_budget(
336
    budget=budget,
337
    update_mask=update_mask
338
)
339
```