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

Runtime Registration - Register Device

服务:: IoT Hub Device Provisioning Service

API 版本:: 2021-10-01

注册设备。

PUT https://global.azure-devices-provisioning.net/{idScope}/registrations/{registrationId}/register?api-version=2021-10-01

URI 参数

名称	在	必需	类型	说明
idScope	path	True	string	DPS实例的范围。
registrationId	path	True	string	注册ID为字母数字、小写字母，可能包含连字符。
api-version	query	True	string minLength: 1	用于此作的 API 版本。

请求正文

名称	类型	说明
payload		任何对象
registrationId	string	注册ID是一个大小写不区分的字符串（最长128个字符），由字母数字字符加上某些特殊字符组成：。 _ -. 开头和结尾都不允许特殊字符。
tpm	TpmAttestation	通过TPM认证。

响应

名称	类型	说明
200 OK	RegistrationOperationStatus	请求已成功。
202 Accepted	RegistrationOperationStatus	已接受请求进行处理，但尚未完成处理。标头 Location: string retry-after: integer
Other Status Codes	ProvisioningServiceErrorDetails	意外的错误响应。标头 x-ms-error-code: string

名称

类型

说明

200 OK

RegistrationOperationStatus

请求已成功。

202 Accepted

RegistrationOperationStatus

已接受请求进行处理，但尚未完成处理。

标头

Location: string
retry-after: integer

Other Status Codes

ProvisioningServiceErrorDetails

意外的错误响应。

标头

x-ms-error-code: string

示例

RuntimeRegistration_RegisterDevice_MaximumSet_Gen

RuntimeRegistration_RegisterDevice_MinimumSet_Gen

RuntimeRegistration_RegisterDevice_MaximumSet_Gen

示例请求

HTTP

PUT https://global.azure-devices-provisioning.net/ofvgihmgllfsmm/registrations/macgmlbhpb/register?api-version=2021-10-01

{
  "payload": {},
  "registrationId": "qypnuerjeunzogqdezhjgisfr",
  "tpm": {
    "endorsementKey": "sbvvzftylrpsetexcmnijtdezppq",
    "storageRootKey": "juohyrayid"
  }
}

示例响应

状态代码:: 200

{
  "operationId": "xosjboksmobnotwgqejpvxiwi",
  "registrationState": {
    "assignedHub": "ljexps",
    "createdDateTimeUtc": "2025-10-01T17:41:56.535Z",
    "deviceId": "hjvdlwpugzlk",
    "errorCode": 13,
    "errorMessage": "zpctqazbkbiqjkwosis",
    "etag": "hjtelksspyfzhmet",
    "lastUpdatedDateTimeUtc": "2025-10-01T17:41:56.535Z",
    "payload": {},
    "registrationId": "urejrffpkqneou",
    "status": "unassigned",
    "substatus": "initialAssignment",
    "symmetricKey": {
      "enrollmentGroupId": "w"
    },
    "tpm": {
      "authenticationKey": "sofbxakhjrxpiyysjjxkx"
    },
    "x509": {
      "certificateInfo": {
        "issuerName": "pvpbipnhcahytrcq",
        "notAfterUtc": "2025-10-01T17:41:56.534Z",
        "notBeforeUtc": "2025-10-01T17:41:56.534Z",
        "serialNumber": "jjvdijgwgpagrjdi",
        "sha1Thumbprint": "guqltcfgusf",
        "sha256Thumbprint": "ysryarleygpkejrjlwuxacvcwbxqw",
        "subjectName": "jtsfqnbcmmott",
        "version": 20
      },
      "enrollmentGroupId": "qbw",
      "signingCertificateInfo": {
        "issuerName": "pvpbipnhcahytrcq",
        "notAfterUtc": "2025-10-01T17:41:56.534Z",
        "notBeforeUtc": "2025-10-01T17:41:56.534Z",
        "serialNumber": "jjvdijgwgpagrjdi",
        "sha1Thumbprint": "guqltcfgusf",
        "sha256Thumbprint": "ysryarleygpkejrjlwuxacvcwbxqw",
        "subjectName": "jtsfqnbcmmott",
        "version": 20
      }
    }
  },
  "status": "unassigned"
}

状态代码:: 202

{
  "operationId": "xosjboksmobnotwgqejpvxiwi",
  "registrationState": {
    "assignedHub": "ljexps",
    "createdDateTimeUtc": "2025-10-01T17:41:56.535Z",
    "deviceId": "hjvdlwpugzlk",
    "errorCode": 13,
    "errorMessage": "zpctqazbkbiqjkwosis",
    "etag": "hjtelksspyfzhmet",
    "lastUpdatedDateTimeUtc": "2025-10-01T17:41:56.535Z",
    "payload": {},
    "registrationId": "urejrffpkqneou",
    "status": "unassigned",
    "substatus": "initialAssignment",
    "symmetricKey": {
      "enrollmentGroupId": "w"
    },
    "tpm": {
      "authenticationKey": "sofbxakhjrxpiyysjjxkx"
    },
    "x509": {
      "certificateInfo": {
        "issuerName": "pvpbipnhcahytrcq",
        "notAfterUtc": "2025-10-01T17:41:56.534Z",
        "notBeforeUtc": "2025-10-01T17:41:56.534Z",
        "serialNumber": "jjvdijgwgpagrjdi",
        "sha1Thumbprint": "guqltcfgusf",
        "sha256Thumbprint": "ysryarleygpkejrjlwuxacvcwbxqw",
        "subjectName": "jtsfqnbcmmott",
        "version": 20
      },
      "enrollmentGroupId": "qbw",
      "signingCertificateInfo": {
        "issuerName": "pvpbipnhcahytrcq",
        "notAfterUtc": "2025-10-01T17:41:56.534Z",
        "notBeforeUtc": "2025-10-01T17:41:56.534Z",
        "serialNumber": "jjvdijgwgpagrjdi",
        "sha1Thumbprint": "guqltcfgusf",
        "sha256Thumbprint": "ysryarleygpkejrjlwuxacvcwbxqw",
        "subjectName": "jtsfqnbcmmott",
        "version": 20
      }
    }
  },
  "status": "unassigned"
}

RuntimeRegistration_RegisterDevice_MinimumSet_Gen

示例请求

HTTP

PUT https://global.azure-devices-provisioning.net/gwgyqmyyzzzjpjmxml/registrations/tuodrxicixbbekaajxfiyvoxsbe/register?api-version=2021-10-01

{}

示例响应

状态代码:: 200

{
  "operationId": "xosjboksmobnotwgqejpvxiwi"
}

状态代码:: 202

{
  "operationId": "xosjboksmobnotwgqejpvxiwi"
}

定义

名称	说明
AssignedDeviceSubstatus	“已分配”设备的子状态。可能的值包括 - “initialAssignment”：设备首次被分配到物联网中心，“deviceDataMigrated”：设备被分配到不同的物联网中心，其设备数据已从之前分配的物联网中心迁移。设备数据从之前分配的物联网中心“deviceDataReset”中移除：设备被分配到另一个物联网中心，其设备数据是从注册时存储的初始状态填充的。设备数据已从之前分配的物联网中心移除，“reprovisionedToInitialAssignment”：设备已重新配置到之前分配的物联网中心。
DeviceRegistration	设备注册。
DeviceRegistrationResult	设备注册结果。
EnrollmentStatus	招生状态。
ProvisioningServiceErrorDetails	包含 Azure IoT Hub 配置服务返回的错误属性。
RegistrationOperationStatus	注册运营状态。
SymmetricKeyRegistrationResult	使用SymmetricKey认证时，注册结果返回。
TpmAttestation	通过TPM认证。
TpmRegistrationResult	TPM注册结果。
X509CertificateInfo	X509证书信息。
X509RegistrationResult	X509注册结果。

AssignedDeviceSubstatus

枚举

“已分配”设备的子状态。可能的值包括 - “initialAssignment”：设备首次被分配到物联网中心，“deviceDataMigrated”：设备被分配到不同的物联网中心，其设备数据已从之前分配的物联网中心迁移。设备数据从之前分配的物联网中心“deviceDataReset”中移除：设备被分配到另一个物联网中心，其设备数据是从注册时存储的初始状态填充的。设备数据已从之前分配的物联网中心移除，“reprovisionedToInitialAssignment”：设备已重新配置到之前分配的物联网中心。

值	说明
initialAssignment	初始分配
deviceDataMigrated	deviceDataMigrated
deviceDataReset	deviceDataReset
reprovisionedToInitialAssignment	重新配置为初始分配

DeviceRegistration

对象

设备注册。

名称	类型	说明
payload		任何对象
registrationId	string	注册ID是一个大小写不区分的字符串（最长128个字符），由字母数字字符加上某些特殊字符组成：。 _ -. 开头和结尾都不允许特殊字符。
tpm	TpmAttestation	通过TPM认证。

DeviceRegistrationResult

对象

设备注册结果。

名称	类型	说明
assignedHub	string	Assigned Azure IoT Hub.
createdDateTimeUtc	string (date-time)	注册创建日期时间（UTC）。
deviceId	string	设备 ID。
errorCode	integer (int32)	错误代码。
errorMessage	string	错误消息。
etag	string	与资源相关的实体标签。
lastUpdatedDateTimeUtc	string (date-time)	最后更新日期时间（UTC）。
payload		任何对象
registrationId	string	该ID用于唯一标识注册的设备注册。一个大小写不区分的字符串（长度可达128个字符），由字母数字字符加上某些特殊字符组成：。 _ -. 开头和结尾都不允许特殊字符。
status	EnrollmentStatus	招生状态。
substatus	AssignedDeviceSubstatus	“已分配”设备的子状态。可能的值包括 - “initialAssignment”：设备首次被分配到物联网中心，“deviceDataMigrated”：设备被分配到不同的物联网中心，其设备数据已从之前分配的物联网中心迁移。设备数据从之前分配的物联网中心“deviceDataReset”中移除：设备被分配到另一个物联网中心，其设备数据是从注册时存储的初始状态填充的。设备数据已从之前分配的物联网中心移除，“reprovisionedToInitialAssignment”：设备已重新配置到之前分配的物联网中心。
symmetricKey	SymmetricKeyRegistrationResult	使用SymmetricKey认证时，注册结果返回。
tpm	TpmRegistrationResult	TPM注册结果。
x509	X509RegistrationResult	X509注册结果。

EnrollmentStatus

枚举

招生状态。

值	说明
unassigned	未分配
assigning	指派
assigned	已分配
failed	"失败"
disabled	禁用的

ProvisioningServiceErrorDetails

对象

包含 Azure IoT Hub 配置服务返回的错误属性。

名称	类型	说明
errorCode	integer (int32)	数字错误代码。
info	object	<字符串> 字典
message	string	错误消息。
timestampUtc	string (date-time)	错误时间戳（UTC）。
trackingId	string	错误追踪ID。

RegistrationOperationStatus

对象

注册运营状态。

名称	类型	说明
operationId	string minLength: 1	操作编号
registrationState	DeviceRegistrationResult	设备注册结果。
status	EnrollmentStatus	设备注册状态。

SymmetricKeyRegistrationResult

对象

使用SymmetricKey认证时，注册结果返回。

名称	类型	说明
enrollmentGroupId	string	注册组 ID。

TpmAttestation

对象

通过TPM认证。

名称	类型	说明
endorsementKey	string	TPM背书密钥。
storageRootKey	string	TPM存储根键。

TpmRegistrationResult

对象

TPM注册结果。

名称	类型	说明
authenticationKey	string	加密的认证密钥。

X509CertificateInfo

对象

X509证书信息。

名称	类型	说明
issuerName	string	证书颁发者名称。
notAfterUtc	string (date-time)	证书到期日（UTC）。
notBeforeUtc	string (date-time)	证书有效期起始日期（UTC）。
serialNumber	string	证书序列号。
sha1Thumbprint	string	证书的SHA-1指纹。
sha256Thumbprint	string	证书上的SHA-256指纹。
subjectName	string	证书主题名称。
version	integer (int32)	证书版本。

X509RegistrationResult

对象

X509注册结果。

名称	类型	说明
certificateInfo	X509CertificateInfo	X509证书信息。
enrollmentGroupId	string	注册组 ID。
signingCertificateInfo	X509CertificateInfo	X509证书信息。