0
# Request and Response Types
1

2
API request and response message types for all budget operations, including specialized pagination response handling and field mask support for partial updates.
3

4
## Capabilities
5

6
### Budget Creation
7

8
Request and response types for creating new budgets.
9

10
```python { .api }
11
class CreateBudgetRequest:
12
    """
13
    Request message for creating a budget.
14

15
    Attributes:
16
        parent (str): Required. Name of the billing account to create budget in.
17
            Format: billingAccounts/{billingAccountId}
18
        budget (Budget): Required. Budget to create
19
    """
20
    parent: str  # Format: billingAccounts/{billingAccountId}
21
    budget: Budget
22

23
# Response: Budget object (the created budget)
24
```
25

26
### Budget Retrieval
27

28
Request type for retrieving a specific budget by name.
29

30
```python { .api }
31
class GetBudgetRequest:
32
    """
33
    Request message for getting a budget.
34

35
    Attributes:
36
        name (str): Required. Name of budget to retrieve.
37
            Format: billingAccounts/{billingAccountId}/budgets/{budgetId}
38
    """
39
    name: str  # Format: billingAccounts/{billingAccountId}/budgets/{budgetId}
40

41
# Response: Budget object
42
```
43

44
### Budget Updates
45

46
Request type for updating existing budgets with optional field masking for partial updates.
47

48
```python { .api }
49
class UpdateBudgetRequest:
50
    """
51
    Request message for updating a budget.
52

53
    Attributes:
54
        budget (Budget): Required. The updated budget object. Must contain
55
            a valid name field for identifying the budget to update
56
        update_mask (FieldMask): Optional. Indicates which budget fields
57
            should be updated. If not provided, all fields will be updated
58
    """
59
    budget: Budget
60
    update_mask: FieldMask
61

62
# Response: Budget object (the updated budget)
63
```
64

65
### Budget Deletion
66

67
Request type for deleting budgets.
68

69
```python { .api }
70
class DeleteBudgetRequest:
71
    """
72
    Request message for deleting a budget.
73

74
    Attributes:
75
        name (str): Required. Name of the budget to delete.
76
            Format: billingAccounts/{billingAccountId}/budgets/{budgetId}
77
    """
78
    name: str  # Format: billingAccounts/{billingAccountId}/budgets/{budgetId}
79

80
# Response: Empty (no content returned on successful deletion)
81
```
82

83
### Budget Listing
84

85
Request and response types for listing budgets with pagination support and optional project scoping.
86

87
```python { .api }
88
class ListBudgetsRequest:
89
    """
90
    Request message for listing budgets.
91

92
    Attributes:
93
        parent (str): Required. Name of billing account to list budgets for.
94
            Format: billingAccounts/{billingAccountId}
95
        scope (str): Optional. Set to projects/{projectId} to list budgets
96
            that are scoped to a specific project
97
        page_size (int): Optional. Requested page size. Maximum value is 100.
98
            If not specified, returns at most 50 budgets
99
        page_token (str): Optional. Page token for pagination. Pass the
100
            next_page_token from previous response to get next page
101
    """
102
    parent: str  # Format: billingAccounts/{billingAccountId}
103
    scope: str   # Optional: projects/{projectId}
104
    page_size: int  # Max 100, default ~50
105
    page_token: str
106

107
class ListBudgetsResponse:
108
    """
109
    Response message for listing budgets.
110

111
    Attributes:
112
        budgets (List[Budget]): List of budgets owned by the specified
113
            billing account
114
        next_page_token (str): Token to retrieve the next page of results.
115
            Empty if no more results exist
116
    """
117
    budgets: List[Budget]
118
    next_page_token: str
119

120
    @property
121
    def raw_page(self) -> ListBudgetsResponse:
122
        """
123
        Returns the raw page response (self).
124
        Required for pager compatibility.
125
        """
126
        return self
127
```
128

129
## Common Types
130

131
Supporting types used in request and response messages.
132

133
```python { .api }
134
class FieldMask:
135
    """
136
    A field mask to specify which fields should be updated.
137

138
    Attributes:
139
        paths (List[str]): The set of field mask paths. Examples:
140
            - ["display_name"] - Update only display name
141
            - ["amount", "threshold_rules"] - Update amount and thresholds
142
            - ["budget_filter.projects"] - Update only filter projects
143
    """
144
    paths: List[str]
145
```
146

147
## Usage Examples
148

149
### Creating a Budget
150

151
```python
152
from google.cloud.billing import budgets
153

154
# Create request object
155
request = budgets.CreateBudgetRequest(
156
    parent="billingAccounts/123456-ABCDEF-789012",
157
    budget=budgets.Budget(
158
        display_name="Development Budget",
159
        amount=budgets.BudgetAmount(
160
            specified_amount={"currency_code": "USD", "units": 500}
161
        ),
162
        budget_filter=budgets.Filter(
163
            projects=["projects/dev-project"],
164
            calendar_period=budgets.CalendarPeriod.MONTH
165
        ),
166
        threshold_rules=[
167
            budgets.ThresholdRule(
168
                threshold_percent=0.8,
169
                spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
170
            )
171
        ]
172
    )
173
)
174

175
# Send request
176
client = budgets.BudgetServiceClient()
177
created_budget = client.create_budget(request=request)
178

179
# Or use keyword arguments directly
180
created_budget = client.create_budget(
181
    parent="billingAccounts/123456-ABCDEF-789012",
182
    budget=budget
183
)
184
```
185

186
### Retrieving a Budget
187

188
```python
189
from google.cloud.billing import budgets
190

191
# Create request object
192
request = budgets.GetBudgetRequest(
193
    name="billingAccounts/123456-ABCDEF-789012/budgets/budget-id-123"
194
)
195

196
# Send request
197
client = budgets.BudgetServiceClient()
198
budget = client.get_budget(request=request)
199

200
# Or use keyword arguments
201
budget = client.get_budget(
202
    name="billingAccounts/123456-ABCDEF-789012/budgets/budget-id-123"
203
)
204
```
205

206
### Partial Budget Update
207

208
```python
209
from google.cloud.billing import budgets
210
from google.protobuf import field_mask_pb2
211

212
# Get existing budget first
213
client = budgets.BudgetServiceClient()
214
budget_name = "billingAccounts/123456-ABCDEF-789012/budgets/budget-id-123"
215
existing_budget = client.get_budget(name=budget_name)
216

217
# Modify only specific fields
218
existing_budget.display_name = "Updated Budget Name"
219
existing_budget.threshold_rules = [
220
    budgets.ThresholdRule(
221
        threshold_percent=0.75,  # Changed from 0.8 to 0.75
222
        spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
223
    )
224
]
225

226
# Create field mask to specify which fields to update
227
update_mask = field_mask_pb2.FieldMask(
228
    paths=["display_name", "threshold_rules"]
229
)
230

231
# Create update request
232
request = budgets.UpdateBudgetRequest(
233
    budget=existing_budget,
234
    update_mask=update_mask
235
)
236

237
# Send request
238
updated_budget = client.update_budget(request=request)
239

240
# Or use keyword arguments
241
updated_budget = client.update_budget(
242
    budget=existing_budget,
243
    update_mask=update_mask
244
)
245
```
246

247
### Listing Budgets with Pagination
248

249
```python
250
from google.cloud.billing import budgets
251

252
# List all budgets for a billing account
253
request = budgets.ListBudgetsRequest(
254
    parent="billingAccounts/123456-ABCDEF-789012",
255
    page_size=10  # Get 10 budgets per page
256
)
257

258
client = budgets.BudgetServiceClient()
259
response = client.list_budgets(request=request)
260

261
# Process first page
262
for budget in response.budgets:
263
    print(f"Budget: {budget.display_name}")
264

265
# Get next page if available
266
if response.next_page_token:
267
    next_request = budgets.ListBudgetsRequest(
268
        parent="billingAccounts/123456-ABCDEF-789012",
269
        page_size=10,
270
        page_token=response.next_page_token
271
    )
272
    next_response = client.list_budgets(request=next_request)
273

274
# Or use the pager (recommended)
275
pager = client.list_budgets(
276
    parent="billingAccounts/123456-ABCDEF-789012"
277
)
278

279
# Iterate through all budgets automatically
280
for budget in pager:
281
    print(f"Budget: {budget.display_name}")
282
```
283

284
### Project-Scoped Budget Listing
285

286
```python
287
from google.cloud.billing import budgets
288

289
# List budgets scoped to a specific project
290
request = budgets.ListBudgetsRequest(
291
    parent="billingAccounts/123456-ABCDEF-789012",
292
    scope="projects/my-specific-project"
293
)
294

295
client = budgets.BudgetServiceClient()
296
response = client.list_budgets(request=request)
297

298
print(f"Found {len(response.budgets)} budgets for the project")
299
for budget in response.budgets:
300
    print(f"Project Budget: {budget.display_name}")
301
```
302

303
### Deleting a Budget
304

305
```python
306
from google.cloud.billing import budgets
307

308
# Create delete request
309
request = budgets.DeleteBudgetRequest(
310
    name="billingAccounts/123456-ABCDEF-789012/budgets/budget-id-123"
311
)
312

313
# Send request (no response content on success)
314
client = budgets.BudgetServiceClient()
315
client.delete_budget(request=request)
316

317
# Or use keyword arguments
318
client.delete_budget(
319
    name="billingAccounts/123456-ABCDEF-789012/budgets/budget-id-123"
320
)
321

322
print("Budget deleted successfully")
323
```
324

325
### Batch Operations Example
326

327
```python
328
from google.cloud.billing import budgets
329

330
client = budgets.BudgetServiceClient()
331
parent = "billingAccounts/123456-ABCDEF-789012"
332

333
# Create multiple budgets
334
budgets_to_create = [
335
    budgets.Budget(
336
        display_name=f"Project {i} Budget",
337
        amount=budgets.BudgetAmount(
338
            specified_amount={"currency_code": "USD", "units": 1000 * (i + 1)}
339
        ),
340
        budget_filter=budgets.Filter(
341
            projects=[f"projects/project-{i}"],
342
            calendar_period=budgets.CalendarPeriod.MONTH
343
        )
344
    )
345
    for i in range(3)
346
]
347

348
created_budgets = []
349
for budget in budgets_to_create:
350
    created_budget = client.create_budget(parent=parent, budget=budget)
351
    created_budgets.append(created_budget)
352
    print(f"Created: {created_budget.name}")
353

354
# List all budgets to verify
355
pager = client.list_budgets(parent=parent)
356
all_budgets = list(pager)
357
print(f"Total budgets: {len(all_budgets)}")
358

359
# Clean up - delete created budgets
360
for budget in created_budgets:
361
    client.delete_budget(name=budget.name)
362
    print(f"Deleted: {budget.name}")
363
```
364

365
## Error Handling
366

367
Common error scenarios and their handling:
368

369
```python
370
from google.cloud.billing import budgets
371
from google.api_core import exceptions
372

373
client = budgets.BudgetServiceClient()
374

375
try:
376
    # Attempt to get a non-existent budget
377
    budget = client.get_budget(
378
        name="billingAccounts/123456/budgets/non-existent"
379
    )
380
except exceptions.NotFound:
381
    print("Budget not found")
382
except exceptions.PermissionDenied:
383
    print("Insufficient permissions to access budget")
384
except exceptions.InvalidArgument as e:
385
    print(f"Invalid request: {e}")
386
except exceptions.GoogleAPICallError as e:
387
    print(f"API call failed: {e}")
388

389
try:
390
    # Attempt to create budget with invalid parent
391
    client.create_budget(
392
        parent="invalid-parent-format",
393
        budget=budgets.Budget(display_name="Test")
394
    )
395
except exceptions.InvalidArgument as e:
396
    print(f"Invalid parent format: {e}")
397
```