0
# Reservation Management
1

2
Access reservation summaries, details, recommendations, and transaction history for cost optimization through Azure Reserved Instances. This module provides comprehensive reservation analytics and recommendation capabilities.
3

4
## Capabilities
5

6
### Reservation Summaries
7

8
Get aggregated reservation usage and cost data for analysis and reporting.
9

10
```python { .api }
11
def list_by_reservation_order(
12
    reservation_order_id: str,
13
    grain: str,
14
    filter: str = None,
15
    **kwargs
16
) -> Iterable[ReservationSummariesListResult]:
17
    """
18
    List reservation summaries for a specific reservation order.
19
    
20
    Parameters:
21
    - reservation_order_id: The reservation order ID (str)
22
    - grain: Summary grain - "Daily" or "Monthly" (str)
23
    - filter: OData filter expression (str, optional)
24
    
25
    Returns:
26
    Iterable[ReservationSummariesListResult]: Reservation summaries collection
27
    """
28

29
def list_by_reservation_order_and_reservation(
30
    reservation_order_id: str,
31
    reservation_id: str,
32
    grain: str,
33
    filter: str = None,
34
    **kwargs
35
) -> Iterable[ReservationSummariesListResult]:
36
    """
37
    List reservation summaries for a specific reservation.
38
    
39
    Parameters:
40
    - reservation_order_id: The reservation order ID (str)
41
    - reservation_id: The specific reservation ID (str)
42
    - grain: Summary grain - "Daily" or "Monthly" (str)
43
    - filter: OData filter expression (str, optional)
44
    
45
    Returns:
46
    Iterable[ReservationSummariesListResult]: Reservation summaries collection
47
    """
48

49
def list(
50
    resource_scope: str,
51
    grain: str,
52
    start_date: str = None,
53
    end_date: str = None,
54
    filter: str = None,
55
    reservation_id: str = None,
56
    reservation_order_id: str = None,
57
    **kwargs
58
) -> Iterable[ReservationSummariesListResult]:
59
    """
60
    List reservation summaries for a defined scope.
61
    
62
    Parameters:
63
    - resource_scope: The scope for the reservation query (str)
64
    - grain: Summary grain - "Daily" or "Monthly" (str)
65
    - start_date: Start date for the query (str, optional)
66
    - end_date: End date for the query (str, optional)
67
    - filter: OData filter expression (str, optional)
68
    - reservation_id: Filter by specific reservation (str, optional)
69
    - reservation_order_id: Filter by reservation order (str, optional)
70
    
71
    Returns:
72
    Iterable[ReservationSummariesListResult]: Reservation summaries collection
73
    """
74
```
75

76
### Reservation Details
77

78
Access detailed reservation usage information for granular analysis.
79

80
```python { .api }
81
def list_by_reservation_order(
82
    reservation_order_id: str,
83
    filter: str,
84
    **kwargs
85
) -> Iterable[ReservationDetailsListResult]:
86
    """
87
    List detailed reservation usage for a reservation order.
88
    
89
    Parameters:
90
    - reservation_order_id: The reservation order ID (str)
91
    - filter: Required date range filter (str)
92
    
93
    Returns:
94
    Iterable[ReservationDetailsListResult]: Reservation details collection
95
    """
96

97
def list_by_reservation_order_and_reservation(
98
    reservation_order_id: str,
99
    reservation_id: str,
100
    filter: str,
101
    **kwargs
102
) -> Iterable[ReservationDetailsListResult]:
103
    """
104
    List detailed reservation usage for a specific reservation.
105
    
106
    Parameters:
107
    - reservation_order_id: The reservation order ID (str)
108
    - reservation_id: The specific reservation ID (str)
109
    - filter: Required date range filter (str)
110
    
111
    Returns:
112
    Iterable[ReservationDetailsListResult]: Reservation details collection
113
    """
114

115
def list(
116
    resource_scope: str,
117
    start_date: str = None,
118
    end_date: str = None,
119
    filter: str = None,
120
    reservation_id: str = None,
121
    reservation_order_id: str = None,
122
    **kwargs
123
) -> Iterable[ReservationDetailsListResult]:
124
    """
125
    List reservation details for a defined scope.
126
    
127
    Parameters:
128
    - resource_scope: The scope for the reservation query (str)
129
    - start_date: Start date for the query (str, optional)
130
    - end_date: End date for the query (str, optional)
131
    - filter: OData filter expression (str, optional)
132
    - reservation_id: Filter by specific reservation (str, optional)
133
    - reservation_order_id: Filter by reservation order (str, optional)
134
    
135
    Returns:
136
    Iterable[ReservationDetailsListResult]: Reservation details collection
137
    """
138
```
139

140
### Reservation Recommendations
141

142
Get recommendations for purchasing reserved instances to optimize costs.
143

144
```python { .api }
145
def list(resource_scope: str, filter: str = None, **kwargs) -> Iterable[ReservationRecommendationsListResult]:
146
    """
147
    List reservation recommendations for cost optimization.
148
    
149
    Parameters:
150
    - resource_scope: The scope for recommendations (str)
151
    - filter: Filter for resourceType, lookBackPeriod, etc. (str, optional)
152
    
153
    Returns:
154
    Iterable[ReservationRecommendationsListResult]: Reservation recommendations
155
    """
156
```
157

158
### Reservation Recommendation Details
159

160
Get detailed analysis for what-if scenarios on reservation recommendations.
161

162
```python { .api }
163
def get(
164
    resource_scope: str,
165
    scope: str,
166
    region: str,
167
    term: str,
168
    look_back_period: str,
169
    product: str,
170
    **kwargs
171
) -> Optional[ReservationRecommendationDetailsModel]:
172
    """
173
    Get detailed recommendation analysis for what-if scenarios.
174
    
175
    Parameters:
176
    - resource_scope: The scope for the recommendation (str)
177
    - scope: Recommendation scope - "Single" or "Shared" (str)
178
    - region: Azure region for the recommendation (str)
179
    - term: Reservation term - "P1Y" or "P3Y" (str)
180
    - look_back_period: Analysis period - "Last7Days", "Last30Days", "Last60Days" (str)
181
    - product: Product type for reservation (str)
182
    
183
    Returns:
184
    ReservationRecommendationDetailsModel: Detailed recommendation analysis
185
    """
186
```
187

188
### Reservation Transactions
189

190
Access reservation purchase and refund transaction history.
191

192
```python { .api }
193
def list(
194
    billing_account_id: str,
195
    filter: str = None,
196
    **kwargs
197
) -> Iterable[ReservationTransactionsListResult]:
198
    """
199
    List reservation transactions for a billing account.
200
    
201
    Parameters:
202
    - billing_account_id: The billing account ID (str)
203
    - filter: OData filter expression (str, optional)
204
    
205
    Returns:
206
    Iterable[ReservationTransactionsListResult]: Reservation transactions
207
    """
208

209
def list_by_billing_profile(
210
    billing_account_id: str,
211
    billing_profile_id: str,
212
    filter: str = None,
213
    **kwargs
214
) -> Iterable[ModernReservationTransactionsListResult]:
215
    """
216
    List reservation transactions for a billing profile.
217
    
218
    Parameters:
219
    - billing_account_id: The billing account ID (str)
220
    - billing_profile_id: The billing profile ID (str)
221
    - filter: OData filter expression (str, optional)
222
    
223
    Returns:
224
    Iterable[ModernReservationTransactionsListResult]: Modern reservation transactions
225
    """
226
```
227

228
**Usage Example:**
229

230
```python
231
# Get reservation summaries for subscription
232
scope = f"/subscriptions/{subscription_id}"
233
reservation_summaries = client.reservations_summaries.list(
234
    resource_scope=scope,
235
    grain="Monthly",
236
    start_date="2024-01-01",
237
    end_date="2024-12-31"
238
)
239

240
for summary in reservation_summaries:
241
    print(f"Reservation: {summary.reservation_id}")
242
    print(f"Used Hours: {summary.used_hours}")
243
    print(f"Reserved Hours: {summary.reserved_hours}")
244
    print(f"Utilization: {summary.utilization_percentage}%")
245

246
# Get reservation recommendations
247
recommendations = client.reservation_recommendations.list(
248
    resource_scope=scope,
249
    filter="properties/resourceType eq 'VirtualMachines' and properties/lookBackPeriod eq 'Last30Days'"
250
)
251

252
for recommendation in recommendations:
253
    print(f"Product: {recommendation.sku}")
254
    print(f"Recommended Quantity: {recommendation.recommended_quantity}")
255
    print(f"Annual Savings: ${recommendation.total_cost_with_reserved_instances}")
256

257
# Get detailed recommendation analysis
258
detail = client.reservation_recommendation_details.get(
259
    resource_scope=scope,
260
    scope="Single",
261
    region="westus2",
262
    term="P1Y",
263
    look_back_period="Last30Days",
264
    product="Standard_D2s_v3"
265
)
266

267
if detail:
268
    print(f"Expected Usage: {detail.usage.usage_data}")
269
    print(f"Cost with reservation: ${detail.cost.total_cost_with_reserved_instances}")
270
```
271

272
## Types
273

274
### Reservation Summary Models
275

276
```python { .api }
277
class ReservationSummary:
278
    """Reservation usage summary."""
279
    reservation_order_id: str
280
    reservation_id: str
281
    sku_name: str
282
    reserved_hours: float
283
    usage_date: datetime
284
    used_hours: float
285
    min_utilization_percentage: float
286
    avg_utilization_percentage: float
287
    max_utilization_percentage: float
288
    kind: str
289
```
290

291
### Reservation Detail Models
292

293
```python { .api }
294
class ReservationDetail:
295
    """Detailed reservation usage information."""
296
    reservation_order_id: str
297
    reservation_id: str
298
    sku_name: str
299
    reserved_hours: float
300
    usage_date: datetime
301
    used_hours: float
302
    instance_id: str
303
    total_reserved_quantity: float
304
    kind: str
305
```
306

307
### Reservation Recommendation Models
308

309
```python { .api }
310
class ReservationRecommendation:
311
    """Base reservation recommendation."""
312
    id: str
313
    name: str
314
    type: str
315
    location: str
316
    sku: str
317
    kind: str
318

319
class LegacyReservationRecommendation(ReservationRecommendation):
320
    """Legacy format reservation recommendation."""
321
    cost_with_no_reserved_instances: float
322
    recommended_quantity: float
323
    total_cost_with_reserved_instances: float
324
    net_savings: float
325
    first_usage_date: datetime
326
    scope: str
327
    look_back_period: str
328
    instance_flexibility_ratio: float
329
    instance_flexibility_group: str
330
    normalized_size: str
331
    recommended_quantity_normalized: float
332
    meter_id: str
333
    resource_type: str
334
    term: str
335

336
class ModernReservationRecommendation(ReservationRecommendation):
337
    """Modern format reservation recommendation."""
338
    properties: dict
339
```
340

341
### Reservation Transaction Models
342

343
```python { .api }
344
class ReservationTransaction:
345
    """Base reservation transaction."""
346
    id: str
347
    name: str
348
    type: str
349
    tags: dict
350

351
class LegacyReservationTransaction(ReservationTransaction):
352
    """Legacy reservation transaction format."""
353
    account_name: str
354
    account_owner_id: str
355
    subscription_id: str
356
    subscription_name: str
357
    reservation_order_id: str
358
    reservation_order_name: str
359
    purchase_date: datetime
360
    reservation_term: str
361
    quantity: float
362
    amount: float
363
    currency: str
364
    current_enrollment: str
365
    billing_frequency: str
366
    region: str
367
    description: str
368
    
369
class ModernReservationTransaction(ReservationTransaction):
370
    """Modern reservation transaction format."""
371
    properties: dict
372
```
373

374
### Recommendation Detail Models
375

376
```python { .api }
377
class ReservationRecommendationDetailsModel:
378
    """Detailed recommendation analysis."""
379
    id: str
380
    name: str
381
    type: str
382
    location: str
383
    sku: str
384
    currency: str
385
    resource: ReservationRecommendationDetailsResourceProperties
386
    resource_group: str
387
    savings: ReservationRecommendationDetailsSavingsProperties
388
    usage: ReservationRecommendationDetailsUsageProperties
389
    
390
class ReservationRecommendationDetailsResourceProperties:
391
    """Resource properties for recommendation."""
392
    applied_scopes: List[str]
393
    on_demand_rate: float
394
    product: str
395
    region: str
396
    resource_type: str
397
    term: str
398

399
class ReservationRecommendationDetailsSavingsProperties:
400
    """Savings analysis for recommendation."""
401
    calculated_savings: List[ReservationRecommendationDetailsCalculatedSavingsProperties]
402
    on_demand_cost: float
403
    overhead_cost: float
404
    quantity_used: float
405
    reservation_cost: float
406
    total_reservation_cost: float
407
    savings_percentage: float
408
    savings_ratio: float
409

410
class ReservationRecommendationDetailsUsageProperties:
411
    """Usage analysis for recommendation."""
412
    first_consumption_date: datetime
413
    last_consumption_date: datetime
414
    look_back_unit_type: str
415
    usage_data: List[float]
416
    usage_grain: str
417
```
418

419
### List Result Models
420

421
```python { .api }
422
class ReservationSummariesListResult:
423
    """Container for reservation summaries list."""
424
    value: List[ReservationSummary]
425
    next_link: str
426

427
class ReservationDetailsListResult:
428
    """Container for reservation details list."""
429
    value: List[ReservationDetail]
430
    next_link: str
431

432
class ReservationRecommendationsListResult:
433
    """Container for reservation recommendations list."""
434
    value: List[ReservationRecommendation]
435
    next_link: str
436

437
class ReservationTransactionsListResult:
438
    """Container for legacy reservation transactions list."""
439
    value: List[LegacyReservationTransaction]
440
    next_link: str
441

442
class ModernReservationTransactionsListResult:
443
    """Container for modern reservation transactions list."""
444
    value: List[ModernReservationTransaction]
445
    next_link: str
446
```
447

448
### Enumeration Types
449

450
```python { .api }
451
class Datagrain:
452
    """Data grain options for reservation summaries."""
453
    DAILY = "Daily"
454
    MONTHLY = "Monthly"
455

456
class Scope:
457
    """Reservation recommendation scope."""
458
    SINGLE = "Single"
459
    SHARED = "Shared"
460

461
class Term:
462
    """Reservation term options."""
463
    P1Y = "P1Y"  # 1 year
464
    P3Y = "P3Y"  # 3 years
465

466
class LookBackPeriod:
467
    """Look-back period for recommendations."""
468
    LAST_7_DAYS = "Last7Days"
469
    LAST_30_DAYS = "Last30Days"
470
    LAST_60_DAYS = "Last60Days"
471

472
class ReservationRecommendationKind:
473
    """Reservation recommendation format types."""
474
    LEGACY = "legacy"
475
    MODERN = "modern"
476
```