public final class ProvisioningServiceClient extends Object
The IoT Hub Device Provisioning Service is a helper service for IoT Hub that enables automatic device provisioning to a specified IoT hub without requiring human intervention. You can use the Device Provisioning Service to provision millions of devices in a secure and scalable manner.
This java SDK provides an API to help developers to create and maintain Enrollments on the IoT Hub Device Provisioning Service, it translate the rest API in java Objects and Methods.
To use the this SDK, you must include the follow package on your application.
// Include the following imports to use the Device Provisioning Service APIs.
import com.microsoft.azure.sdk.iot.provisioning.service.*;
The main APIs are exposed by the ProvisioningServiceClient
, it contains the public Methods that the
application shall call to create and maintain the Enrollments. The Objects in the configs package shall
be filled and passed as parameters of the public API, for example, to create a new enrollment, the application
shall create the object IndividualEnrollment
with the appropriate enrollment configurations, and call the
createOrUpdateIndividualEnrollment(IndividualEnrollment)
.
The IoT Hub Device Provisioning Service supports SQL queries too. The application can create a new query using
one of the queries factories, for instance createIndividualEnrollmentQuery(QuerySpecification)
, passing
the QuerySpecification
, with the SQL query. This factory returns a Query
object, which is an
active iterator.
This java SDK can be represented in the follow diagram, the first layer are the public APIs the your application shall use:
+===============+ +==========================================+ +============+ +===+
| configs |------>| ProvisioningServiceClient | +->| Query | | |
+===============+ +==+=================+==================+==+ | +======+=====+ | e |
/ | \ | | | x |
/ | \ | | | c |
+-----------------------+-----+ +-----------+------------+ +-----+---------------------+ | | | e |
| IndividualEnrollmentManager | | EnrollmentGroupManager | | RegistrationStatusManager | | | | p |
+---------------+------+------+ +-----------+------+-----+ +-------------+-------+-----+ | | | t |
\ \ | \ | \ | | | i |
\ +----------------------------+------------------------------+------+ | | o |
\ | | | | n |
+--------+ +--+------------------------+-----------------------------+--------------------------+-----+ | s |
| auth |----->| ContractApiHttp | | |
+--------+ +-------------------------------------------+----------------------------------------------+ +===+
|
|
+-------------------------------------+------------------------------------------+
| com.microsoft.azure.sdk.iot.deps.transport.http |
+--------------------------------------------------------------------------------+
Constructor and Description |
---|
ProvisioningServiceClient(String connectionString)
Create a new instance of the
DeviceProvisioningServiceClient that exposes
the API to the Device Provisioning Service. |
Modifier and Type | Method and Description |
---|---|
Query |
createEnrollmentGroupQuery(QuerySpecification querySpecification)
Factory to create an enrollmentGroup query.
|
Query |
createEnrollmentGroupQuery(QuerySpecification querySpecification,
int pageSize)
Factory to create an enrollmentGroup query.
|
Query |
createEnrollmentGroupRegistrationStateQuery(QuerySpecification querySpecification,
String enrollmentGroupId)
Factory to create a registration status query.
|
Query |
createEnrollmentGroupRegistrationStateQuery(QuerySpecification querySpecification,
String enrollmentGroupId,
int pageSize)
Factory to create a registration status query.
|
static ProvisioningServiceClient |
createFromConnectionString(String connectionString)
Deprecated.
This static constructor works exactly the same as
ProvisioningServiceClient(String)
so it has been deprecated. |
Query |
createIndividualEnrollmentQuery(QuerySpecification querySpecification)
Factory to create a individualEnrollment query.
|
Query |
createIndividualEnrollmentQuery(QuerySpecification querySpecification,
int pageSize)
Factory to create a individualEnrollment query.
|
EnrollmentGroup |
createOrUpdateEnrollmentGroup(EnrollmentGroup enrollmentGroup)
Create or update an enrollment group record.
|
IndividualEnrollment |
createOrUpdateIndividualEnrollment(IndividualEnrollment individualEnrollment)
Create or update a individual Device Enrollment record.
|
void |
deleteDeviceRegistrationState(DeviceRegistrationState deviceRegistrationState)
Delete the Registration Status information.
|
void |
deleteDeviceRegistrationState(String id)
Delete the registration status information.
|
void |
deleteDeviceRegistrationState(String id,
String eTag)
Delete the registration status information.
|
void |
deleteEnrollmentGroup(EnrollmentGroup enrollmentGroup)
Delete the enrollmentGroup information.
|
void |
deleteEnrollmentGroup(String enrollmentGroupId)
Delete the enrollmentGroup information.
|
void |
deleteEnrollmentGroup(String enrollmentGroupId,
String eTag)
Delete the enrollmentGroup information.
|
void |
deleteIndividualEnrollment(IndividualEnrollment individualEnrollment)
Delete the individualEnrollment information.
|
void |
deleteIndividualEnrollment(String registrationId)
Delete the individualEnrollment information.
|
void |
deleteIndividualEnrollment(String registrationId,
String eTag)
Delete the individualEnrollment information.
|
DeviceRegistrationState |
getDeviceRegistrationState(String id)
Retrieve the registration status information.
|
EnrollmentGroup |
getEnrollmentGroup(String enrollmentGroupId)
Retrieve the enrollmentGroup information.
|
AttestationMechanism |
getEnrollmentGroupAttestationMechanism(String enrollmentGroupId)
Get the attestation mechanism details for a given enrollment group
|
IndividualEnrollment |
getIndividualEnrollment(String registrationId)
Retrieve the individualEnrollment information.
|
AttestationMechanism |
getIndividualEnrollmentAttestationMechanism(String registrationId)
Get the attestation mechanism details for a given individual enrollment
|
BulkEnrollmentOperationResult |
runBulkEnrollmentOperation(BulkOperationMode bulkOperationMode,
Collection<IndividualEnrollment> individualEnrollments)
Create, update or delete a set of individual Device Enrollments.
|
public ProvisioningServiceClient(String connectionString)
DeviceProvisioningServiceClient
that exposes
the API to the Device Provisioning Service.
The Device Provisioning Service Client is created based on a Provisioning Connection String.
Once you create a Device Provisioning Service on Azure, you can get the connection string on the Azure portal.
connectionString
- the String
that cares the connection string of the Device Provisioning Service.IllegalArgumentException
- if the connectionString is null
or empty.@Deprecated public static ProvisioningServiceClient createFromConnectionString(String connectionString)
ProvisioningServiceClient(String)
so it has been deprecated.DeviceProvisioningServiceClient
that exposes
the API to the Device Provisioning Service.
The Device Provisioning Service Client is created based on a Provisioning Connection String.
Once you create a Device Provisioning Service on Azure, you can get the connection string on the Azure portal.
connectionString
- the String
that cares the connection string of the Device Provisioning Service.ProvisioningServiceClient
with the new instance of this object.IllegalArgumentException
- if the connectionString is null
or empty.public IndividualEnrollment createOrUpdateIndividualEnrollment(IndividualEnrollment individualEnrollment) throws ProvisioningServiceClientException
This API creates a new individualEnrollment or update a existed one. All enrollments in the Device Provisioning Service contains a unique identifier called registrationId. If this API is called for an individualEnrollment with a registrationId that already exists, it will replace the existed individualEnrollment information by the new one. On the other hand, if the registrationId does not exit, this API will create a new individualEnrollment.
To use the Device Provisioning Service API, you must include the follow package on your application.
// Include the following imports to use the Device Provisioning Service APIs.
import com.microsoft.azure.sdk.iot.provisioning.service.*;
Sample:
The follow code will create a new individualEnrollment that will provisioning the ContosoDevice1000 to the ContosoHub.azure-devices.net using TPM attestation.
// IndividualEnrollment information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String TPM_ENDORSEMENT_KEY = "tpm-endorsement-key";
private static final String REGISTRATION_ID = "registrationId-1";
private static final String DEVICE_ID = "ContosoDevice1000";
private static final String IOTHUB_HOST_NAME = "ContosoHub.azure-devices.net";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Create a new individualEnrollment configurations.
Attestation attestation = new TpmAttestation(TPM_ENDORSEMENT_KEY);
IndividualEnrollment individualEnrollment =
new IndividualEnrollment(
REGISTRATION_ID,
attestation);
individualEnrollment.setDeviceId(DEVICE_ID);
individualEnrollment.setIotHubHostName(IOTHUB_HOST_NAME);
individualEnrollment.setProvisioningStatus(ProvisioningStatus.DISABLED);
// Create a new individualEnrollment.
IndividualEnrollment enrollmentResult = deviceProvisioningServiceClient.createOrUpdateIndividualEnrollment(individualEnrollment);
}
If the registrationId already exists, this method will update existed enrollments. Note that update the individualEnrollment will not change the status of the device that was already registered using the old individualEnrollment.
The follow code will update the provisioningStatus of the previous individualEnrollment from disabled to enabled.
// IndividualEnrollment information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String REGISTRATION_ID = "registrationId-1";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Get the content of the previous individualEnrollment.
IndividualEnrollment individualEnrollment = deviceProvisioningServiceClient.getIndividualEnrollment(REGISTRATION_ID);
// Change the provisioning status, from disabled to enabled
individualEnrollment.setProvisioningStatus(ProvisioningStatus.ENABLED);
// Update the individualEnrollment information.
IndividualEnrollment enrollmentResult = deviceProvisioningServiceClient.createOrUpdateIndividualEnrollment(individualEnrollment);
}
individualEnrollment
- the IndividualEnrollment
object that describes the individualEnrollment that will be created of
updated. It cannot be null
.IndividualEnrollment
object with the result of the create or update requested.IllegalArgumentException
- if the provided parameter is not correct.ProvisioningServiceClientTransportException
- if the SDK failed to send the request to the Device Provisioning Service.ProvisioningServiceClientException
- if the Device Provisioning Service was not able to create or update the individualEnrollment.public BulkEnrollmentOperationResult runBulkEnrollmentOperation(BulkOperationMode bulkOperationMode, Collection<IndividualEnrollment> individualEnrollments) throws ProvisioningServiceClientException
This API provide the means to do a single operation over multiple individualEnrollments. A valid operation
is determined by BulkOperationMode
, and can be 'create', 'update', 'updateIfMatchETag', or 'delete'.
To use the Device Provisioning Service API, you must include the follow package on your application.
// Include the following imports to use the Device Provisioning Service APIs.
import com.microsoft.azure.sdk.iot.provisioning.service.*;
Sample:
The follow code will create two new enrollment that will provisioning the ContosoDevice1000 and ContosoDevice1001 to the ContosoHub.azure-devices.net using TPM attestation.
// IndividualEnrollment information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String TPM_ENDORSEMENT_KEY = "tpm-endorsement-key";
private static final String IOTHUB_HOST_NAME = "ContosoHub.azure-devices.net";
private static final String REGISTRATION_ID_1 = "registrationId-1";
private static final String DEVICE_ID_1 = "ContosoDevice1000";
private static final String REGISTRATION_ID_2 = "registrationId-2";
private static final String DEVICE_ID_2 = "ContosoDevice1001";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Create two new individualEnrollment configurations.
Attestation attestation = new TpmAttestation(TPM_ENDORSEMENT_KEY);
IndividualEnrollment enrollment1 =
new IndividualEnrollment(
REGISTRATION_ID_1,
attestation);
enrollment1.setDeviceId(DEVICE_ID_1);
enrollment1.setIotHubHostName(IOTHUB_HOST_NAME);
enrollment1.setProvisioningStatus(ProvisioningStatus.DISABLED);
IndividualEnrollment enrollment2 =
new IndividualEnrollment(
REGISTRATION_ID_2,
attestation);
enrollment2.setDeviceId(DEVICE_ID_2);
enrollment2.setIotHubHostName(IOTHUB_HOST_NAME);
enrollment2.setProvisioningStatus(ProvisioningStatus.DISABLED);
// Add these 2 individualEnrollments to a list of individualEnrollments.
List<IndividualEnrollment> individualEnrollments = new LinkedList<>();
individualEnrollments.add(enrollment1);
individualEnrollments.add(enrollment2);
// Create these 2 new individualEnrollment using the bulk operation.
BulkEnrollmentOperationResult bulkEnrollmentOperationResult = provisioningServiceClient.runBulkEnrollmentOperation(BulkOperationMode.create, individualEnrollments);
}
bulkOperationMode
- the BulkOperationMode
that defines the single operation to do over the individualEnrollments. It cannot be null
.individualEnrollments
- the collection of IndividualEnrollment
that contains the description of each individualEnrollment. It cannot be null
or empty.BulkEnrollmentOperationResult
object with the result of operation for each enrollment.IllegalArgumentException
- if the provided parameters are not correct.ProvisioningServiceClientTransportException
- if the SDK failed to send the request to the Device Provisioning Service.ProvisioningServiceClientException
- if the Device Provisioning Service was not able to execute the bulk operation.public IndividualEnrollment getIndividualEnrollment(String registrationId) throws ProvisioningServiceClientException
This method will return the enrollment information for the provided registrationId. It will retrieve
the correspondent individualEnrollment from the Device Provisioning Service, and return it in the
IndividualEnrollment
object.
If the registrationId do not exists, this method will throw
ProvisioningServiceClientNotFoundException
.
for more exceptions that this method can throw, please see
ProvisioningServiceClientExceptionManager
Sample:
The follow code will get and print the information about the individualEnrollment "registrationId-1".
// IndividualEnrollment information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String REGISTRATION_ID = "registrationId-1";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Get the individualEnrollment information.
IndividualEnrollment enrollmentResult = deviceProvisioningServiceClient.getIndividualEnrollment(REGISTRATION_ID);
System.out.println(enrollmentResult.toString());
}
registrationId
- the String
that identifies the individualEnrollment. It cannot be null
or empty.IndividualEnrollment
with the content of the individualEnrollment in the Provisioning Device Service.IllegalArgumentException
- if the provided parameter is not correct.ProvisioningServiceClientTransportException
- if the SDK failed to send the request to the Device Provisioning Service.ProvisioningServiceClientException
- if the Device Provisioning Service was not able to execute the bulk operation.public AttestationMechanism getIndividualEnrollmentAttestationMechanism(String registrationId) throws ProvisioningServiceClientException
registrationId
- the registration id of the individual enrollment to look up the attestation mechanism forProvisioningServiceClientException
- if any exception is thrown while getting the attestation mechanismpublic void deleteIndividualEnrollment(IndividualEnrollment individualEnrollment) throws ProvisioningServiceClientException
This method will remove the individualEnrollment from the Device Provisioning Service using the
provided IndividualEnrollment
information. The Device Provisioning Service will care about the
registrationId and the eTag on the individualEnrollment. If you want to delete the individualEnrollment regardless the
eTag, you can set the eTag="*"
into the individualEnrollment, or use the deleteIndividualEnrollment(String)
passing only the registrationId.
Note that delete the individualEnrollment will not remove the Device itself from the IotHub.
If the registrationId does not exists or the eTag not matches, this method will throw
ProvisioningServiceClientNotFoundException
.
for more exceptions that this method can throw, please see
ProvisioningServiceClientExceptionManager
Sample:
The follow code will delete the information about the individualEnrollment "registrationId-1".
// IndividualEnrollment information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String REGISTRATION_ID = "registrationId-1";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Get the individualEnrollment information.
IndividualEnrollment enrollmentResult = deviceProvisioningServiceClient.getIndividualEnrollment(REGISTRATION_ID);
// Delete the individualEnrollment information.
deviceProvisioningServiceClient.deleteIndividualEnrollment(enrollmentResult);
}
individualEnrollment
- the IndividualEnrollment
that identifies the individualEnrollment. It cannot be null
.IllegalArgumentException
- if the provided parameter is not correct.ProvisioningServiceClientTransportException
- if the SDK failed to send the request to the Device Provisioning Service.ProvisioningServiceClientException
- if the Device Provisioning Service was not able to execute the bulk operation.public void deleteIndividualEnrollment(String registrationId) throws ProvisioningServiceClientException
This method will remove the individualEnrollment from the Device Provisioning Service using the
provided registrationId. It will delete the enrollment regardless the eTag. It means that this API
correspond to the deleteIndividualEnrollment(String, String)
with the eTag="*"
.
Note that delete the enrollment will not remove the Device itself from the IotHub.
If the registrationId does not exists, this method will throw
ProvisioningServiceClientNotFoundException
.
for more exceptions that this method can throw, please see
ProvisioningServiceClientExceptionManager
Sample:
The follow code will delete the information about the individualEnrollment "registrationId-1".
// IndividualEnrollment information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String REGISTRATION_ID = "registrationId-1";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Delete the individualEnrollment information.
deviceProvisioningServiceClient.deleteIndividualEnrollment(REGISTRATION_ID);
}
registrationId
- the String
that identifies the individualEnrollment. It cannot be null
or empty.IllegalArgumentException
- if the provided registrationId is not correct.ProvisioningServiceClientTransportException
- if the SDK failed to send the request to the Device Provisioning Service.ProvisioningServiceClientException
- if the Device Provisioning Service was not able to execute the bulk operation.public void deleteIndividualEnrollment(String registrationId, String eTag) throws ProvisioningServiceClientException
This method will remove the individualEnrollment from the Device Provisioning Service using the
provided registrationId and eTag. If you want to delete the enrollment regardless the eTag, you can
use deleteIndividualEnrollment(String)
or you can pass the eTag as null
, empty, or
"*"
.
Note that delete the enrollment will not remove the Device itself from the IotHub.
If the registrationId does not exists or the eTag does not matches, this method will throw
ProvisioningServiceClientNotFoundException
.
for more exceptions that this method can throw, please see
ProvisioningServiceClientExceptionManager
Sample:
The follow code will delete the information about the individualEnrollment "registrationId-1" regardless the eTag.
// IndividualEnrollment information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String REGISTRATION_ID = "registrationId-1";
private Static final String ANY_ETAG = "*";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Delete the individualEnrollment information.
deviceProvisioningServiceClient.deleteIndividualEnrollment(REGISTRATION_ID, ANY_ETAG);
}
registrationId
- the String
that identifies the individualEnrollment. It cannot be null
or empty.eTag
- the String
with the IndividualEnrollment eTag. It can be null
or empty.
The Device Provisioning Service will ignore it in all of these cases.IllegalArgumentException
- if the provided registrationId is not correct.ProvisioningServiceClientTransportException
- if the SDK failed to send the request to the Device Provisioning Service.ProvisioningServiceClientException
- if the Device Provisioning Service was not able to execute the bulk operation.public Query createIndividualEnrollmentQuery(QuerySpecification querySpecification)
This method will create a new individualEnrollment query for Device Provisioning Service and return it
as a Query
iterator.
The Device Provisioning Service expects a SQL query in the QuerySpecification
, for instance
"SELECT * FROM enrollments"
.
querySpecification
- the QuerySpecification
with the SQL query. It cannot be null
.Query
iterator.IllegalArgumentException
- if the provided parameter is not correct.public Query createIndividualEnrollmentQuery(QuerySpecification querySpecification, int pageSize)
This method will create a new individualEnrollment query for Device Provisioning Service and return it
as a Query
iterator.
The Device Provisioning Service expects a SQL query in the QuerySpecification
, for instance
"SELECT * FROM enrollments"
.
For each iteration, the Query will return a List of objects correspondent to the query result. The maximum
number of items per iteration can be specified by the pageSize. It is optional, you can provide 0 for
default pageSize or use the API createIndividualEnrollmentQuery(QuerySpecification)
.
querySpecification
- the QuerySpecification
with the SQL query. It cannot be null
.pageSize
- the int
with the maximum number of items per iteration. It can be 0 for default, but not negative.Query
iterator.IllegalArgumentException
- if the provided parameters are not correct.public EnrollmentGroup createOrUpdateEnrollmentGroup(EnrollmentGroup enrollmentGroup) throws ProvisioningServiceClientException
This API creates a new enrollment group or update a existed one. All enrollment group in the Device Provisioning Service contains a unique identifier called enrollmentGroupId. If this API is called with an enrollmentGroupId that already exists, it will replace the existed enrollmentGroup information by the new one. On the other hand, if the enrollmentGroupId does not exit, it will be created.
To use the Device Provisioning Service API, you must include the follow package on your application.
// Include the following imports to use the Device Provisioning Service APIs.
import com.microsoft.azure.sdk.iot.provisioning.service.*;
Sample:
The follow code will create a new enrollmentGroup that will provisioning multiple devices to the ContosoHub.azure-devices.net.
// EnrollmentGroup information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String ENROLLMENT_GROUP_ID = "enrollmentGroupId-1";
private static final String IOTHUB_HOST_NAME = "ContosoHub.azure-devices.net";
private static String PUBLIC_CERTIFICATE_STRING =
"-----BEGIN CERTIFICATE-----\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"-----END CERTIFICATE-----\n";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Create a new enrollmentGroup configurations.
Attestation attestation = X509Attestation.createFromSigningCertificates(PUBLIC_KEY_CERTIFICATE_STRING);
EnrollmentGroup enrollmentGroup =
new EnrollmentGroup(
enrollmentGroupId,
attestation);
enrollmentGroup.setIotHubHostName(IOTHUB_HOST_NAME);
enrollmentGroup.setProvisioningStatus(ProvisioningStatus.ENABLED);
// Create a new enrollmentGroup.
EnrollmentGroup enrollmentGroupResult = provisioningServiceClient.createOrUpdateEnrollmentGroup(enrollmentGroup);
}
enrollmentGroup
- the EnrollmentGroup
object that describes the individualEnrollment that will be created of updated.EnrollmentGroup
object with the result of the create or update requested.ProvisioningServiceClientException
- if the Provisioning was not able to create or update the enrollmentpublic EnrollmentGroup getEnrollmentGroup(String enrollmentGroupId) throws ProvisioningServiceClientException
This method will return the enrollmentGroup information for the provided enrollmentGroupId. It will retrieve
the correspondent enrollmentGroup from the Device Provisioning Service, and return it in the
EnrollmentGroup
object.
If the enrollmentGroupId does not exists, this method will throw
ProvisioningServiceClientNotFoundException
.
for more exceptions that this method can throw, please see
ProvisioningServiceClientExceptionManager
Sample:
The follow code will get and print the information about the enrollmentGroupId "enrollmentGroupId-1".
// EnrollmentGroup information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String ENROLLMENT_GROUP_ID = "enrollmentGroupId-1";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Get the individualEnrollment information.
EnrollmentGroup enrollmentGroupResult = deviceProvisioningServiceClient.getEnrollmentGroup(ENROLLMENT_GROUP_ID);
System.out.println(enrollmentGroupResult.toString());
}
enrollmentGroupId
- the String
that identifies the enrollmentGroup. It cannot be null
or empty.EnrollmentGroup
with the content of the enrollmentGroup in the Provisioning Device Service.ProvisioningServiceClientException
- if the Provisioning Device Service was not able to retrieve the
enrollmentGroup information for the provided enrollmentGroupId.public AttestationMechanism getEnrollmentGroupAttestationMechanism(String enrollmentGroupId) throws ProvisioningServiceClientException
enrollmentGroupId
- the group id of the enrollment group to look up the attestation mechanism forProvisioningServiceClientException
- if any exception is thrown while getting the attestation mechanismpublic void deleteEnrollmentGroup(EnrollmentGroup enrollmentGroup) throws ProvisioningServiceClientException
This method will remove the enrollmentGroup from the Device Provisioning Service using the
provided EnrollmentGroup
information. The Device Provisioning Service will care about the
enrollmentGroupId and the eTag on the enrollmentGroup. If you want to delete the enrollment regardless the
eTag, you can set the eTag="*"
into the enrollmentGroup, or use the deleteEnrollmentGroup(String)
passing only the enrollmentGroupId.
Note that delete the enrollmentGroup will not remove the Devices itself from the IotHub.
If the enrollmentGroupId does not exists or the eTag does not matches, this method will throw
ProvisioningServiceClientNotFoundException
.
for more exceptions that this method can throw, please see
ProvisioningServiceClientExceptionManager
Sample:
The follow code will delete the information about the enrollmentGroup "enrollmentGroupId-1".
// EnrollmentGroup information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String ENROLLMENT_GROUP_ID = "enrollmentGroupId-1";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Get the enrollmentGroup information.
EnrollmentGroup enrollmentGroupResult = deviceProvisioningServiceClient.getEnrollmentGroup(ENROLLMENT_GROUP_ID);
// Delete the enrollmentGroup information.
deviceProvisioningServiceClient.deleteEnrollmentGroup(enrollmentResult);
}
enrollmentGroup
- the EnrollmentGroup
that identifies the enrollmentGroup. It cannot be null
.ProvisioningServiceClientException
- if the Provisioning Device Service was not able to delete the
enrollmentGroup information for the provided enrollmentGroup.public void deleteEnrollmentGroup(String enrollmentGroupId) throws ProvisioningServiceClientException
This method will remove the enrollmentGroup from the Device Provisioning Service using the
provided enrollmentGroupId. It will delete the enrollmentGroup regardless the eTag. It means that this API
correspond to the deleteEnrollmentGroup(String, String)
with the eTag="*"
.
Note that delete the enrollmentGroup will not remove the Devices itself from the IotHub.
If the enrollmentGroupId does not exists, this method will throw
ProvisioningServiceClientNotFoundException
.
for more exceptions that this method can throw, please see
ProvisioningServiceClientExceptionManager
Sample:
The follow code will delete the information about the enrollmentGroup "enrollmentGroupId-1".
// EnrollmentGroup information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String ENROLLMENT_GROUP_ID = "enrollmentGroupId-1";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Delete the enrollmentGroup information.
deviceProvisioningServiceClient.deleteEnrollmentGroup(ENROLLMENT_GROUP_ID);
}
enrollmentGroupId
- the String
that identifies the enrollmentGroup. It cannot be null
or empty.ProvisioningServiceClientException
- if the Provisioning Device Service was not able to delete the
enrollmentGroup information for the provided enrollmentGroupId.public void deleteEnrollmentGroup(String enrollmentGroupId, String eTag) throws ProvisioningServiceClientException
This method will remove the enrollmentGroup from the Device Provisioning Service using the
provided enrollmentGroupId and eTag. If you want to delete the enrollmentGroup regardless the eTag, you can
use deleteEnrollmentGroup(String)
or you can pass the eTag as null
, empty, or
"*"
.
Note that delete the enrollmentGroup will not remove the Device itself from the IotHub.
If the enrollmentGroupId does not exists or eTag does not matches, this method will throw
ProvisioningServiceClientNotFoundException
.
for more exceptions that this method can throw, please see
ProvisioningServiceClientExceptionManager
Sample:
The follow code will delete the information about the enrollmentGroup "enrollmentGroupId-1" regardless the eTag.
// enrollmentGroup information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String ENROLLMENT_GROUP_ID = "enrollmentGroupId-1";
private Static final String ANY_ETAG = "*";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Delete the enrollmentGroup information.
deviceProvisioningServiceClient.deleteEnrollmentGroup(ENROLLMENT_GROUP_ID, ANY_ETAG);
}
enrollmentGroupId
- the String
that identifies the enrollmentGroup. It cannot be null
or empty.eTag
- the String
with the enrollmentGroup eTag. It can be null
or empty.
The Device Provisioning Service will ignore it in all of these cases.ProvisioningServiceClientException
- if the Provisioning Device Service was not able to delete the
enrollmentGroup information for the provided enrollmentGroupId and eTag.public Query createEnrollmentGroupQuery(QuerySpecification querySpecification)
This method will create a new enrollment group query on Device Provisioning Service and return it as
a Query
iterator.
The Device Provisioning Service expects a SQL query in the QuerySpecification
, for instance
"SELECT * FROM enrollments"
.
querySpecification
- the QuerySpecification
with the SQL query. It cannot be null
.Query
iterator.IllegalArgumentException
- if the provided parameter is not correct.public Query createEnrollmentGroupQuery(QuerySpecification querySpecification, int pageSize)
This method will create a new enrollment group query on Device Provisioning Service and return it as
a Query
iterator.
The Device Provisioning Service expects a SQL query in the QuerySpecification
, for instance
"SELECT * FROM enrollments"
.
For each iteration, the Query will return a List of objects correspondent to the query result. The maximum
number of items per iteration can be specified by the pageSize. It is optional, you can provide 0 for
default pageSize or use the API createEnrollmentGroupQuery(QuerySpecification)
.
querySpecification
- the QuerySpecification
with the SQL query. It cannot be null
.pageSize
- the int
with the maximum number of items per iteration. It can be 0 for default, but not negative.Query
iterator.IllegalArgumentException
- if the provided parameters are not correct.public DeviceRegistrationState getDeviceRegistrationState(String id) throws ProvisioningServiceClientException
This method will return the DeviceRegistrationState
for the provided id. It will retrieve
the correspondent deviceRegistrationState from the Device Provisioning Service, and return it in the
DeviceRegistrationState
object.
If the id do not exists, this method will throw
ProvisioningServiceClientNotFoundException
.
for more exceptions that this method can throw, please see
ProvisioningServiceClientExceptionManager
Sample:
The follow code will get and print the information about the deviceRegistrationState "registrationId-1".
// Registration status information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String REGISTRATION_ID = "registrationId-1";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Get the deviceRegistrationState information.
DeviceRegistrationState registrationStateResult = deviceProvisioningServiceClient.getDeviceRegistrationState(REGISTRATION_ID);
System.out.println(registrationStateResult.toString());
}
id
- the String
that identifies the deviceRegistrationState. It cannot be null
or empty.DeviceRegistrationState
with the content of the deviceRegistrationState in the Provisioning Device Service.ProvisioningServiceClientException
- if the Provisioning Device Service was not able to retrieve the
deviceRegistrationState information for the provided registrationId.public void deleteDeviceRegistrationState(DeviceRegistrationState deviceRegistrationState) throws ProvisioningServiceClientException
This method will remove the DeviceRegistrationState
from the Device Provisioning Service using the
provided DeviceRegistrationState
information. The Device Provisioning Service will care about the
id and the eTag on the DeviceRegistrationState. If you want to delete the deviceRegistrationState regardless the
eTag, you can use the deleteDeviceRegistrationState(String)
passing only the id.
If the id does not exists or the eTag does not matches, this method will throw
ProvisioningServiceClientNotFoundException
.
for more exceptions that this method can throw, please see
ProvisioningServiceClientExceptionManager
Sample:
The follow code will delete the information about the deviceRegistrationState "registrationId-1".
// Registration Status information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String REGISTRATION_ID = "registrationId-1";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Get the registration status information.
DeviceRegistrationState registrationStateResult = deviceProvisioningServiceClient.getDeviceRegistrationState(REGISTRATION_ID);
// Delete the registration status information.
deviceProvisioningServiceClient.deleteDeviceRegistrationState(registrationStateResult);
}
deviceRegistrationState
- the DeviceRegistrationState
that identifies the deviceRegistrationState. It cannot be null
.ProvisioningServiceClientException
- if the Provisioning Device Service was not able to delete the
registration status information for the provided DeviceRegistrationState.public void deleteDeviceRegistrationState(String id) throws ProvisioningServiceClientException
This method will remove the DeviceRegistrationState
from the Device Provisioning Service using the
provided id. It will delete the registration status regardless the eTag. It means that this API
correspond to the deleteDeviceRegistrationState(String, String)
with the eTag="*"
.
If the id does not exists, this method will throw
ProvisioningServiceClientNotFoundException
.
for more exceptions that this method can throw, please see
ProvisioningServiceClientExceptionManager
Sample:
The follow code will delete the information about the registration status "registrationId-1".
// deviceRegistrationState information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String REGISTRATION_ID = "registrationId-1";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Delete the registration status information.
deviceProvisioningServiceClient.deleteDeviceRegistrationState(REGISTRATION_ID);
}
id
- the String
that identifies the deviceRegistrationState. It cannot be null
or empty.ProvisioningServiceClientException
- if the Provisioning Device Service was not able to delete the
deviceRegistrationState information for the provided registrationId.public void deleteDeviceRegistrationState(String id, String eTag) throws ProvisioningServiceClientException
This method will remove the registration status from the Device Provisioning Service using the
provided id and eTag. If you want to delete the registration status regardless the eTag, you can
use deleteDeviceRegistrationState(String)
or you can pass the eTag as null
, empty, or
"*"
.
If the id does not exists or the eTag does not matches, this method will throw
ProvisioningServiceClientNotFoundException
.
for more exceptions that this method can throw, please see
ProvisioningServiceClientExceptionManager
Sample:
The follow code will delete the information about the deviceRegistrationState "registrationId-1" regardless the eTag.
// Registration Status information.
private static final String PROVISIONING_CONNECTION_STRING = "HostName=ContosoProvisioning.azure-devices-provisioning.net;" +
"SharedAccessKeyName=contosoprovisioningserviceowner;" +
"SharedAccessKey=0000000000000000000000000000000000000000000=";
private static final String REGISTRATION_ID = "registrationId-1";
private Static final String ANY_ETAG = "*";
public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningServiceClientException
{
// Create a Device Provisioning Service Client.
DeviceProvisioningServiceClient deviceProvisioningServiceClient =
new ProvisioningServiceClient(PROVISIONING_CONNECTION_STRING);
// Delete the deviceRegistrationState information.
deviceProvisioningServiceClient.deleteDeviceRegistrationState(REGISTRATION_ID, ANY_ETAG);
}
id
- the String
that identifies the deviceRegistrationState. It cannot be null
or empty.eTag
- the String
with the deviceRegistrationState eTag. It can be null
or empty.
The Device Provisioning Service will ignore it in all of these cases.ProvisioningServiceClientException
- if the Provisioning Device Service was not able to delete the
deviceRegistrationState information for the provided registrationId and eTag.public Query createEnrollmentGroupRegistrationStateQuery(QuerySpecification querySpecification, String enrollmentGroupId)
This method will create a new registration status query for a specific enrollment group on the Device
Provisioning Service and return it as a Query
iterator.
The Device Provisioning Service expects a SQL query in the QuerySpecification
, for instance
"SELECT * FROM enrollments"
.
querySpecification
- the QuerySpecification
with the SQL query. It cannot be null
.enrollmentGroupId
- the String
that identifies the enrollmentGroup. It cannot be null
or empty.Query
iterator.public Query createEnrollmentGroupRegistrationStateQuery(QuerySpecification querySpecification, String enrollmentGroupId, int pageSize)
This method will create a new registration status query for a specific enrollment group on the Device
Provisioning Service and return it as a Query
iterator.
The Device Provisioning Service expects a SQL query in the QuerySpecification
, for instance
"SELECT * FROM enrollments"
.
For each iteration, the Query will return a List of objects correspondent to the query result. The maximum
number of items per iteration can be specified by the pageSize. It is optional, you can provide 0 for
default pageSize or use the API createIndividualEnrollmentQuery(QuerySpecification)
.
querySpecification
- the QuerySpecification
with the SQL query. It cannot be null
.enrollmentGroupId
- the String
that identifies the enrollmentGroup. It cannot be null
or empty.pageSize
- the int
with the maximum number of items per iteration. It can be 0 for default, but not negative.Query
iterator.IllegalArgumentException
- if the provided parameters are not correct.Copyright © 2022. All rights reserved.