az iot device registration

預覽

Note

此參考文獻是 Azure CLI（版本 2.73.0 或更高版本）azure-iot 擴充的一部分。擴充功能會在您第一次執行 az iot device registration 命令時自動安裝。深入了解擴充功能。

此命令群組處於預覽狀態，且正在開發中。參考和支援層級： https://aka.ms/CLI_refstatus

透過 Azure IoT 中樞裝置配置服務（DPS）註冊裝置。

個人或團體註冊使用創建，接著在接受註冊後使用運作狀態。請使用對稱金鑰或 X.509 憑證驗證裝置。服役登記紀錄及註冊-州政府管理仍屬 az iot dps。

命令

名稱	Description	類型	狀態
az iot device registration create	註冊裝置並可選擇性地發出其運作證書。	Extension	Preview
az iot device registration operation-status	顯示 DPS 裝置註冊操作的狀態。	Extension	Preview

az iot device registration create

預覽

命令群組「iot 裝置註冊」處於預覽狀態，目前正在開發中。參考和支援層級： https://aka.ms/CLI_refstatus

註冊裝置並可選擇性地發出其運作證書。

對於個人登記，請提供其裝置——對稱鑰匙。對於群組註冊，請提供帶有 --compute-key 的群組金鑰，或提供一個已衍生出的裝置金鑰，但不含 --compute-key。或者，使用 --dps-name 搭配 --auth-類型的登入來發現 ID 範圍/端點並取得註冊金鑰;新增 --group-id 和 --compute-key 以設定群組註冊。 Entra 登入授權這個啟動查詢，而不是裝置註冊請求。

使用 --id-scope 搭配明確的裝置憑證來跳過 DPS 資源發現。使用非預設配置端點時，請設定 --host。對於 X.509 認證，請提供 --certificate-file-path 與 --key-file-path;只有當私鑰加密時才加 --密碼短語。

新增 --csr（別名 --csr-file-path）以請求操作憑證。它接受 PEM 或 base64 DER PKCS #10，無論是內嵌或檔案。 CSR 簽名必須有效，且其通用名稱必須與 --registration-id 相符。CSR 不會取代裝置的對稱金鑰或 X.509 認證。

指揮部投票接受註冊，以致敬重試後。如果在收到操作 ID 後逾時，則使用 Operation-status，該 ID 與相同的註冊 ID、ID 範圍、端點及裝置認證。逾時不會取消後端操作;不要盲目重複創作。 --timeout 會在初步 ID 範圍與啟動憑證發現後，對同一 REST 流程施加硬性截止日期，涵蓋 CSR 與非 CSR 註冊，包括工作啟動、HTTP 重試與輪詢。若沒有 ---timeout，則保留現有的有界五分鐘投票行為。

JSON 輸出保留 issuedCertificateChain 和 connectionProfile，當 DPS 返回時，還有用於登錄裝置關聯的 registryDeviceExternalId。 2026-11-02-preview 的 RegisterDeviceAndIssueCertificate 合約僅將 issuedCertificateChain 描述為一個位元組陣列，並未定義其線路編碼或憑證順序。因此，此指令在 JSON 輸出中保留該欄位，但不提供憑證檔案輸出選項;寫出猜測鏈可能會產生不符合 TLS 標準或錯誤排序的組合。 --endorsement-key 與 --storage-root-key 保留為進階請求結構欄位，但 TPM 僅認證明確不支援，因為此合約未提供用戶端 TPM 挑戰協定。

az iot device registration create --registration-id --rid
                                  [--acquire-policy-token]
                                  [--auth-type {key, login}]
                                  [--certificate-file-path --cp]
                                  [--change-reference]
                                  [--ck --compute-key]
                                  [--csr --csr-file-path]
                                  [--dps-name]
                                  [--endorsement-key]
                                  [--enrollment-group-id --gid --group-id]
                                  [--host --provisioning-host]
                                  [--id-scope --scope]
                                  [--key --symmetric-key]
                                  [--key-file-path --kp]
                                  [--login]
                                  [--pass --passphrase]
                                  [--payload]
                                  [--resource-group]
                                  [--storage-root-key]
                                  [--timeout]

範例

使用 Entra 授權的啟動金鑰查詢註冊個人登記

az iot device registration create --dps-name MyDps --resource-group MyResourceGroup \
  --registration-id device-01 --auth-type login

使用 Entra 授權的啟動鍵查詢註冊群組成員

az iot device registration create --dps-name MyDps --registration-id device-01 \
  --group-id MyEnrollmentGroup --compute-key --auth-type login

用裝置金鑰和已知的 ID 範圍註冊，無需啟動搜尋

az iot device registration create --id-scope 0ne00000000 \
  --registration-id device-01 --symmetric-key DEVICE_KEY

從註冊群組金鑰和註冊器中推導出裝置金鑰

az iot device registration create --id-scope 0ne00000000 \
  --registration-id device-01 --symmetric-key GROUP_KEY --compute-key

向PEM CSR註冊並申請營運證書

az iot device registration create --id-scope 0ne00000000 --registration-id device-01 \
  --symmetric-key DEVICE_KEY --csr ./device-01.csr --timeout 120

註冊 X.509 裝置憑證

az iot device registration create --id-scope 0ne00000000 \
  --registration-id device-01 --certificate-file-path ./device.pem \
  --key-file-path ./device-key.pem

必要參數

--registration-id --rid

裝置註冊標識碼或個別註冊標識碼。

選擇性參數

下列參數是選擇性參數，但視內容而定，命令可能需要一或多個參數才能成功執行。

--acquire-policy-token

自動取得 Azure 原則令牌以進行此資源操作。

屬性	值
參數群組:	Global Policy Arguments

--auth-type

指示操作是否應該自動產生政策金鑰，或使用目前的 Azure AD 會話。如果驗證類型是登入，而且會提供資源主機名，除非需要，否則將會略過資源查閱。您可以使用來設定預設值 az configure --defaults iothub-data-auth-type={auth-type-value}。

屬性	值
參數群組:	Access Control Arguments
預設值:	key
接受的值:	key, login

--certificate-file-path --cp

憑證 PEM 檔案的路徑。 x509 註冊的必要專案。

屬性	值
參數群組:	x509 Authentication Arguments

--change-reference

相關變更的 ID 是為此資源操作所參考的。

屬性	值
參數群組:	Global Policy Arguments

--ck --compute-key

可從 --symmetric-key 計算每個裝置的金鑰，或是由 --group-id 解析的註冊群組金鑰（含 --dps-name/--login）計算。無法與 X.509 輸入合併。

屬性	值
參數群組:	Symmetric Key Authentication Arguments
預設值:	False

--csr --csr-file-path

內嵌 PEM/base64 DER PKCS #10 CSR 或 CSR 檔案路徑。簽名必須有效，且通用名稱必須與註冊ID相符。請求傳送 base64 DER，沒有 PEM 標頭。

屬性	值
參數群組:	Certificate Issuance Arguments

--dps-name -n

Azure IoT 中樞 Device Provisioning Service 名稱。如果未提供 --login 或未提供 authenticaton 自變數，則為必要專案，且未提供 --id-scope。

屬性	值
參數群組:	DPS Identifier Arguments

--endorsement-key

進階 TPM 請求欄位由服務架構保留。必須搭配 --storage-root-key 一起使用。此指令不支援僅 TPM 用戶端的認證。

屬性	值
參數群組:	TPM Arguments

--enrollment-group-id --gid --group-id

註冊群組標識碼。只需要擷取驗證自變數。

--host --provisioning-host

DPS 裝置端點。若省略，端點會從所選的 DPS 資源衍生，然後退回到全域端點。

--id-scope --scope

Azure IoT 中樞 Device Provisioning Service 的 ID 範圍。 ID 範圍不會識別裝置端點：--dps-name 或 --login 在提供時仍會解析。僅有 -id-scope 與明確的裝置憑證時，會使用文件化的全域端點備援。

屬性	值
參數群組:	DPS Identifier Arguments

--key --symmetric-key

裝置註冊的對稱共用存取金鑰。

屬性	值
參數群組:	Symmetric Key Authentication Arguments

--key-file-path --kp

金鑰 PEM 檔案的路徑。 x509 註冊的必要專案。

屬性	值
參數群組:	x509 Authentication Arguments

--login -l

此指令支援帶有執行動作權限的實體連接字串。使用來避免透過「az login」的工作階段登入。若同時提供實體連接字串與名稱，則該連接字串會優先。如果未提供 --dps-name，或未提供 authenticaton 自變數和 --id-scope，則為必要專案。

屬性	值
參數群組:	DPS Identifier Arguments

--pass --passphrase

X.509私鑰的密碼短語。僅適用於 --certificate-file-path 與 --key-file-path 兩條路徑。

屬性	值
參數群組:	x509 Authentication Arguments

--payload

將註冊有效載荷視為 JSON 物件或 JSON 檔案的路徑。

--resource-group -g

資源組名。您可以使用 az configure --defaults group=<name>來設定預設群組。

--storage-root-key

進階 TPM 請求欄位由服務架構保留。必須搭配 ---endorsement-key 使用。此指令不支援僅 TPM 用戶端的認證。

屬性	值
參數群組:	TPM Arguments

--timeout

正整數硬 REST 註冊逾時可在數秒內完成，包括工作啟動、HTTP 與輪詢。排除初步ID範圍及自助式憑證發現。

全域參數

--debug

提高日誌詳細程度以顯示所有調試日誌。

屬性	值
預設值:	False

--help -h

顯示此說明訊息並結束。

--only-show-errors

只顯示錯誤，隱藏警告。

屬性	值
預設值:	False

--output -o

輸出格式。

屬性	值
預設值:	json
接受的值:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath 查詢字串。如需詳細資訊和範例，請參閱 http://jmespath.org/。

--subscription

訂用帳戶的名稱或標識碼。您可以使用 az account set -s NAME_OR_ID來設定預設訂用帳戶。

--verbose

增加記錄的詳細程度。針對完整偵錯記錄使用 --debug。

屬性	值
預設值:	False

az iot device registration operation-status

預覽