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 參數

名稱	位於	必要	類型	Description
idScope	path	True	string	DPS 實例的範圍。
registrationId	path	True	string	註冊 ID 為字母數字、小寫，且可能包含連字號。
api-version	query	True	string minLength: 1	用於此作業的 API 版本。

要求本文

名稱	類型	Description
payload		任何物件
registrationId	string	註冊 ID 是一個大小寫不區分的字串（長度可達 128 個字元），包含字母數字加上某些特殊字元：。 _ -. 開頭和結尾都不允許特殊字元。
tpm	TpmAttestation	透過TPM認證。

回應

名稱	類型	Description
200 OK	RegistrationOperationStatus	要求已成功。
202 Accepted	RegistrationOperationStatus	要求已接受進行處理，但尚未完成處理。標題 Location: string retry-after: integer
Other Status Codes	ProvisioningServiceErrorDetails	未預期的錯誤回應。標題 x-ms-error-code: string

名稱

類型

Description

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"
}

定義

名稱	Description
AssignedDeviceSubstatus	「指派」裝置的子狀態。可能的值包括：「initialAssignment」：裝置首次被指派到物聯網樞紐，「deviceDataMigrated」：裝置被指派到不同的物聯網樞紐，且其裝置資料從先前分配的物聯網樞紐遷移過來。裝置資料從先前分配的物聯網樞紐「deviceDataReset」中移除：裝置已被分配到另一個物聯網樞紐，其裝置資料是從註冊時儲存的初始狀態中填充的。裝置資料已從先前指派的物聯網樞紐移除，'reprovisionedToInitialAssignment'：裝置已重新配置至先前指派的物聯網樞紐。
DeviceRegistration	裝置註冊。
DeviceRegistrationResult	裝置註冊結果。
EnrollmentStatus	註冊狀況。
ProvisioningServiceErrorDetails	包含 Azure IoT Hub Provisioning Service 回傳錯誤的屬性。
RegistrationOperationStatus	登記運作狀態。
SymmetricKeyRegistrationResult	使用 SymmetricKey 認證時，註冊結果回傳。
TpmAttestation	透過TPM認證。
TpmRegistrationResult	TPM 註冊結果。
X509CertificateInfo	X509 證書資訊。
X509RegistrationResult	X509 報名結果。

AssignedDeviceSubstatus

列舉型別

「指派」裝置的子狀態。可能的值包括：「initialAssignment」：裝置首次被指派到物聯網樞紐，「deviceDataMigrated」：裝置被指派到不同的物聯網樞紐，且其裝置資料從先前分配的物聯網樞紐遷移過來。裝置資料從先前分配的物聯網樞紐「deviceDataReset」中移除：裝置已被分配到另一個物聯網樞紐，其裝置資料是從註冊時儲存的初始狀態中填充的。裝置資料已從先前指派的物聯網樞紐移除，'reprovisionedToInitialAssignment'：裝置已重新配置至先前指派的物聯網樞紐。

值	Description
initialAssignment	初始指派
deviceDataMigrated	deviceDataMigrated
deviceDataReset	deviceDataReset
reprovisionedToInitialAssignment	重新配置為初始分配

DeviceRegistration

Object

裝置註冊。

名稱	類型	Description
payload		任何物件
registrationId	string	註冊 ID 是一個大小寫不區分的字串（長度可達 128 個字元），包含字母數字加上某些特殊字元：。 _ -. 開頭和結尾都不允許特殊字元。
tpm	TpmAttestation	透過TPM認證。

DeviceRegistrationResult

Object

裝置註冊結果。

名稱	類型	Description
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

列舉型別

註冊狀況。

值	Description
unassigned	未分配
assigning	指派
assigned	已指派
failed	失敗
disabled	停用

ProvisioningServiceErrorDetails

Object

包含 Azure IoT Hub Provisioning Service 回傳錯誤的屬性。

名稱	類型	Description
errorCode	integer (int32)	數字錯誤代碼。
info	object	<字串> 字典
message	string	錯誤訊息。
timestampUtc	string (date-time)	錯誤時間戳記（UTC）。
trackingId	string	錯誤追蹤ID。

RegistrationOperationStatus

Object

登記運作狀態。

名稱	類型	Description
operationId	string minLength: 1	作業標識碼。
registrationState	DeviceRegistrationResult	裝置註冊結果。
status	EnrollmentStatus	裝置註冊狀態。

SymmetricKeyRegistrationResult

Object

使用 SymmetricKey 認證時，註冊結果回傳。

名稱	類型	Description
enrollmentGroupId	string	註冊群組標識碼。

TpmAttestation

Object

透過TPM認證。

名稱	類型	Description
endorsementKey	string	TPM 背書鑰匙。
storageRootKey	string	TPM 儲存根金鑰。

TpmRegistrationResult

Object

TPM 註冊結果。

名稱	類型	Description
authenticationKey	string	加密的認證金鑰。

X509CertificateInfo

Object

X509 證書資訊。

名稱	類型	Description
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

Object

X509 報名結果。

名稱	類型	Description
certificateInfo	X509CertificateInfo	X509 證書資訊。
enrollmentGroupId	string	註冊群組標識碼。
signingCertificateInfo	X509CertificateInfo	X509 證書資訊。