Enrollment Group - Run Bulk Operation

Service:

IoT Hub Device Provisioning Service

API Version:

2021-10-01

Bulk device enrollment group operation with maximum of 10 groups.

POST https://your-dps.azure-devices-provisioning.net/enrollmentGroups?api-version=2021-10-01

URI Parameters

Name	In	Required	Type	Description
api-version	query	True	string	The API version to use for the request. Supported versions include: 2021-10-01

Request Body

Name	Required	Type	Description
enrollmentGroups	True	EnrollmentGroup[]	Enrollment items
mode	True	enum: create update updateIfMatchETag delete	Operation mode.

Responses

Name	Type	Description
200 OK	BulkEnrollmentGroupOperationResult	Success
Other Status Codes	ProvisioningServiceErrorDetails	Error response Headers x-ms-error-code: string

Definitions

Name	Description
AttestationMechanism	Attestation mechanism for individualEnrollment as well as enrollmentGroup.
BulkEnrollmentGroupOperation	Bulk enrollment operation.
BulkEnrollmentGroupOperationError	Bulk enrollment operation error.
BulkEnrollmentGroupOperationResult	Results of a bulk enrollment group operation.
CustomAllocationDefinition	This tells DPS which webhook to call when using custom allocation.
DeviceCapabilities	Device capabilities.
EnrollmentGroup	Enrollment group record.
InitialTwin	Initial device twin. Contains a subset of the properties of Twin.
InitialTwinProperties	Represents the initial properties that will be set on the device twin.
Metadata	Metadata for the TwinCollection
ProvisioningServiceErrorDetails	Contains the properties of an error returned by the Azure IoT Hub Provisioning Service.
ReprovisionPolicy	The behavior of the service when a device is re-provisioned to an IoT hub.
SymmetricKeyAttestation	Attestation via SymmetricKey.
TpmAttestation	Attestation via TPM.
TwinCollection	Represents a collection of properties within a Twin
X509Attestation	Attestation via X509.
X509CAReferences	Primary and secondary CA references.
X509CertificateInfo	X509 certificate info.
X509Certificates	Primary and secondary certificates
X509CertificateWithInfo	Certificate and Certificate info

AttestationMechanism

Attestation mechanism for individualEnrollment as well as enrollmentGroup.

Name	Type	Description
symmetricKey	SymmetricKeyAttestation	Attestation via SymmetricKey.
tpm	TpmAttestation	Attestation via TPM.
type	enum: none symmetricKey tpm x509	Attestation Type.
x509	X509Attestation	Attestation via X509.

BulkEnrollmentGroupOperation

Bulk enrollment operation.

Name	Type	Description
enrollmentGroups	EnrollmentGroup[]	Enrollment items
mode	enum: create delete update updateIfMatchETag	Operation mode.

BulkEnrollmentGroupOperationError

Bulk enrollment operation error.

Name	Type	Description
enrollmentGroupId	string	Enrollment group id.
errorCode	integer	Error code
errorStatus	string	Error status.

BulkEnrollmentGroupOperationResult

Results of a bulk enrollment group operation.

Name	Type	Description
errors	BulkEnrollmentGroupOperationError[]	Registration errors
isSuccessful	boolean	Indicates if the operation was successful in its entirety.

CustomAllocationDefinition

This tells DPS which webhook to call when using custom allocation.

Name	Type	Description
apiVersion	string	The API version of the provisioning service types (such as IndividualEnrollment) sent in the custom allocation request. Minimum supported version: "2018-09-01-preview".
webhookUrl	string	The webhook URL used for allocation requests.

DeviceCapabilities

Device capabilities.

Name	Type	Default value	Description
iotEdge	boolean	False	If set to true, this device is an IoTEdge device.

EnrollmentGroup

Enrollment group record.

Name	Type	Default value	Description
allocationPolicy	enum: custom geoLatency hashed static		The allocation policy of this resource. This policy overrides the tenant level allocation policy for this individual enrollment or enrollment group. Possible values include 'hashed': Linked IoT hubs are equally likely to have devices provisioned to them, 'geoLatency': Devices are provisioned to an IoT hub with the lowest latency to the device.If multiple linked IoT hubs would provide the same lowest latency, the provisioning service hashes devices across those hubs, 'static' : Specification of the desired IoT hub in the enrollment list takes priority over the service-level allocation policy, 'custom': Devices are provisioned to an IoT hub based on your own custom logic. The provisioning service passes information about the device to the logic, and the logic returns the desired IoT hub as well as the desired initial configuration. We recommend using Azure Functions to host your logic.
attestation	AttestationMechanism		Attestation mechanism for individualEnrollment as well as enrollmentGroup.
capabilities	DeviceCapabilities		Device capabilities.
createdDateTimeUtc	string		The DateTime this resource was created.
customAllocationDefinition	CustomAllocationDefinition		This tells DPS which webhook to call when using custom allocation.
enrollmentGroupId	string		Enrollment Group ID.
etag	string		The entity tag associated with the resource.
initialTwin	InitialTwin		Initial device twin. Contains a subset of the properties of Twin.
iotHubHostName	string		The Iot Hub host name.
iotHubs	string[]		The list of IoT Hub hostnames the device(s) in this resource can be allocated to. Must be a subset of tenant level list of IoT hubs.
lastUpdatedDateTimeUtc	string		The DateTime this resource was last updated.
provisioningStatus	enum: disabled enabled	enabled	The provisioning status.
reprovisionPolicy	ReprovisionPolicy		The behavior of the service when a device is re-provisioned to an IoT hub.

InitialTwin

Initial device twin. Contains a subset of the properties of Twin.

Name	Type	Description
properties	InitialTwinProperties	Represents the initial properties that will be set on the device twin.
tags	TwinCollection	Represents a collection of properties within a Twin

InitialTwinProperties

Represents the initial properties that will be set on the device twin.

Name	Type	Description
desired	TwinCollection	Represents a collection of properties within a Twin

Metadata

Metadata for the TwinCollection

Name	Type	Description
lastUpdated	string	Last time the TwinCollection was updated
lastUpdatedVersion	integer	This is null for reported properties metadata and is not null for desired properties metadata.

ProvisioningServiceErrorDetails

Contains the properties of an error returned by the Azure IoT Hub Provisioning Service.

Name	Type	Description
errorCode	integer
info	object
message	string
timestampUtc	string
trackingId	string

ReprovisionPolicy

The behavior of the service when a device is re-provisioned to an IoT hub.

Name	Type	Default value	Description
migrateDeviceData	boolean	True	When set to true (default), the Device Provisioning Service will migrate the device's data (twin, device capabilities, and device ID) from one IoT hub to another during an IoT hub assignment update. If set to false, the Device Provisioning Service will reset the device's data to the initial desired configuration stored in the corresponding enrollment list.
updateHubAssignment	boolean	True	When set to true (default), the Device Provisioning Service will evaluate the device's IoT Hub assignment and update it if necessary for any provisioning requests beyond the first from a given device. If set to false, the device will stay assigned to its current IoT hub.

SymmetricKeyAttestation

Attestation via SymmetricKey.

Name	Type	Description
primaryKey	string	Primary symmetric key.
secondaryKey	string	Secondary symmetric key.

TpmAttestation

Attestation via TPM.

Name	Type	Description
endorsementKey	string
storageRootKey	string

TwinCollection

Represents a collection of properties within a Twin

Name	Type	Description
count	integer	Number of properties in the TwinCollection
metadata	Metadata	Metadata for the TwinCollection
version	integer	Version of the TwinCollection

X509Attestation

Attestation via X509.

Name	Type	Description
caReferences	X509CAReferences	Primary and secondary CA references.
clientCertificates	X509Certificates	Primary and secondary certificates
signingCertificates	X509Certificates	Primary and secondary certificates

X509CAReferences

Primary and secondary CA references.

Name	Type	Description
primary	string
secondary	string

X509CertificateInfo

X509 certificate info.

Name	Type	Description
issuerName	string
notAfterUtc	string
notBeforeUtc	string
serialNumber	string
sha1Thumbprint	string
sha256Thumbprint	string
subjectName	string
version	integer

X509Certificates

Primary and secondary certificates

Name	Type	Description
primary	X509CertificateWithInfo	Certificate and Certificate info
secondary	X509CertificateWithInfo	Certificate and Certificate info

X509CertificateWithInfo

Certificate and Certificate info

Name	Type	Description
certificate	string
info	X509CertificateInfo	X509 certificate info.