你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Individual Enrollment - Create Or Update

服务:

IoT Hub Device Provisioning Service

API 版本:

2021-10-01

Create或更新设备注册记录。

PUT https://your-dps.azure-devices-provisioning.net/enrollments/{id}?api-version=2021-10-01

URI 参数

名称	在	必需	类型	说明
id	path	True	string	此 ID 用于唯一标识注册的设备注册。 不区分大小写的字符串 (最多 128 个字符，) 字母数字字符加上某些特殊字符：。 _ -. 开头或结尾不允许使用特殊字符。
api-version	query	True	string	要用于请求的 API 版本。 支持的版本包括：2021-10-01

请求头

名称	必需	类型	说明
If-Match		string	注册记录的 ETag。

请求正文

名称	必需	类型	说明
attestation	True	AttestationMechanism	用于 individualEnrollment 和 enrollmentGroup 的证明机制。
registrationId	True	string	此 ID 用于唯一标识注册的设备注册。 不区分大小写的字符串 (最多 128 个字符，) 字母数字字符和某些特殊字符：。 _ -. 不允许在开头或结尾使用特殊字符。
allocationPolicy		enum: hashed geoLatency static custom	此资源的分配策略。 此策略覆盖此单独注册或注册组的租户级别分配策略。 可能的值包括“hashed”：链接的 IoT 中心同样有可能将设备预配到它们，“geoLatency”：设备预配到 IoT 中心，且设备延迟最低。如果多个链接的 IoT 中心提供相同的最低延迟，则预配服务会跨这些中心对设备进行哈希处理，即“静态”：注册列表中所需 IoT 中心的规范优先于服务级别分配策略“custom”：设备根据你自己的自定义逻辑预配到 IoT 中心。 预配服务将有关设备的信息传递给逻辑，逻辑返回所需的 IoT 中心和所需的初始配置。 建议使用 Azure Functions 来托管逻辑。
capabilities		DeviceCapabilities	设备功能。
customAllocationDefinition		CustomAllocationDefinition	这会告知 DPS 在使用自定义分配时要调用哪个 Webhook。
deviceId		string	所需IoT 中心设备 ID (可选) 。
etag		string	与资源关联的实体标记。
initialTwin		InitialTwin	初始设备孪生。 包含 Twin 属性的子集。
iotHubHostName		string	IoT 中心主机名。
iotHubs		string[]	设备 (此资源中的) 可以分配到的IoT 中心主机名列表。 必须是 IoT 中心的租户级列表的子集。
optionalDeviceInformation		TwinCollection	表示孪生体中的属性集合
provisioningStatus		enum: enabled disabled	预配状态。
registrationState		DeviceRegistrationState	设备注册状态。
reprovisionPolicy		ReprovisionPolicy	将设备重新预配到 IoT 中心时服务的行为。

响应

名称	类型	说明
200 OK	IndividualEnrollment	成功
Other Status Codes	ProvisioningServiceErrorDetails	错误响应 标头 x-ms-error-code: string

定义

名称	说明
AttestationMechanism	用于 individualEnrollment 和 enrollmentGroup 的证明机制。
CustomAllocationDefinition	这会告知 DPS 在使用自定义分配时要调用哪个 Webhook。
DeviceCapabilities	设备功能。
DeviceRegistrationState	设备注册状态。
IndividualEnrollment	设备注册记录。
InitialTwin	初始设备孪生。 包含 Twin 属性的子集。
InitialTwinProperties	表示将在设备孪生上设置的初始属性。
Metadata	TwinCollection 的元数据
ProvisioningServiceErrorDetails	包含Azure IoT 中心预配服务返回的错误的属性。
ReprovisionPolicy	将设备重新预配到 IoT 中心时服务的行为。
SymmetricKeyAttestation	通过 SymmetricKey 证明。
TpmAttestation	通过 TPM 证明。
TwinCollection	表示孪生体中的属性集合
X509Attestation	通过 X509 进行证明。
X509CAReferences	主要和次要 CA 引用。
X509CertificateInfo	X509 证书信息。
X509Certificates	主证书和辅助证书
X509CertificateWithInfo	证书和证书信息

AttestationMechanism

用于 individualEnrollment 和 enrollmentGroup 的证明机制。

名称	类型	说明
symmetricKey	SymmetricKeyAttestation	通过 SymmetricKey 证明。
tpm	TpmAttestation	通过 TPM 证明。
type	enum: none symmetricKey tpm x509	证明类型。
x509	X509Attestation	通过 X509 进行证明。

CustomAllocationDefinition

这会告知 DPS 在使用自定义分配时要调用哪个 Webhook。

名称	类型	说明
apiVersion	string	在自定义分配请求中发送的预配服务类型的 API 版本 (，例如 IndividualEnrollment) 。 支持的最低版本：“2018-09-01-preview”。
webhookUrl	string	用于分配请求的 Webhook URL。

DeviceCapabilities

设备功能。

名称	类型	默认值	说明
iotEdge	boolean	False	如果设置为 true，则此设备是 IoTEdge 设备。

DeviceRegistrationState

设备注册状态。

名称	类型	说明
assignedHub	string	已分配Azure IoT 中心。
createdDateTimeUtc	string	注册创建日期时间 (UTC) 。
deviceId	string	设备 ID。
errorCode	integer	错误代码。
errorMessage	string	错误消息。
etag	string	与资源关联的实体标记。
lastUpdatedDateTimeUtc	string	上次更新日期时间 (UTC) 。
payload	object
registrationId	string	此 ID 用于唯一标识注册的设备注册。 不区分大小写的字符串 (最多 128 个字符，) 字母数字字符和某些特殊字符：。 _ -. 不允许在开头或结尾使用特殊字符。
status	enum: assigned assigning disabled failed unassigned	注册状态。
substatus	enum: deviceDataMigrated deviceDataReset initialAssignment reprovisionedToInitialAssignment	“已分配”设备的子状态。 可能的值包括 -“initialAssignment”：设备已首次分配到 IoT 中心，“deviceDataMigrated”：设备已分配到其他 IoT 中心，并且其设备数据已从以前分配的 IoT 中心迁移。 设备数据已从以前分配的 IoT 中心“deviceDataReset”中删除：设备已分配到其他 IoT 中心，并且其设备数据已从注册中存储的初始状态填充。 设备数据已从以前分配的 IoT 中心“reprovisionedToInitialAssignment”中删除：设备已重新预配到以前分配的 IoT 中心。

IndividualEnrollment

设备注册记录。

名称	类型	默认值	说明
allocationPolicy	enum: custom geoLatency hashed static		此资源的分配策略。 此策略将覆盖此单独注册或注册组的租户级别分配策略。 可能的值包括“hashed”：链接的 IoT 中心同样可能预配设备，“geoLatency”：设备预配到 IoT 中心，其延迟最低。如果多个链接的 IoT 中心提供相同的最低延迟，则预配服务会跨这些中心对设备进行哈希处理，即“静态”：注册列表中的所需 IoT 中心的规范优先于服务级别分配策略“自定义”：设备根据你自己的自定义逻辑预配到 IoT 中心。 预配服务将有关设备的信息传递给逻辑，逻辑返回所需的 IoT 中心和所需的初始配置。 建议使用 Azure Functions 来托管逻辑。
attestation	AttestationMechanism		用于 individualEnrollment 和 enrollmentGroup 的证明机制。
capabilities	DeviceCapabilities		设备功能。
createdDateTimeUtc	string		创建此资源的 DateTime。
customAllocationDefinition	CustomAllocationDefinition		这会告知 DPS 在使用自定义分配时要调用哪个 Webhook。
deviceId	string		所需IoT 中心设备 ID (可选) 。
etag	string		与资源关联的实体标记。
initialTwin	InitialTwin		初始设备孪生。 包含 Twin 属性的子集。
iotHubHostName	string		IoT 中心主机名。
iotHubs	string[]		可以将设备 () IoT 中心主机名的列表。 必须是 IoT 中心的租户级列表的子集。
lastUpdatedDateTimeUtc	string		上次更新此资源的 DateTime。
optionalDeviceInformation	TwinCollection		表示孪生体中的属性集合
provisioningStatus	enum: disabled enabled	enabled	预配状态。
registrationId	string		此 ID 用于唯一标识注册的设备注册。 不区分大小写的字符串 (最多 128 个字符，) 字母数字字符和某些特殊字符：。 _ -. 不允许在开头或结尾使用特殊字符。
registrationState	DeviceRegistrationState		设备注册状态。
reprovisionPolicy	ReprovisionPolicy		将设备重新预配到 IoT 中心时服务的行为。

InitialTwin

初始设备孪生。 包含 Twin 属性的子集。

名称	类型	说明
properties	InitialTwinProperties	表示将在设备孪生上设置的初始属性。
tags	TwinCollection	表示孪生体中的属性集合

InitialTwinProperties

表示将在设备孪生上设置的初始属性。

名称	类型	说明
desired	TwinCollection	表示孪生体中的属性集合

Metadata

TwinCollection 的元数据

名称	类型	说明
lastUpdated	string	上次更新 TwinCollection 的时间
lastUpdatedVersion	integer	对于报告的属性元数据，这为 null，对于所需属性元数据，则不为 null。

ProvisioningServiceErrorDetails

包含Azure IoT 中心预配服务返回的错误的属性。

名称	类型	说明
errorCode	integer
info	object
message	string
timestampUtc	string
trackingId	string

ReprovisionPolicy

将设备重新预配到 IoT 中心时服务的行为。

名称	类型	默认值	说明
migrateDeviceData	boolean	True	(默认) 设置为 true 时，设备预配服务将在 IoT 中心分配更新期间将设备的数据 (孪生、设备功能和设备 ID) 从一个 IoT 中心迁移到另一个 IoT 中心。 如果设置为 false，则设备预配服务会将设备的数据重置为存储在相应注册列表中的初始所需配置。
updateHubAssignment	boolean	True	当设置为 true (默认) 时，设备预配服务将评估设备的IoT 中心分配，并在必要时更新该分配，以便对给定设备的第一个预配请求以外的任何预配请求进行更新。 如果设置为 false，设备将始终分配到其当前 IoT 中心。

SymmetricKeyAttestation

通过 SymmetricKey 证明。

名称	类型	说明
primaryKey	string	主对称密钥。
secondaryKey	string	辅助对称密钥。

TpmAttestation

通过 TPM 证明。

名称	类型	说明
endorsementKey	string
storageRootKey	string

TwinCollection

表示孪生体中的属性集合

名称	类型	说明
count	integer	TwinCollection 中的属性数
metadata	Metadata	TwinCollection 的元数据
version	integer	TwinCollection 的版本

X509Attestation

通过 X509 进行证明。

名称	类型	说明
caReferences	X509CAReferences	主要和次要 CA 引用。
clientCertificates	X509Certificates	主证书和辅助证书
signingCertificates	X509Certificates	主证书和辅助证书

X509CAReferences

主要和次要 CA 引用。

名称	类型	说明
primary	string
secondary	string

X509CertificateInfo

X509 证书信息。

名称	类型	说明
issuerName	string
notAfterUtc	string
notBeforeUtc	string
serialNumber	string
sha1Thumbprint	string
sha256Thumbprint	string
subjectName	string
version	integer

X509Certificates

主证书和辅助证书

名称	类型	说明
primary	X509CertificateWithInfo	证书和证书信息
secondary	X509CertificateWithInfo	证书和证书信息

X509CertificateWithInfo

证书和证书信息

名称	类型	说明
certificate	string
info	X509CertificateInfo	X509 证书信息。