0
# Azure Batch
1

2
Microsoft Azure Batch Client Library for Python provides comprehensive APIs for managing batch computing workloads in Azure cloud. It enables developers to create, manage, and monitor batch pools (compute nodes), jobs (logical containers for tasks), and tasks (individual work items) with capabilities for resource allocation, job scheduling, task distribution, and monitoring.
3

4
## Package Information
5

6
- **Package Name**: azure-batch
7
- **Version**: 14.2.0
8
- **Language**: Python
9
- **Installation**: `pip install azure-batch`
10
- **Dependencies**: msrestazure (>=0.4.32,<2.0.0), azure-common (~=1.1)
11

12
## Core Imports
13

14
```python
15
from azure.batch import BatchServiceClient, BatchServiceClientConfiguration
16
from azure.batch.batch_auth import SharedKeyCredentials
17
```
18

19
Import specific operations:
20

21
```python
22
from azure.batch.operations import (
23
    PoolOperations, JobOperations, TaskOperations, 
24
    ComputeNodeOperations, ApplicationOperations,
25
    CertificateOperations, FileOperations, 
26
    JobScheduleOperations, AccountOperations,
27
    ComputeNodeExtensionOperations
28
)
29
```
30

31
Import model classes:
32

33
```python
34
from azure.batch.models import (
35
    CloudPool, CloudJob, CloudTask, PoolSpecification,
36
    JobSpecification, TaskSpecification, BatchError
37
)
38
```
39

40
## Basic Usage
41

42
```python
43
from azure.batch import BatchServiceClient
44
from azure.batch.batch_auth import SharedKeyCredentials
45

46
# Set up authentication
47
credentials = SharedKeyCredentials(
48
    account_name="your_batch_account",
49
    key="your_account_key"
50
)
51

52
# Create the Batch service client
53
batch_url = "https://your_batch_account.your_region.batch.azure.com"
54
client = BatchServiceClient(credentials, batch_url)
55

56
# List existing pools
57
pools = client.pool.list()
58
for pool in pools:
59
    print(f"Pool ID: {pool.id}, State: {pool.state}")
60

61
# Create a new pool
62
from azure.batch.models import PoolSpecification, CloudServiceConfiguration
63

64
pool_spec = PoolSpecification(
65
    id="my-pool",
66
    vm_size="Standard_A1",
67
    cloud_service_configuration=CloudServiceConfiguration(
68
        os_family="4",  # Windows Server 2012 R2
69
        target_os_version="*"
70
    ),
71
    target_dedicated_nodes=2,
72
    enable_auto_scale=False
73
)
74

75
client.pool.add(pool_spec)
76

77
# Create a job
78
from azure.batch.models import JobSpecification, PoolInformation
79

80
job_spec = JobSpecification(
81
    id="my-job",
82
    pool_info=PoolInformation(pool_id="my-pool")
83
)
84

85
client.job.add(job_spec)
86

87
# Add a task to the job  
88
from azure.batch.models import TaskSpecification
89

90
task_spec = TaskSpecification(
91
    id="my-task",
92
    command_line="echo Hello World"
93
)
94

95
client.task.add("my-job", task_spec)
96
```
97

98
## Architecture
99

100
The Azure Batch client follows a resource hierarchy with operation-specific clients:
101

102
- **BatchServiceClient**: Main client managing all operations and authentication
103
- **Operations Classes**: Specialized operations for different resource types (pools, jobs, tasks, etc.)
104
- **Model Classes**: Data structures representing Azure Batch entities and configurations
105
- **Authentication**: Shared key authentication for secure API access
106

107
Each operation class provides full CRUD (Create, Read, Update, Delete) capabilities for its respective resources, along with batch-specific operations like scaling, scheduling, and monitoring.
108

109
## Capabilities
110

111
### Client Management
112

113
Core client initialization, configuration, and authentication management for accessing Azure Batch services.
114

115
```python { .api }
116
class BatchServiceClient:
117
    def __init__(self, credentials, batch_url): ...
118

119
class SharedKeyCredentials:
120
    def __init__(self, account_name: str, key: str): ...
121
```
122

123
[Client Management](./client-management.md)
124

125
### Pool Operations
126

127
Pool management capabilities including creation, deletion, scaling, and monitoring of compute node pools that execute batch workloads.
128

129
```python { .api }
130
class PoolOperations:
131
    def add(self, pool, pool_add_options=None, **kwargs): ...
132
    def list(self, pool_list_options=None, **kwargs): ...
133
    def get(self, pool_id, pool_get_options=None, **kwargs): ...
134
    def delete(self, pool_id, pool_delete_options=None, **kwargs): ...
135
    def resize(self, pool_id, pool_resize_parameter, **kwargs): ...
136
    def enable_auto_scale(self, pool_id, auto_scale_formula, **kwargs): ...
137
```
138

139
[Pool Operations](./pool-operations.md)
140

141
### Job Operations
142

143
Job management capabilities for creating, configuring, and controlling logical containers that organize and manage task execution within batch pools.
144

145
```python { .api }
146
class JobOperations:
147
    def add(self, job, job_add_options=None, **kwargs): ...
148
    def list(self, job_list_options=None, **kwargs): ...
149
    def get(self, job_id, job_get_options=None, **kwargs): ...
150
    def delete(self, job_id, job_delete_options=None, **kwargs): ...
151
    def enable(self, job_id, job_enable_options=None, **kwargs): ...
152
    def disable(self, job_id, disable_job_parameter, **kwargs): ...
153
    def terminate(self, job_id, job_terminate_parameter=None, **kwargs): ...
154
```
155

156
[Job Operations](./job-operations.md)
157

158
### Task Operations
159

160
Task management capabilities for creating, monitoring, and controlling individual work items that execute within batch jobs on compute nodes.
161

162
```python { .api }
163
class TaskOperations:
164
    def add(self, job_id, task, task_add_options=None, **kwargs): ...
165
    def add_collection(self, job_id, task_add_collection_parameter, **kwargs): ...
166
    def list(self, job_id, task_list_options=None, **kwargs): ...
167
    def get(self, job_id, task_id, task_get_options=None, **kwargs): ...
168
    def delete(self, job_id, task_id, task_delete_options=None, **kwargs): ...
169
    def update(self, job_id, task_id, task_update_parameter, **kwargs): ...
170
    def terminate(self, job_id, task_id, task_terminate_options=None, **kwargs): ...
171
```
172

173
[Task Operations](./task-operations.md)
174

175
### Compute Node Operations
176

177
Compute node management capabilities for managing individual virtual machines within pools, including user management, remote access, and node maintenance operations.
178

179
```python { .api }
180
class ComputeNodeOperations:
181
    def list(self, pool_id, compute_node_list_options=None, **kwargs): ...
182
    def get(self, pool_id, node_id, compute_node_get_options=None, **kwargs): ...
183
    def add_user(self, pool_id, node_id, user, **kwargs): ...
184
    def delete_user(self, pool_id, node_id, user_name, **kwargs): ...
185
    def reboot(self, pool_id, node_id, node_reboot_parameter=None, **kwargs): ...
186
    def reimage(self, pool_id, node_id, node_reimage_parameter=None, **kwargs): ...
187
```
188

189
[Compute Node Operations](./compute-node-operations.md)
190

191
### File Operations
192

193
File management capabilities for accessing, downloading, and managing files on compute nodes and task outputs.
194

195
```python { .api }
196
class FileOperations:
197
    def list_from_task(self, job_id, task_id, file_list_from_task_options=None, **kwargs): ...
198
    def list_from_compute_node(self, pool_id, node_id, file_list_from_compute_node_options=None, **kwargs): ...
199
    def get_from_task(self, job_id, task_id, file_path, **kwargs): ...
200
    def get_from_compute_node(self, pool_id, node_id, file_path, **kwargs): ...
201
    def delete_from_task(self, job_id, task_id, file_path, **kwargs): ...
202
    def delete_from_compute_node(self, pool_id, node_id, file_path, **kwargs): ...
203
```
204

205
[File Operations](./file-operations.md)
206

207
### Application Operations
208

209
Application package management capabilities for managing and deploying application packages to batch pools and tasks.
210

211
```python { .api }
212
class ApplicationOperations:
213
    def list(self, application_list_options=None, **kwargs): ...
214
    def get(self, application_id, application_get_options=None, **kwargs): ...
215
```
216

217
[Application Operations](./application-operations.md)
218

219
### Certificate Operations
220

221
Certificate management capabilities for adding, listing, and managing certificates used for authentication and secure communication in batch operations.
222

223
```python { .api }
224
class CertificateOperations:
225
    def add(self, certificate, certificate_add_options=None, **kwargs): ...
226
    def list(self, certificate_list_options=None, **kwargs): ...
227
    def get(self, thumbprint_algorithm, thumbprint, **kwargs): ...
228
    def delete(self, thumbprint_algorithm, thumbprint, **kwargs): ...
229
    def cancel_deletion(self, thumbprint_algorithm, thumbprint, **kwargs): ...
230
```
231

232
[Certificate Operations](./certificate-operations.md)
233

234
### Job Schedule Operations
235

236
Job schedule management capabilities for creating and managing recurring batch jobs with time-based or interval-based scheduling.
237

238
```python { .api }
239
class JobScheduleOperations:
240
    def add(self, cloud_job_schedule, job_schedule_add_options=None, **kwargs): ...
241
    def list(self, job_schedule_list_options=None, **kwargs): ...
242
    def get(self, job_schedule_id, job_schedule_get_options=None, **kwargs): ...
243
    def delete(self, job_schedule_id, job_schedule_delete_options=None, **kwargs): ...
244
    def exists(self, job_schedule_id, job_schedule_exists_options=None, **kwargs): ...
245
    def enable(self, job_schedule_id, job_schedule_enable_options=None, **kwargs): ...
246
    def disable(self, job_schedule_id, job_schedule_disable_options=None, **kwargs): ...
247
    def terminate(self, job_schedule_id, job_schedule_terminate_options=None, **kwargs): ...
248
```
249

250
[Job Schedule Operations](./job-schedule-operations.md)
251

252
### Account Operations
253

254
Account-level operations for retrieving information about supported VM images and pool node counts across the batch account.
255

256
```python { .api }
257
class AccountOperations:
258
    def list_supported_images(self, account_list_supported_images_options=None, **kwargs): ...
259
    def list_pool_node_counts(self, account_list_pool_node_counts_options=None, **kwargs): ...
260
```
261

262
[Account Operations](./account-operations.md)
263

264
### Compute Node Extension Operations
265

266
Compute node extension management capabilities for managing and querying virtual machine extensions on compute nodes within batch pools.
267

268
```python { .api }
269
class ComputeNodeExtensionOperations:
270
    def get(self, pool_id, node_id, extension_name, **kwargs): ...
271
    def list(self, pool_id, node_id, **kwargs): ...
272
```
273

274
[Compute Node Extension Operations](./compute-node-extension-operations.md)
275

276
## Common Types
277

278
### Core Entity Types
279

280
```python { .api }
281
class CloudPool:
282
    """Pool information and configuration."""
283
    def __init__(self):
284
        self.id: str
285
        self.state: str  # PoolState enum
286
        self.vm_size: str
287
        self.target_dedicated_nodes: int
288
        self.current_dedicated_nodes: int
289
        self.enable_auto_scale: bool
290
        self.auto_scale_formula: str
291

292
class CloudJob:
293
    """Job information and configuration."""
294
    def __init__(self):
295
        self.id: str
296
        self.state: str  # JobState enum
297
        self.pool_info: PoolInformation
298
        self.priority: int
299
        self.constraints: JobConstraints
300
        self.job_manager_task: JobManagerTask
301

302
class CloudTask:
303
    """Task information and configuration."""
304
    def __init__(self):
305
        self.id: str
306
        self.state: str  # TaskState enum
307
        self.command_line: str
308
        self.execution_info: TaskExecutionInformation
309
        self.resource_files: List[ResourceFile]
310
        self.output_files: List[OutputFile]
311
        self.environment_settings: List[EnvironmentSetting]
312

313
class ComputeNode:
314
    """Compute node information and status."""
315
    def __init__(self):
316
        self.id: str
317
        self.state: str  # ComputeNodeState enum
318
        self.vm_size: str
319
        self.ip_address: str
320
        self.total_tasks_run: int
321
        self.running_tasks_count: int
322
```
323

324
### Configuration Types
325

326
```python { .api }
327
class PoolSpecification:
328
    """Pool creation/update specification."""
329
    def __init__(self):
330
        self.id: str
331
        self.vm_size: str
332
        self.cloud_service_configuration: CloudServiceConfiguration
333
        self.virtual_machine_configuration: VirtualMachineConfiguration
334
        self.target_dedicated_nodes: int
335
        self.target_low_priority_nodes: int
336
        self.enable_auto_scale: bool
337
        self.auto_scale_formula: str
338
        self.start_task: StartTask
339
        self.certificates: List[CertificateReference]
340
        self.application_packages: List[ApplicationPackageReference]
341

342
class JobSpecification:
343
    """Job creation/update specification."""
344
    def __init__(self):
345
        self.id: str
346
        self.pool_info: PoolInformation
347
        self.priority: int
348
        self.constraints: JobConstraints
349
        self.job_manager_task: JobManagerTask
350
        self.job_preparation_task: JobPreparationTask
351
        self.job_release_task: JobReleaseTask
352
        self.common_environment_settings: List[EnvironmentSetting]
353

354
class TaskSpecification:
355
    """Task creation/update specification."""
356
    def __init__(self):
357
        self.id: str
358
        self.command_line: str
359
        self.resource_files: List[ResourceFile]
360
        self.output_files: List[OutputFile]
361
        self.environment_settings: List[EnvironmentSetting]
362
        self.constraints: TaskConstraints
363
        self.user_identity: UserIdentity
364
        self.depends_on: TaskDependencies
365
```
366

367
### Authentication Types
368

369
```python { .api }
370
class SharedKeyCredentials:
371
    """Shared key authentication for Azure Batch."""
372
    def __init__(self, account_name: str, key: str): ...
373
    def signed_session(self, session=None): ...
374

375
class BatchServiceClientConfiguration:
376
    """Configuration for BatchServiceClient."""
377
    def __init__(self, credentials, batch_url: str): ...
378
```
379

380
### Error Types
381

382
```python { .api }
383
class BatchError:
384
    """Batch service error information."""
385
    def __init__(self):
386
        self.code: str
387
        self.message: str
388
        self.values: List[BatchErrorDetail]
389

390
class BatchErrorException(Exception):
391
    """Exception for Batch service errors."""
392
    def __init__(self, message: str, response, error: BatchError): ...
393
```