ProvisioningDeviceClient Class
Client which can be used to run the registration of a device with provisioning service using Symmetric Key or X509 authentication.
Initializes the provisioning client.
NOTE: This initializer should not be called directly. Instead, the class methods that start with create_from_ should be used to create a client object.
- Inheritance
-
azure.iot.device.provisioning.abstract_provisioning_device_client.AbstractProvisioningDeviceClientProvisioningDeviceClient
Constructor
ProvisioningDeviceClient(pipeline)Parameters
| Name | Description |
|---|---|
|
pipeline
Required
|
<xref:azure.iot.device.provisioning.pipeline.MQTTPipeline>
Instance of the provisioning pipeline object. |
Methods
| create_from_symmetric_key |
Create a client which can be used to run the registration of a device with provisioning service using Symmetric Key authentication. |
| create_from_x509_certificate |
Create a client which can be used to run the registration of a device with provisioning service using X509 certificate authentication. |
| register |
Register the device with the provisioning service This is a synchronous call, meaning that this function will not return until the registration process has completed successfully or the attempt has resulted in a failure. Before returning, the client will also disconnect from the provisioning service. If a registration attempt is made while a previous registration is in progress it may throw an error. Once the device is successfully registered, the client will no longer be operable. |
create_from_symmetric_key
Create a client which can be used to run the registration of a device with provisioning service using Symmetric Key authentication.
create_from_symmetric_key(provisioning_host, registration_id, id_scope, symmetric_key, **kwargs)Parameters
| Name | Description |
|---|---|
|
provisioning_host
Required
|
Host running the Device Provisioning Service. Can be found in the Azure portal in the Overview tab as the string Global device endpoint. |
|
registration_id
Required
|
The registration ID used to uniquely identify a device in the Device Provisioning Service. The registration ID is alphanumeric, lowercase string and may contain hyphens. |
|
id_scope
Required
|
The ID scope used to uniquely identify the specific provisioning service the device will register through. The ID scope is assigned to a Device Provisioning Service when it is created by the user and is generated by the service and is immutable, guaranteeing uniqueness. |
|
symmetric_key
Required
|
The key which will be used to create the shared access signature token to authenticate the device with the Device Provisioning Service. By default, the Device Provisioning Service creates new symmetric keys with a default length of 32 bytes when new enrollments are saved with the Auto-generate keys option enabled. Users can provide their own symmetric keys for enrollments by disabling this option within 16 bytes and 64 bytes and in valid Base64 format. |
|
server_verification_cert
Required
|
Configuration Option. The trusted certificate chain. Necessary when using connecting to an endpoint which has a non-standard root of trust, such as a protocol gateway. |
|
gateway_hostname
Required
|
Configuration Option. The gateway hostname for the gateway device. |
|
websockets
Required
|
Configuration Option. Default is False. Set to true if using MQTT over websockets. |
|
cipher
Required
|
Configuration Option. Cipher suite(s) for TLS/SSL, as a string in "OpenSSL cipher list format" or as a list of cipher suite strings. |
|
proxy_options
Required
|
Options for sending traffic through proxy servers. |
|
keepalive
Required
|
Maximum period in seconds between communications with the broker. If no other messages are being exchanged, this controls the rate at which the client will send ping messages to the broker. If not provided default value of 60 secs will be used. |
Returns
| Type | Description |
|---|---|
|
A ProvisioningDeviceClient instance which can register via Symmetric Key. |
Exceptions
| Type | Description |
|---|---|
|
TypeError if given an unrecognized parameter.
|
create_from_x509_certificate
Create a client which can be used to run the registration of a device with provisioning service using X509 certificate authentication.
create_from_x509_certificate(provisioning_host, registration_id, id_scope, x509, **kwargs)Parameters
| Name | Description |
|---|---|
|
provisioning_host
Required
|
Host running the Device Provisioning Service. Can be found in the Azure portal in the Overview tab as the string Global device endpoint. |
|
registration_id
Required
|
The registration ID used to uniquely identify a device in the Device Provisioning Service. The registration ID is alphanumeric, lowercase string and may contain hyphens. |
|
id_scope
Required
|
The ID scope is used to uniquely identify the specific provisioning service the device will register through. The ID scope is assigned to a Device Provisioning Service when it is created by the user and is generated by the service and is immutable, guaranteeing uniqueness. |
|
x509
Required
|
The x509 certificate, To use the certificate the enrollment object needs to contain cert (either the root certificate or one of the intermediate CA certificates). If the cert comes from a CER file, it needs to be base64 encoded. |
|
server_verification_cert
Required
|
Configuration Option. The trusted certificate chain. Necessary when using connecting to an endpoint which has a non-standard root of trust, such as a protocol gateway. |
|
gateway_hostname
Required
|
Configuration Option. The gateway hostname for the gateway device. |
|
websockets
Required
|
Configuration Option. Default is False. Set to true if using MQTT over websockets. |
|
cipher
Required
|
Configuration Option. Cipher suite(s) for TLS/SSL, as a string in "OpenSSL cipher list format" or as a list of cipher suite strings. |
|
proxy_options
Required
|
Options for sending traffic through proxy servers. |
|
keepalive
Required
|
Maximum period in seconds between communications with the broker. If no other messages are being exchanged, this controls the rate at which the client will send ping messages to the broker. If not provided default value of 60 secs will be used. |
Returns
| Type | Description |
|---|---|
|
A ProvisioningDeviceClient which can register via X509 client certificates. |
Exceptions
| Type | Description |
|---|---|
|
TypeError if given an unrecognized parameter.
|
register
Register the device with the provisioning service
This is a synchronous call, meaning that this function will not return until the registration process has completed successfully or the attempt has resulted in a failure. Before returning, the client will also disconnect from the provisioning service. If a registration attempt is made while a previous registration is in progress it may throw an error.
Once the device is successfully registered, the client will no longer be operable.
register()Returns
| Type | Description |
|---|---|
|
RegistrationResult indicating the result of the registration. |
Exceptions
| Type | Description |
|---|---|
|
if credentials are invalid and a connection cannot be established. |
|
|
if establishing a connection results in failure. |
|
|
if connection is lost during execution. |
|
|
if the connection times out. |
|
|
if there is an unexpected failure during execution. |
Attributes
provisioning_payload
Azure SDK for Python
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for