Bulk Registry - Update Registry

Creates, updates, or deletes the identities 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, use 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=2021-04-12

URI Parameters

Name In Required Type Description
api-version
query True

string

Version of the Api.

Request Body

Name Type Description
devices

ExportImportDevice[]

The registry operations to perform.

Responses

Name Type Description
200 OK

BulkRegistryOperationResult

OK.

400 Bad Request

BulkRegistryOperationResult

Bad Request.

Definitions

Name Description
AuthenticationMechanism
BulkRegistryOperationResult

The result of the bulk registry operation.

DeviceCapabilities

The status of capabilities enabled on the device.

DeviceRegistryOperationError

The device registry operation error details.

DeviceRegistryOperationWarning

The device registry operation warning details.

ExportImportDevice
PropertyContainer

The desired and reported properties of the twin. The maximum depth of the object is 10.

SymmetricKey
X509Thumbprint

AuthenticationMechanism

Name Type Description
symmetricKey

SymmetricKey

The primary and secondary keys used for SAS based authentication.

type enum:
  • certificateAuthority
  • none
  • sas
  • selfSigned

The type of authentication used to connect to the service.

x509Thumbprint

X509Thumbprint

The primary and secondary x509 thumbprints used for x509 based authentication.

BulkRegistryOperationResult

The result of the bulk registry operation.

Name Type Description
errors

DeviceRegistryOperationError[]

The device registry operation errors.

isSuccessful

boolean

The operation result.

warnings

DeviceRegistryOperationWarning[]

The device registry operation warnings.

DeviceCapabilities

The status of capabilities enabled on the device.

Name Type Description
iotEdge

boolean

The property that determines if the device is an edge device or not.

DeviceRegistryOperationError

The device registry operation error details.

Name Type Description
deviceId

string

The unique identifier of the device.

errorCode enum:
  • AmqpAddressNotFound
  • ApplyConfigurationAlreadyInProgressOnDevice
  • ArgumentInvalid
  • ArgumentNull
  • AsyncOperationNotFound
  • AzureStorageTimeout
  • AzureTableStoreError
  • AzureTableStoreNotFound
  • BackupTimedOut
  • BlobContainerValidationError
  • BulkAddDevicesNotSupported
  • BulkRegistryOperationFailure
  • CallbackSubscriptionConflict
  • CannotModifyImmutableConfigurationContent
  • CannotRegisterModuleToModule
  • CertificateAuthorityConflict
  • CertificateAuthorityNotFound
  • CertificateNotFound
  • CheckpointStoreNotFound
  • ClientClosedRequest
  • ConfigReadFailed
  • ConfigurationAlreadyExists
  • ConfigurationCountLimitExceeded
  • ConfigurationNotAvailable
  • ConfigurationNotFound
  • ConnectionForcefullyClosed
  • ConnectionForcefullyClosedOnFaultInjection
  • ConnectionForcefullyClosedOnNewConnection
  • ConnectionRejectedOnFaultInjection
  • ConnectionUnavailable
  • CustomAllocationFailed
  • CustomAllocationIotHubNotSpecified
  • CustomAllocationUnauthorizedAccess
  • DefaultStorageEndpointNotConfigured
  • DeserializationError
  • DeviceAlreadyExists
  • DeviceConnectionClosedRemotely
  • DeviceDefinedMultipleTimes
  • DeviceDisabled
  • DeviceGroupConflict
  • DeviceGroupNotFound
  • DeviceInvalidResultCount
  • DeviceJobAlreadyExists
  • DeviceLocked
  • DeviceMaximumActiveFileUploadLimitExceeded
  • DeviceMaximumQueueDepthExceeded
  • DeviceMaximumQueueSizeExceeded
  • DeviceMessageLockLost
  • DeviceModelMaxIndexablePropertiesExceeded
  • DeviceModelMaxPropertiesExceeded
  • DeviceNotFound
  • DeviceNotOnline
  • DeviceRecordConflict
  • DeviceRecordNotFound
  • DeviceRegistrationNotFound
  • DeviceStorageEntitySerializationError
  • DeviceThrottlingLimitExceeded
  • DeviceUnavailable
  • DigitalTwinInterfaceNotFound
  • DigitalTwinModelAlreadyExists
  • DigitalTwinModelCountLimitExceeded
  • DigitalTwinModelExistsWithOtherModelType
  • DigitalTwinModelNotFound
  • 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
  • GroupRecordConflict
  • GroupRecordNotFound
  • HostingServiceNotAvailable
  • ImportDevicesNotSupported
  • ImportWarningExistsError
  • IncompatibleDataType
  • InflightMessagesInLink
  • InterfaceNameCompressionModelCountLimitExceeded
  • InterfaceNameModelAlreadyExists
  • InterfaceNameModelNotFound
  • InvalidBlobState
  • InvalidConfigurationContent
  • InvalidConfigurationCustomMetricsQuery
  • InvalidConfigurationTargetCondition
  • InvalidContainerReceiveLink
  • InvalidContentEncodingOrType
  • InvalidDeviceScope
  • InvalidDigitalTwinJsonPatch
  • InvalidDigitalTwinPatch
  • InvalidDigitalTwinPatchPath
  • InvalidDigitalTwinPayload
  • InvalidEndorsementKey
  • InvalidEndpointAuthenticationType
  • 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
  • KeyEncryptionKeyRevoked
  • LinkCreationConflict
  • LinkedHubConflict
  • LinkedHubNotFound
  • ManagedIdentityNotEnabled
  • MessageTooLarge
  • ModelAlreadyExists
  • ModelRepoEndpointError
  • ModuleAlreadyExistsOnDevice
  • ModuleNotFound
  • NullMessage
  • OperationNotAllowedInCurrentState
  • OperationNotAvailableInCurrentTier
  • OrchestrationOperationFailed
  • OrphanDiscoveryDocument
  • PartitionNotFound
  • PreconditionFailed
  • ProvisioningRecordConflict
  • ProvisioningRecordNotFound
  • ProvisioningSettingsConflict
  • ProvisioningSettingsNotFound
  • QueryStoreClusterNotFound
  • QuotaMetricNotFound
  • ReceiveLinkOpensThrottled
  • RegistrationIdDefinedMultipleTimes
  • RegistrationStatusConflict
  • ReliableBlobStoreError
  • ReliableBlobStoreTimeoutError
  • ReliableDocDbStoreStoreError
  • RequestCanceled
  • RequestTimedOut
  • ResolutionError
  • RestoreTimedOut
  • RetryAttemptsExhausted
  • RoutingEndpointResponseForbidden
  • RoutingEndpointResponseNotFound
  • RoutingNotEnabled
  • SerializationError
  • ServerBusy
  • ServerError
  • ServiceUnavailable
  • StatisticsRetrievalError
  • StreamReservationFailure
  • SystemModuleModifyUnauthorizedAccess
  • SystemPropertyNotFound
  • TenantHubRoutingNotEnabled
  • ThrottleBacklogLimitExceeded
  • ThrottlingBacklogTimeout
  • ThrottlingException
  • ThrottlingMaxActiveJobCountExceeded
  • TooManyDevices
  • TooManyEnrollments
  • TooManyModulesOnDevice
  • UnableToCompressComponentInfo
  • UnableToCompressDiscoveryInfo
  • UnableToExpandComponentInfo
  • UnableToExpandDiscoveryInfo
  • UnableToFetchCredentials
  • UnableToFetchTenantInfo
  • UnableToShareIdentity
  • UnexpectedPropertyValue
  • UnsupportedOperationOnReplica

The error code.

errorStatus

string

The details of the error.

moduleId

string

The unique identifier of the module, if applicable.

operation

string

The type of the operation that failed.

DeviceRegistryOperationWarning

The device registry operation warning details.

Name Type Description
deviceId

string

The unique identifier of the device.

warningCode enum:

DeviceRegisteredWithoutTwin

The warning code.

warningStatus

string

The details of the warning.

ExportImportDevice

Name Type Description
authentication

AuthenticationMechanism

The authentication mechanism used by the module. This parameter is optional and defaults to SAS if not provided. In that case, primary/secondary access keys are auto-generated.

capabilities

DeviceCapabilities

The status of capabilities enabled on the device.

deviceScope

string

The scope of the device.

eTag

string

The string representing a weak ETag for the device RFC7232. The value is only used if import mode is updateIfMatchETag, in that case the import operation is performed only if this ETag matches the value maintained by the server.

id

string

The unique identifier of the device.

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

The type of registry operation and ETag preferences.

moduleId

string

The unique identifier of the module, if applicable.

parentScopes

string[]

The scopes of the upper level edge devices if applicable. Only available for edge devices.

properties

PropertyContainer

The desired and reported properties for the device.

status enum:
  • disabled
  • enabled

The status of the module. If disabled, the module cannot connect to the service.

statusReason

string

The 128 character-long string that stores the reason for the device identity status. All UTF-8 characters are allowed.

tags

object

The JSON document read and written by the solution back end. The tags are not visible to device apps.

twinETag

string

The string representing a weak ETag for the device twin RFC7232. The value is only used if import mode is updateIfMatchETag, in that case the import operation is performed only if this ETag matches the value maintained by the server.

PropertyContainer

The desired and reported properties of the twin. The maximum depth of the object is 10.

Name Type Description
desired

object

The collection of desired property key-value pairs. The keys are UTF-8 encoded, case-sensitive and up-to 1KB in length. Allowed characters exclude UNICODE control characters (segments C0 and C1), '.', '$' and space. The desired porperty values are JSON objects, up-to 4KB in length.

reported

object

The collection of reported property key-value pairs. The keys are UTF-8 encoded, case-sensitive and up-to 1KB in length. Allowed characters exclude UNICODE control characters (segments C0 and C1), '.', '$' and space. The reported property values are JSON objects, up-to 4KB in length.

SymmetricKey

Name Type Description
primaryKey

string

The base64 encoded primary key of the device.

secondaryKey

string

The base64 encoded secondary key of the device.

X509Thumbprint

Name Type Description
primaryThumbprint

string

The X509 client certificate primary thumbprint.

secondaryThumbprint

string

The X509 client certificate secondary thumbprint.