IoTHubRegistryManager Class

A class to provide convenience APIs for IoTHub Registry Manager operations, based on top of the auto generated IotHub REST APIs

Initializer for a Registry Manager Service client.

Users should not call this directly. Rather, they should the from_connection_string() or from_token_credential() factory methods.

After a successful creation the class has been authenticated with IoTHub and it is ready to call the member APIs to communicate with IoTHub.

Inheritance
builtins.object
IoTHubRegistryManager

Constructor

IoTHubRegistryManager(connection_string=None, host=None, token_credential=None)

Parameters

Name Description
connection_string
str

The IoTHub connection string used to authenticate connection with IoTHub if we are using connection_str authentication. Default value: None

Default value: None
host
str

The Azure service url if we are using token credential authentication. Default value: None

Default value: None
auth
Required
str

The Azure authentication object if we are using token credential authentication. Default value: None

token_credential
Default value: None

Methods

bulk_create_or_update_devices

Create, update, or delete the identities of multiple devices from the IoTHub identity registry.

Create, update, or delete the identities of multiple devices from the IoTHub identity registry. A device identity can be specified only once in the list. Different operations (create, update, delete) on different devices are allowed. A maximum of 100 devices can be specified per invocation. For large scale operations, consider using the import feature using blob storage(https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities).

create_device_with_certificate_authority

Creates a device identity on IoTHub using certificate authority.

create_device_with_sas

Creates a device identity on IoTHub using SAS authentication.

create_device_with_x509

Creates a device identity on IoTHub using X509 authentication.

create_module_with_certificate_authority

Creates a module identity for a device on IoTHub using certificate authority.

create_module_with_sas

Creates a module identity for a device on IoTHub using SAS authentication.

create_module_with_x509

Creates a module identity for a device on IoTHub using X509 authentication.

delete_device

Deletes a device identity from IoTHub.

delete_module

Deletes a module identity for a device from IoTHub.

from_connection_string

Classmethod initializer for a Registry Manager Service client. Creates Registry Manager class from connection string.

After a successful creation the class has been authenticated with IoTHub and it is ready to call the member APIs to communicate with IoTHub.

from_token_credential

Classmethod initializer for a Registry Manager Service client. Creates Registry Manager class from host name url and Azure token credential.

After a successful creation the class has been authenticated with IoTHub and it is ready to call the member APIs to communicate with IoTHub.

get_device

Retrieves a device identity from IoTHub.

get_device_registry_statistics

Retrieves the IoTHub device registry statistics.

get_devices

Get the identities of multiple devices from the IoTHub identity registry. Not recommended. Use the IoTHub query language to retrieve device twin and device identity information. See https://docs.microsoft.com/en-us/rest/api/iothub/service/queryiothub and https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-query-language for more information.

get_module

Retrieves a module identity for a device from IoTHub.

get_module_twin

Gets a module twin.

get_modules

Retrieves all module identities on a device.

get_service_statistics

Retrieves the IoTHub service statistics.

get_twin

Gets a device twin.

invoke_device_method

Invoke a direct method on a device.

invoke_device_module_method

Invoke a direct method on a device.

query_iot_hub

Query an IoTHub to retrieve information regarding device twins using a SQL-like language. See https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-query-language for more information. Pagination of results is supported. This returns information about device twins only.

replace_module_twin

Replaces tags and desired properties of a module twin.

replace_twin

Replaces tags and desired properties of a device twin.

send_c2d_message

Send a C2D message to a IoTHub Device.

update_device_with_certificate_authority

Updates a device identity on IoTHub using certificate authority.

update_device_with_sas

Updates a device identity on IoTHub using SAS authentication.

update_device_with_x509

Updates a device identity on IoTHub using X509 authentication.

update_module_twin

Updates tags and desired properties of a module twin.

update_module_with_certificate_authority

Updates a module identity for a device on IoTHub using certificate authority.

update_module_with_sas

Updates a module identity for a device on IoTHub using SAS authentication.

update_module_with_x509

Updates a module identity for a device on IoTHub using X509 authentication.

update_twin

Updates tags and desired properties of a device twin.

bulk_create_or_update_devices

Create, update, or delete the identities of multiple devices from the IoTHub identity registry.

Create, update, or delete the identities of multiple devices from the IoTHub identity registry. A device identity can be specified only once in the list. Different operations (create, update, delete) on different devices are allowed. A maximum of 100 devices can be specified per invocation. For large scale operations, consider using the import feature using blob storage(https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities).

bulk_create_or_update_devices(devices)

Parameters

Name Description
devices
Required

The list of device objects to operate on.

Returns

Type Description

The BulkRegistryOperationResult object.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

create_device_with_certificate_authority

Creates a device identity on IoTHub using certificate authority.

create_device_with_certificate_authority(device_id, status, iot_edge=False, status_reason=None, device_scope=None, parent_scopes=None)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

status
Required
str

Initial state of the created device. (Possible values: "enabled" or "disabled").

iot_edge

Whether or not the created device is an IoT Edge device. Default value: False

Default value: False
status_reason
str

The reason for the device identity status. Default value: None

Default value: None
device_scope
str

The scope of the device. Default value: None Auto generated and immutable for edge devices and modifiable in leaf devices to create child/parent relationship. For leaf devices, the value to set a parent edge device can be retrieved from the parent edge device's device_scope property.

Default value: None
parent_scopes

The scopes of the upper level edge devices if applicable. Default value: None For edge devices, the value to set a parent edge device can be retrieved from the parent edge device's device_scope property. For leaf devices, this could be set to the same value as device_scope or left for the service to copy over.

Default value: None

Returns

Type Description

Device object containing the created device.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

create_device_with_sas

Creates a device identity on IoTHub using SAS authentication.

create_device_with_sas(device_id, primary_key, secondary_key, status, iot_edge=False, status_reason=None, device_scope=None, parent_scopes=None)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

primary_key
Required
str

Primary authentication key.

secondary_key
Required
str

Secondary authentication key.

status
Required
str

Initial state of the created device. (Possible values: "enabled" or "disabled")

iot_edge

Whether or not the created device is an IoT Edge device. Default value: False

Default value: False
status_reason
str

The reason for the device identity status. Default value: None

Default value: None
device_scope
str

The scope of the device. Default value: None Auto generated and immutable for edge devices and modifiable in leaf devices to create child/parent relationship. For leaf devices, the value to set a parent edge device can be retrieved from the parent edge device's device_scope property.

Default value: None
parent_scopes

The scopes of the upper level edge devices if applicable. Default value: None For edge devices, the value to set a parent edge device can be retrieved from the parent edge device's device_scope property. For leaf devices, this could be set to the same value as device_scope or left for the service to copy over.

Default value: None

Returns

Type Description

Device object containing the created device.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

create_device_with_x509

Creates a device identity on IoTHub using X509 authentication.

create_device_with_x509(device_id, primary_thumbprint, secondary_thumbprint, status, iot_edge=False, status_reason=None, device_scope=None, parent_scopes=None)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

primary_thumbprint
Required
str

Primary X509 thumbprint.

secondary_thumbprint
Required
str

Secondary X509 thumbprint.

status
Required
str

Initial state of the created device. (Possible values: "enabled" or "disabled")

iot_edge

Whether or not the created device is an IoT Edge device. Default value: False

Default value: False
status_reason
str

The reason for the device identity status. Default value: None

Default value: None
device_scope
str

The scope of the device. Default value: None Auto generated and immutable for edge devices and modifiable in leaf devices to create child/parent relationship. For leaf devices, the value to set a parent edge device can be retrieved from the parent edge device's device_scope property.

Default value: None
parent_scopes

The scopes of the upper level edge devices if applicable. Default value: None For edge devices, the value to set a parent edge device can be retrieved from the parent edge device's device_scope property. For leaf devices, this could be set to the same value as device_scope or left for the service to copy over.

Default value: None

Returns

Type Description

Device object containing the created device.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

create_module_with_certificate_authority

Creates a module identity for a device on IoTHub using certificate authority.

create_module_with_certificate_authority(device_id, module_id, managed_by)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

module_id
Required
str

The name (Id) of the module.

managed_by
Required
str

The name of the manager device (edge).

Returns

Type Description

Module object containing the created module.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

create_module_with_sas

Creates a module identity for a device on IoTHub using SAS authentication.

create_module_with_sas(device_id, module_id, managed_by, primary_key, secondary_key)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

module_id
Required
str

The name (Id) of the module.

managed_by
Required
str

The name of the manager device (edge).

primary_key
Required
str

Primary authentication key.

secondary_key
Required
str

Secondary authentication key.

Returns

Type Description

Module object containing the created module.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

create_module_with_x509

Creates a module identity for a device on IoTHub using X509 authentication.

create_module_with_x509(device_id, module_id, managed_by, primary_thumbprint, secondary_thumbprint)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

module_id
Required
str

The name (Id) of the module.

managed_by
Required
str

The name of the manager device (edge).

primary_thumbprint
Required
str

Primary X509 thumbprint.

secondary_thumbprint
Required
str

Secondary X509 thumbprint.

Returns

Type Description

Module object containing the created module.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

delete_device

Deletes a device identity from IoTHub.

delete_device(device_id, etag=None)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

etag
str

The etag (if_match) value to use for the delete operation.

Default value: None

Returns

Type Description

None.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

delete_module

Deletes a module identity for a device from IoTHub.

delete_module(device_id, module_id, etag=None)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

module_id
Required
str

The name (Id) of the module.

etag
str

The etag (if_match) value to use for the delete operation.

Default value: None

Returns

Type Description

None.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

from_connection_string

Classmethod initializer for a Registry Manager Service client. Creates Registry Manager class from connection string.

After a successful creation the class has been authenticated with IoTHub and it is ready to call the member APIs to communicate with IoTHub.

from_connection_string(connection_string)

Parameters

Name Description
connection_string
Required
str

The IoTHub connection string used to authenticate connection with IoTHub.

Returns

Type Description

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

from_token_credential

Classmethod initializer for a Registry Manager Service client. Creates Registry Manager class from host name url and Azure token credential.

After a successful creation the class has been authenticated with IoTHub and it is ready to call the member APIs to communicate with IoTHub.

from_token_credential(url, token_credential)

Parameters

Name Description
url
Required
str

The Azure service url (host name).

token_credential
Required
<xref:azure.core.TokenCredential>

The Azure token credential object

Returns

Type Description

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

get_device

Retrieves a device identity from IoTHub.

get_device(device_id)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

Returns

Type Description

The Device object containing the requested device.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

get_device_registry_statistics

Retrieves the IoTHub device registry statistics.

get_device_registry_statistics()

Returns

Type Description

The RegistryStatistics object.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

get_devices

Get the identities of multiple devices from the IoTHub identity registry. Not recommended. Use the IoTHub query language to retrieve device twin and device identity information. See https://docs.microsoft.com/en-us/rest/api/iothub/service/queryiothub and https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-query-language for more information.

get_devices(max_number_of_devices=None)

Parameters

Name Description
max_number_of_devices
int

This parameter when specified, defines the maximum number of device identities that are returned. Any value outside the range of 1-1000 is considered to be 1000

Default value: None

Returns

Type Description

List of device info.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

get_module

Retrieves a module identity for a device from IoTHub.

get_module(device_id, module_id)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

module_id
Required
str

The name (Id) of the module.

Returns

Type Description

The Module object containing the requested module.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

get_module_twin

Gets a module twin.

get_module_twin(device_id, module_id)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

module_id
Required
str

The name (Id) of the module.

Returns

Type Description

The Twin object.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

get_modules

Retrieves all module identities on a device.

get_modules(device_id)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

Returns

Type Description

The list[Module] containing all the modules on the device.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

get_service_statistics

Retrieves the IoTHub service statistics.

get_service_statistics()

Returns

Type Description

The ServiceStatistics object.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

get_twin

Gets a device twin.

get_twin(device_id)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

Returns

Type Description

The Twin object.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

invoke_device_method

Invoke a direct method on a device.

invoke_device_method(device_id, direct_method_request)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

direct_method_request
Required

The method request.

Returns

Type Description

The CloudToDeviceMethodResult object.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

invoke_device_module_method

Invoke a direct method on a device.

invoke_device_module_method(device_id, module_id, direct_method_request)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

module_id
Required
str

The name (Id) of the module.

direct_method_request
Required

The method request.

Returns

Type Description

The CloudToDeviceMethodResult object.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

query_iot_hub

Query an IoTHub to retrieve information regarding device twins using a SQL-like language. See https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-query-language for more information. Pagination of results is supported. This returns information about device twins only.

query_iot_hub(query_specification, continuation_token=None, max_item_count=None)

Parameters

Name Description
query
Required

The query specification.

continuation_token
str

Continuation token for paging

Default value: None
max_item_count
str

Maximum number of requested device twins

Default value: None
query_specification
Required

Returns

Type Description

The QueryResult object.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

replace_module_twin

Replaces tags and desired properties of a module twin.

replace_module_twin(device_id, module_id, module_twin, etag=None)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

module_id
Required
str

The name (Id) of the module.

module_twin
Required

The twin info of the module.

etag
str

The etag (if_match) value to use for the replace operation.

Default value: None

Returns

Type Description

The Twin object.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

replace_twin

Replaces tags and desired properties of a device twin.

replace_twin(device_id, device_twin, etag=None)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

device_twin
Required

The twin info of the device.

etag
str

The etag (if_match) value to use for the replace operation.

Default value: None

Returns

Type Description

The Twin object.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

send_c2d_message

Send a C2D message to a IoTHub Device.

send_c2d_message(device_id, message, properties={})

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

message
Required
str

The message that is to be delivered to the device.

properties

The properties to be send with the message. Can contain application properties and system properties

Default value: {}

Exceptions

Type Description
Exception if the Send command is not able to send the message

update_device_with_certificate_authority

Updates a device identity on IoTHub using certificate authority.

update_device_with_certificate_authority(device_id, etag, status, iot_edge=False, status_reason=None, device_scope=None, parent_scopes=None)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

etag
Required
str

The etag (if_match) value to use for the update operation.

status
Required
str

Initial state of the created device. (Possible values: "enabled" or "disabled").

iot_edge

Whether or not the created device is an IoT Edge device. Default value: False

Default value: False
status_reason
str

The reason for the device identity status. Default value: None

Default value: None
device_scope
str

The scope of the device. Default value: None Auto generated and immutable for edge devices and modifiable in leaf devices to create child/parent relationship. For leaf devices, the value to set a parent edge device can be retrieved from the parent edge device's device_scope property.

Default value: None
parent_scopes

The scopes of the upper level edge devices if applicable. Default value: None For edge devices, the value to set a parent edge device can be retrieved from the parent edge device's device_scope property. For leaf devices, this could be set to the same value as device_scope or left for the service to copy over.

Default value: None

Returns

Type Description

The updated Device object containing the created device.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

update_device_with_sas

Updates a device identity on IoTHub using SAS authentication.

update_device_with_sas(device_id, etag, primary_key, secondary_key, status, iot_edge=False, status_reason=None, device_scope=None, parent_scopes=None)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

etag
Required
str

The etag (if_match) value to use for the update operation.

primary_key
Required
str

Primary authentication key.

secondary_key
Required
str

Secondary authentication key.

status
Required
str

Initial state of the created device. (Possible values: "enabled" or "disabled").

iot_edge

Whether or not the created device is an IoT Edge device. Default value: False

Default value: False
status_reason
str

The reason for the device identity status. Default value: None

Default value: None
device_scope
str

The scope of the device. Default value: None Auto generated and immutable for edge devices and modifiable in leaf devices to create child/parent relationship. For leaf devices, the value to set a parent edge device can be retrieved from the parent edge device's device_scope property.

Default value: None
parent_scopes

The scopes of the upper level edge devices if applicable. Default value: None For edge devices, the value to set a parent edge device can be retrieved from the parent edge device's device_scope property. For leaf devices, this could be set to the same value as device_scope or left for the service to copy over.

Default value: None

Returns

Type Description

The updated Device object containing the created device.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

update_device_with_x509

Updates a device identity on IoTHub using X509 authentication.

update_device_with_x509(device_id, etag, primary_thumbprint, secondary_thumbprint, status, iot_edge=False, status_reason=None, device_scope=None, parent_scopes=None)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

etag
Required
str

The etag (if_match) value to use for the update operation.

primary_thumbprint
Required
str

Primary X509 thumbprint.

secondary_thumbprint
Required
str

Secondary X509 thumbprint.

status
Required
str

Initial state of the created device. (Possible values: "enabled" or "disabled").

iot_edge

Whether or not the created device is an IoT Edge device. Default value: False

Default value: False
status_reason
str

The reason for the device identity status. Default value: None

Default value: None
device_scope
str

The scope of the device. Default value: None Auto generated and immutable for edge devices and modifiable in leaf devices to create child/parent relationship. For leaf devices, the value to set a parent edge device can be retrieved from the parent edge device's device_scope property.

Default value: None
parent_scopes

The scopes of the upper level edge devices if applicable. Default value: None For edge devices, the value to set a parent edge device can be retrieved from the parent edge device's device_scope property. For leaf devices, this could be set to the same value as device_scope or left for the service to copy over.

Default value: None

Returns

Type Description

The updated Device object containing the created device.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

update_module_twin

Updates tags and desired properties of a module twin.

update_module_twin(device_id, module_id, module_twin, etag=None)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

module_id
Required
str

The name (Id) of the module.

module_twin
Required

The twin info of the module.

etag
str

The etag (if_match) value to use for the update operation.

Default value: None

Returns

Type Description

The Twin object.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

update_module_with_certificate_authority

Updates a module identity for a device on IoTHub using certificate authority.

update_module_with_certificate_authority(device_id, module_id, managed_by, etag)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

module_id
Required
str

The name (Id) of the module.

managed_by
Required
str

The name of the manager device (edge).

etag
Required
str

The etag (if_match) value to use for the update operation.

Returns

Type Description

The updated Module object containing the created module.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

update_module_with_sas

Updates a module identity for a device on IoTHub using SAS authentication.

update_module_with_sas(device_id, module_id, managed_by, etag, primary_key, secondary_key)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

module_id
Required
str

The name (Id) of the module.

managed_by
Required
str

The name of the manager device (edge).

etag
Required
str

The etag (if_match) value to use for the update operation.

primary_key
Required
str

Primary authentication key.

secondary_key
Required
str

Secondary authentication key.

Returns

Type Description

The updated Module object containing the created module.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

update_module_with_x509

Updates a module identity for a device on IoTHub using X509 authentication.

update_module_with_x509(device_id, module_id, managed_by, etag, primary_thumbprint, secondary_thumbprint)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

module_id
Required
str

The name (Id) of the module.

managed_by
Required
str

The name of the manager device (edge).

etag
Required
str

The etag (if_match) value to use for the update operation.

primary_thumbprint
Required
str

Primary X509 thumbprint.

secondary_thumbprint
Required
str

Secondary X509 thumbprint.

Returns

Type Description

The updated Module object containing the created module.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>

update_twin

Updates tags and desired properties of a device twin.

update_twin(device_id, device_twin, etag=None)

Parameters

Name Description
device_id
Required
str

The name (Id) of the device.

device_twin
Required

The twin info of the device.

etag
str

The etag (if_match) value to use for the update operation.

Default value: None

Returns

Type Description

The Twin object.

Exceptions

Type Description
<xref:if the HTTP response status is not in >[<xref:200>]<xref:.>