Service - Bulk Create Or Update Devices

Create, update, or delete the identities of multiple devices from the IoT hub identity registry.
Create, update, or delete the identiies of multiple devices from the IoT hub 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).

POST https://fully-qualified-iothubname.azure-devices.net/devices?api-version=2018-06-30

URI Parameters

Name In Required Type Description
api-version
query True
  • string

Version of the Api.

Request Body

Name Type Description
authentication

Authentication parameter is optional and defaults to SAS if not provided. In that case, we auto-generate primary/secondary access keys

capabilities

Capabilities param is optional and defaults to no capability

eTag
  • string

ETag parameter is only used for pre-conditioning the update when importMode is updateIfMatchETag

id
  • string

Device Id is always required

importMode enum:
  • create
  • update
  • updateIfMatchETag
  • delete
  • deleteIfMatchETag
  • updateTwin
  • updateTwinIfMatchETag
moduleId
  • string

ModuleId is applicable to modules only

properties

Properties are optional and defaults to empty object

status enum:
  • enabled
  • disabled

Status is optional and defaults to enabled

statusReason
  • string
tags
  • object
twinETag
  • string

twinETag parameter is only used for pre-conditioning the update when importMode is updateTwinIfMatchETag

Responses

Name Type Description
200 OK

OK

400 Bad Request

BadRequest

Definitions

AuthenticationMechanism
BulkRegistryOperationResult

Encapsulates the result of a bulk registry operation.

DeviceCapabilities

Status of Capabilities enabled on the device

DeviceRegistryOperationError

Encapsulates device registry operation error details.

DeviceRegistryOperationWarning

Encapsulates device registry operation error details.

ExportImportDevice
PropertyContainer

Represents Twin properties

SymmetricKey
X509Thumbprint

AuthenticationMechanism

Name Type Description
symmetricKey
type enum:
  • certificateAuthority
  • none
  • sas
  • selfSigned
x509Thumbprint

BulkRegistryOperationResult

Encapsulates the result of a bulk registry operation.

Name Type Description
errors

If the operation was not successful, this contains an array of DeviceRegistryOperationError objects.

isSuccessful
  • boolean

Whether or not the operation was successful.

warnings

If the operation was partially successful, this contains an array of DeviceRegistryOperationWarning objects.

DeviceCapabilities

Status of Capabilities enabled on the device

Name Type Description
iotEdge
  • boolean

DeviceRegistryOperationError

Encapsulates device registry operation error details.

Name Type Description
deviceId
  • string

The ID of the device that indicated the error.

errorCode enum:
  • AmqpAddressNotFound
  • ApplyConfigurationAlreadyInProgressOnDevice
  • ArgumentInvalid
  • ArgumentNull
  • AsyncOperationNotFound
  • AzureStorageTimeout
  • AzureTableStoreError
  • AzureTableStoreNotFound
  • BackupTimedOut
  • BlobContainerValidationError
  • BulkAddDevicesNotSupported
  • BulkRegistryOperationFailure
  • CallbackSubscriptionConflict
  • CannotModifyImmutableConfigurationContent
  • CannotRegisterModuleToModule
  • CertificateNotFound
  • CheckpointStoreNotFound
  • ConfigReadFailed
  • ConfigurationAlreadyExists
  • ConfigurationCountLimitExceeded
  • ConfigurationNotAvailable
  • ConfigurationNotFound
  • ConnectionForcefullyClosed
  • ConnectionForcefullyClosedOnNewConnection
  • ConnectionUnavailable
  • CustomAllocationFailed
  • CustomAllocationIotHubNotSpecified
  • CustomAllocationUnauthorizedAccess
  • DefaultStorageEndpointNotConfigured
  • DeserializationError
  • DeviceAlreadyExists
  • DeviceConnectionClosedRemotely
  • DeviceDefinedMultipleTimes
  • DeviceInvalidResultCount
  • DeviceJobAlreadyExists
  • DeviceLocked
  • DeviceMaximumActiveFileUploadLimitExceeded
  • DeviceMaximumQueueDepthExceeded
  • DeviceMaximumQueueSizeExceeded
  • DeviceMessageLockLost
  • DeviceModelMaxIndexablePropertiesExceeded
  • DeviceModelMaxPropertiesExceeded
  • DeviceNotFound
  • DeviceNotOnline
  • DeviceRegistrationNotFound
  • DeviceStorageEntitySerializationError
  • DeviceUnavailable
  • DocumentDbInvalidReturnValue
  • ElasticPoolNotFound
  • ElasticPoolTenantHubNotFound
  • EnrollmentConflict
  • EnrollmentGroupConflict
  • EnrollmentGroupNotFound
  • EnrollmentNotFound
  • EtagDoesNotMatch
  • EventHubLinkAlreadyClosed
  • ExpiredFileUploadCorrelationId
  • FeatureNotSupported
  • GatewayTimeout
  • GenericBadGateway
  • GenericBadRequest
  • GenericConflict
  • GenericForbidden
  • GenericGatewayTimeout
  • GenericMethodNotAllowed
  • GenericNotFound
  • GenericPreconditionFailed
  • GenericRequestEntityTooLarge
  • GenericServerError
  • GenericServiceUnavailable
  • GenericTimeout
  • GenericTooManyRequests
  • GenericUnauthorized
  • GenericUnsupportedMediaType
  • GroupNotAvailable
  • GroupNotFound
  • ImportDevicesNotSupported
  • ImportWarningExistsError
  • IncompatibleDataType
  • InflightMessagesInLink
  • InvalidBlobState
  • InvalidConfigurationContent
  • InvalidConfigurationCustomMetricsQuery
  • InvalidConfigurationTargetCondition
  • InvalidContainerReceiveLink
  • InvalidDeviceScope
  • InvalidEndorsementKey
  • InvalidEnrollmentGroupId
  • InvalidErrorCode
  • InvalidFileUploadCompletionStatus
  • InvalidFileUploadCorrelationId
  • InvalidMessageExpiryTime
  • InvalidMessagingEndpoint
  • InvalidOperation
  • InvalidPartitionEpoch
  • InvalidPnPDesiredProperties
  • InvalidPnPInterfaceDefinition
  • InvalidPnPReportedProperties
  • InvalidPnPWritableReportedProperties
  • InvalidProtocolVersion
  • InvalidRegistrationId
  • InvalidResponseWhileProxying
  • InvalidRouteTestInput
  • InvalidSchemaVersion
  • InvalidSourceOnRoute
  • InvalidStorageEndpoint
  • InvalidStorageEndpointOrBlob
  • InvalidStorageEndpointProperty
  • InvalidStorageRootKey
  • InvalidThrottleParameter
  • IotDpsSuspended
  • IotDpsSuspending
  • IotHubActivationFailed
  • IotHubFailingOver
  • IotHubFormatError
  • IotHubMaxCbsTokenExceeded
  • IotHubNotFound
  • IotHubQuotaExceeded
  • IotHubRestoring
  • IotHubSuspended
  • IotHubUnauthorized
  • IotHubUnauthorizedAccess
  • JobAlreadyExists
  • JobCancelled
  • JobNotFound
  • JobQuotaExceeded
  • JobRunPreconditionFailed
  • LinkCreationConflict
  • MessageTooLarge
  • ModelAlreadyExists
  • ModuleAlreadyExistsOnDevice
  • ModuleNotFound
  • NullMessage
  • OperationNotAllowedInCurrentState
  • OperationNotAvailableInCurrentTier
  • OrchestrationOperationFailed
  • PartitionNotFound
  • PreconditionFailed
  • QueryStoreClusterNotFound
  • QuotaMetricNotFound
  • ReceiveLinkOpensThrottled
  • RegistrationIdDefinedMultipleTimes
  • RegistrationStatusConflict
  • ReliableBlobStoreError
  • ReliableBlobStoreTimeoutError
  • ReliableDocDbStoreStoreError
  • RequestCanceled
  • RequestTimedOut
  • RestoreTimedOut
  • RetryAttemptsExhausted
  • RoutingEndpointResponseForbidden
  • RoutingEndpointResponseNotFound
  • RoutingNotEnabled
  • ServerBusy
  • ServerError
  • ServiceUnavailable
  • StatisticsRetrievalError
  • StreamReservationFailure
  • SystemModuleModifyUnauthorizedAccess
  • SystemPropertyNotFound
  • TenantHubRoutingNotEnabled
  • ThrottleBacklogLimitExceeded
  • ThrottlingBacklogTimeout
  • ThrottlingException
  • ThrottlingMaxActiveJobCountExceeded
  • TooManyDevices
  • TooManyEnrollments
  • TooManyModulesOnDevice
  • UnexpectedPropertyValue
  • UnsupportedOperationOnReplica

ErrorCode associated with the error.

errorStatus
  • string

Additional details associated with the error.

moduleId
  • string
operation
  • string

DeviceRegistryOperationWarning

Encapsulates device registry operation error details.

Name Type Description
deviceId
  • string

The ID of the device that indicated the warning.

warningCode enum:
  • DeviceRegisteredWithoutTwin
warningStatus
  • string

Additional details associated with the warning.

ExportImportDevice

Name Type Description
authentication

Authentication parameter is optional and defaults to SAS if not provided. In that case, we auto-generate primary/secondary access keys

capabilities

Capabilities param is optional and defaults to no capability

eTag
  • string

ETag parameter is only used for pre-conditioning the update when importMode is updateIfMatchETag

id
  • string

Device Id is always required

importMode enum:
  • create
  • delete
  • deleteIfMatchETag
  • update
  • updateIfMatchETag
  • updateTwin
  • updateTwinIfMatchETag
moduleId
  • string

ModuleId is applicable to modules only

properties

Properties are optional and defaults to empty object

status enum:
  • disabled
  • enabled

Status is optional and defaults to enabled

statusReason
  • string
tags
  • object
twinETag
  • string

twinETag parameter is only used for pre-conditioning the update when importMode is updateTwinIfMatchETag

PropertyContainer

Represents Twin properties

Name Type Description
desired
  • object

Used in conjunction with reported properties to synchronize device configuration or condition. Desired properties can only be set by the solution back end and can be read by the device app. The device app can also be notified in real time of changes on the desired properties.

reported
  • object

Used in conjunction with desired properties to synchronize device configuration or condition. Reported properties can only be set by the device app and can be read and queried by the solution back end.

SymmetricKey

Name Type Description
primaryKey
  • string
secondaryKey
  • string

X509Thumbprint

Name Type Description
primaryThumbprint
  • string
secondaryThumbprint
  • string