0
# Device Operations
1
2
Device lifecycle management operations including bulk import/export of device identities, registry statistics, and device-related job management for large-scale IoT deployments. These operations support managing thousands to millions of devices efficiently through Azure Storage-based bulk operations.
3
4
## Capabilities
5
6
### Device Registry Statistics
7
8
Retrieve comprehensive statistics about the device registry including device counts by status for monitoring and capacity planning.
9
10
```python { .api }
11
def get_stats(resource_group_name: str, resource_name: str, **kwargs) -> RegistryStatistics:
12
"""
13
Get statistics from an IoT hub device registry.
14
15
Args:
16
resource_group_name: Name of the resource group
17
resource_name: Name of the IoT hub resource
18
19
Returns:
20
RegistryStatistics: Device count statistics including total, enabled, and disabled devices
21
"""
22
```
23
24
### Bulk Device Import/Export Operations
25
26
Large-scale device identity management through Azure Storage blob containers, supporting millions of device operations efficiently.
27
28
```python { .api }
29
def export_devices(
30
resource_group_name: str,
31
resource_name: str,
32
export_devices_parameters: ExportDevicesRequest,
33
**kwargs
34
) -> JobResponse:
35
"""
36
Export all device identities to Azure Storage blob container.
37
38
Args:
39
resource_group_name: Name of the resource group
40
resource_name: Name of the IoT hub resource
41
export_devices_parameters: Export configuration including storage details
42
43
Returns:
44
JobResponse: Export job details for tracking progress
45
"""
46
47
def import_devices(
48
resource_group_name: str,
49
resource_name: str,
50
import_devices_parameters: ImportDevicesRequest,
51
**kwargs
52
) -> JobResponse:
53
"""
54
Import, update, or delete device identities from blob storage.
55
56
Args:
57
resource_group_name: Name of the resource group
58
resource_name: Name of the IoT hub resource
59
import_devices_parameters: Import configuration including storage details and import mode
60
61
Returns:
62
JobResponse: Import job details for tracking progress
63
"""
64
```
65
66
### Job Management
67
68
Monitor and manage long-running device operations including import/export jobs and other device management tasks.
69
70
```python { .api }
71
def list_jobs(resource_group_name: str, resource_name: str, **kwargs) -> ItemPaged[JobResponse]:
72
"""
73
Get list of all jobs in an IoT hub.
74
75
Args:
76
resource_group_name: Name of the resource group
77
resource_name: Name of the IoT hub resource
78
79
Returns:
80
ItemPaged[JobResponse]: Paginated list of all jobs with status and details
81
"""
82
83
def get_job(resource_group_name: str, resource_name: str, job_id: str, **kwargs) -> JobResponse:
84
"""
85
Get details of a specific job from IoT hub.
86
87
Args:
88
resource_group_name: Name of the resource group
89
resource_name: Name of the IoT hub resource
90
job_id: Unique identifier of the job
91
92
Returns:
93
JobResponse: Detailed job information including status, progress, and results
94
"""
95
```
96
97
## Usage Examples
98
99
### Exporting device identities
100
101
```python
102
from azure.identity import DefaultAzureCredential
103
from azure.mgmt.iothub import IotHubClient
104
from azure.mgmt.iothub.models import ExportDevicesRequest
105
106
credential = DefaultAzureCredential()
107
client = IotHubClient(credential, "subscription-id")
108
109
# Configure export to Azure Storage
110
export_request = ExportDevicesRequest(
111
export_blob_container_uri="https://mystorageaccount.blob.core.windows.net/exports",
112
exclude_keys=False, # Include device keys in export
113
export_blob_name="device-export.json"
114
)
115
116
# Start export job
117
job = client.iot_hub_resource.export_devices(
118
"my-resource-group",
119
"my-iot-hub",
120
export_request
121
)
122
123
print(f"Export job started: {job.job_id}")
124
print(f"Job status: {job.status}")
125
print(f"Job type: {job.type}")
126
```
127
128
### Importing device identities
129
130
```python
131
from azure.mgmt.iothub.models import ImportDevicesRequest, JobType
132
133
# Configure import from Azure Storage
134
import_request = ImportDevicesRequest(
135
input_blob_container_uri="https://mystorageaccount.blob.core.windows.net/imports",
136
output_blob_container_uri="https://mystorageaccount.blob.core.windows.net/results",
137
input_blob_name="devices-to-import.json",
138
type=JobType.IMPORT
139
)
140
141
# Start import job
142
job = client.iot_hub_resource.import_devices(
143
"my-resource-group",
144
"my-iot-hub",
145
import_request
146
)
147
148
print(f"Import job started: {job.job_id}")
149
```
150
151
### Monitoring job progress
152
153
```python
154
# Get specific job details
155
job_details = client.iot_hub_resource.get_job(
156
"my-resource-group",
157
"my-iot-hub",
158
"job-id-from-previous-operation"
159
)
160
161
print(f"Job {job_details.job_id}:")
162
print(f" Status: {job_details.status}")
163
print(f" Type: {job_details.type}")
164
print(f" Start Time: {job_details.start_time_utc}")
165
print(f" End Time: {job_details.end_time_utc}")
166
print(f" Progress: {job_details.progress}%")
167
168
if job_details.failure_reason:
169
print(f" Failure Reason: {job_details.failure_reason}")
170
171
# List all jobs for monitoring
172
all_jobs = list(client.iot_hub_resource.list_jobs("my-resource-group", "my-iot-hub"))
173
running_jobs = [job for job in all_jobs if job.status == "Running"]
174
print(f"Currently running jobs: {len(running_jobs)}")
175
```
176
177
### Getting device registry statistics
178
179
```python
180
# Get device statistics
181
stats = client.iot_hub_resource.get_stats("my-resource-group", "my-iot-hub")
182
183
print(f"Device Registry Statistics:")
184
print(f" Total devices: {stats.total_device_count}")
185
print(f" Enabled devices: {stats.enabled_device_count}")
186
print(f" Disabled devices: {stats.disabled_device_count}")
187
188
# Calculate utilization
189
if stats.total_device_count > 0:
190
enabled_percentage = (stats.enabled_device_count / stats.total_device_count) * 100
191
print(f" Enabled devices: {enabled_percentage:.1f}%")
192
```
193
194
## Types
195
196
```python { .api }
197
class RegistryStatistics:
198
"""
199
IoT Hub device registry statistics.
200
201
Attributes:
202
total_device_count: Total number of devices in registry (readonly)
203
enabled_device_count: Number of enabled devices (readonly)
204
disabled_device_count: Number of disabled devices (readonly)
205
"""
206
total_device_count: Optional[int]
207
enabled_device_count: Optional[int]
208
disabled_device_count: Optional[int]
209
210
class ExportDevicesRequest:
211
"""
212
Device export operation configuration.
213
214
Attributes:
215
export_blob_container_uri: Azure Storage container URI for export
216
exclude_keys: Whether to exclude device keys from export
217
export_blob_name: Name of the export blob file (optional)
218
authentication_type: Authentication method for storage access
219
identity: Managed identity for storage access (optional)
220
"""
221
export_blob_container_uri: str
222
exclude_keys: bool
223
export_blob_name: Optional[str]
224
authentication_type: Optional[AuthenticationType]
225
identity: Optional[ManagedIdentity]
226
227
class ImportDevicesRequest:
228
"""
229
Device import operation configuration.
230
231
Attributes:
232
input_blob_container_uri: Azure Storage container URI containing import data
233
output_blob_container_uri: Azure Storage container URI for operation results
234
input_blob_name: Name of the input blob file (optional)
235
output_blob_name: Name of the output blob file (optional)
236
type: Type of import operation (import, update, delete)
237
authentication_type: Authentication method for storage access
238
identity: Managed identity for storage access (optional)
239
"""
240
input_blob_container_uri: str
241
output_blob_container_uri: str
242
input_blob_name: Optional[str]
243
output_blob_name: Optional[str]
244
type: Optional[JobType]
245
authentication_type: Optional[AuthenticationType]
246
identity: Optional[ManagedIdentity]
247
248
class JobResponse:
249
"""
250
Job operation details and status.
251
252
Attributes:
253
job_id: Unique job identifier (readonly)
254
start_time_utc: Job start timestamp (readonly)
255
end_time_utc: Job completion timestamp (readonly)
256
type: Job type (import, export, etc.)
257
status: Current job status
258
progress: Job completion percentage (readonly)
259
input_blob_container_uri: Input storage container URI (readonly)
260
input_blob_uri: Input blob URI (readonly)
261
output_blob_container_uri: Output storage container URI (readonly)
262
output_blob_uri: Output blob URI (readonly)
263
exclude_keys_in_export: Whether keys were excluded in export (readonly)
264
failure_reason: Reason for job failure if applicable (readonly)
265
"""
266
job_id: Optional[str]
267
start_time_utc: Optional[datetime]
268
end_time_utc: Optional[datetime]
269
type: Optional[JobType]
270
status: Optional[JobStatus]
271
progress: Optional[int]
272
input_blob_container_uri: Optional[str]
273
input_blob_uri: Optional[str]
274
output_blob_container_uri: Optional[str]
275
output_blob_uri: Optional[str]
276
exclude_keys_in_export: Optional[bool]
277
failure_reason: Optional[str]
278
```