快速入門：佈建 X.509 憑證模擬裝置

發行項
10/24/2024

在本快速入門中，您會在 Windows 機器上建立模擬裝置。模擬裝置已設定為使用 X.509 憑證證明進行驗證。設定好裝置之後，便會使用 Azure IoT 中樞裝置佈建服務將其佈建至 IoT 中樞。

如果您不熟悉佈建程序，請檢閱佈建 (部分機器翻譯) 概觀。繼續之前，請務必完成使用 Azure 入口網站設定 IoT 中樞裝置佈建服務中的步驟。

本快速入門示範 Windows 型工作站的解決方案。不過，您也可以在 Linux 上執行這些程序。如需 Linux 的範例，請參閱教學課程：針對地理延遲來佈建 (部分機器翻譯)。

必要條件

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。
完成透過 Azure 入口網站來設定 IoT 中樞裝置佈建服務中的步驟。

下列必要條件適用於 Windows 開發環境。針對 Linux 或 macOS，請參閱 SDK 文件中準備您的開發環境中的適當章節。

安裝 Visual Studio 2022 並啟用 [使用 C++ 的桌面開發] 工作負載。也支援 Visual Studio 2015、Visual Studio 2017 和 Visual Studio 19。針對 Linux 或 macOS，請參閱 SDK 文件中準備您的開發環境中的適當章節。
下載最新版的 CMake 建置系統。確定核取將 CMake 可執行檔新增至路徑的選項。

重要

在開始安裝 CMake 之前，請確認您的電腦上已安裝 Visual Studio 必要條件 (Visual Studio 和 [使用 C++ 的桌面開發] 工作負載)。在符合先決條件，並且驗證過下載項目之後，請安裝 CMake 建置系統。另請注意，舊版的 CMake 建置系統無法產生本文中所用的解決方案檔案。請務必使用最新版的 CMake。

下列必要條件適用於 Windows 開發環境。針對 Linux 或 macOS，請參閱 SDK 文件中準備您的開發環境中的適當章節。

在您的 Windows 型機器上安裝 .NET SDK 6.0 或更新版本。您可以使用下列命令來檢查您的版本。
```
dotnet --info
```

下列必要條件適用於 Windows 開發環境。針對 Linux 或 macOS，請參閱 SDK 文件中準備您的開發環境中的適當章節。

在您的電腦上安裝 Node.js v4.0 或更新版本。

下列必要條件適用於 Windows 開發環境。

在您的電腦上安裝 Python 3.6 或更新版本。

下列必要條件適用於 Windows 開發環境。針對 Linux 或 macOS，請參閱 SDK 文件中準備您的開發環境中的適當章節。

在您的電腦上安裝 Java SE 開發套件 8 或更新版本。
下載並安裝 Maven。

安裝最新版的 Git。確定 Git 已新增至可存取命令視窗的環境變數中。請參閱 Software Freedom Conservancy 的 Git 用戶端工具以取得要安裝的最新版 git 工具，其中包括 Git Bash (您可用來與本機 Git 存放庫互動的命令列應用程式)。
確定您的電腦上已安裝 OpenSSL。在 Windows 上安裝 Git 會同時安裝 OpenSSL。您可以從 Git Bash 命令提示字元存取 OpenSSL。若要確認已安裝 OpenSSL，請開啟 Git Bash 命令提示字元，然後輸入 openssl version。

注意

除非您熟悉 OpenSSL 並已在 Windows 電腦上進行安裝，否則建議您從 Git Bash 命令提示字元使用 OpenSSL。或者，您可以選擇下載原始程式碼並建置 OpenSSL。若要深入瞭解，請參閱 OpenSSL 下載頁面。您也可以下載從第三方預建的 OpenSSL。若要深入瞭解，請參閱 OpenSSL Wiki。 Microsoft 不保證從第三方下載的套件有效。如果您選擇建置或下載 OpenSSL，請確定您的路徑可存取 OpenSSL 二進位檔，並將 OPENSSL_CNF 環境變數設定為 openssl.cnf 檔案的路徑。
開啟 Windows 命令提示字元和 Git Bash 命令提示字元。

本快速入門中的步驟假設您使用 Windows 電腦，並在安裝 Git 的過程中安裝 OpenSSL。您會使用 Git Bash 命令提示字元來發出 OpenSSL 命令，並使用 Windows 命令提示字元來發出其他所有命令。如果您使用 Linux，您可以從 Bash 殼層發出所有命令。

準備您的開發環境

在本節中，您會準備用來建置 Azure IoT C SDK (英文) 的開發環境。範例程式碼會在裝置的開機順序期間嘗試佈建裝置。

開啟網頁瀏覽器，然後前往 Azure IoT C SDK 的 [版本] 頁面。
選取頁面頂端的 [標籤] 索引標籤。
複製最新版 Azure IoT C SDK 的標籤名稱。
在您的 Windows 命令提示字元中，執行下列命令來複製最新版適用於 C 的 Azure IoT 裝置 SDK GitHub 存放庫。將 <release-tag> 取代為您在上一個步驟中複製的標籤，例如：lts_01_2023。
```
git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init
```
此作業可能需要幾分鐘的時間才能完成。
作業完成時，請從 azure-iot-sdk-c 目錄執行下列命令：
```
mkdir cmake
cd cmake
```
程式碼範例會使用 X.509 憑證來提供透過 X.509 驗證的證明。執行下列命令以建置開發平台專屬的 SDK 版本，其包含裝置佈建用戶端。 cmake 目錄中會產生模擬裝置的 Visual Studio 解決方案。

在下列命令中指定與 -Dhsm_custom_lib 搭配使用的路徑時，請務必使用您先前在 cmake 目錄中建立之程式庫的絕對路徑。所顯示的路徑假設您已複製 C 磁碟機根目錄中的 C SDK。如果您使用其他目錄，請據以調整路徑。
- Windows
- Linux
```
cmake -Duse_prov_client:BOOL=ON -Dhsm_custom_lib=c:/azure-iot-sdk-c/cmake/provisioning_client/samples/custom_hsm_example/Debug/custom_hsm_example.lib ..
```
```
cmake -Duse_prov_client:BOOL=ON -Dhsm_custom_lib=/home/<USER>/azure-iot-sdk-c/cmake/provisioning_client/samples/custom_hsm_example/custom_hsm_example.a ..
```

提示

如果 cmake 找不到 C++ 編譯器，您在執行上述命令時，可能會收到建置錯誤。如果發生這種情況，請嘗試在 Visual Studio 命令提示字元中執行命令。

建置成功時，最後幾行輸出會類似於下列輸出：

-- Building for: Visual Studio 17 2022
-- Selecting Windows SDK version 10.0.19041.0 to target Windows 10.0.22000.
-- The C compiler identification is MSVC 19.32.31329.0
-- The CXX compiler identification is MSVC 19.32.31329.0

...

-- Configuring done
-- Generating done
-- Build files have been written to: C:/azure-iot-sdk-c/cmake

在您的 Windows 命令提示字元中，使用下列命令複製適用於 C# 的 Azure IoT SDK GitHub 存放庫：

git clone https://github.com/Azure/azure-iot-sdk-csharp.git

在您的 Windows 命令提示字元中，使用下列命令複製適用於 Node.js 的 Azure IoT SDK GitHub 存放庫：

git clone https://github.com/Azure/azure-iot-sdk-node.git

在您的 Windows 命令提示字元中，使用下列命令複製適用於 Python 的 Azure IoT 裝置 SDK GitHub 存放庫：

git clone -b v2 https://github.com/Azure/azure-iot-sdk-python.git --recursive

注意

本教學課程中所使用的範例位於 azure-iot-sdk-python 存放庫的 v2 分支中。提供 V3 版的 Python SDK 以在搶鮮版 (Beta) 中使用。

在您的 Windows 命令提示字元中，使用下列命令複製適用於 Java 的 Azure IoT 範例 GitHub 存放庫：
```
git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
```
移至 azure-iot-sdk-java 根目錄並建置專案，以下載所有所需套件。
```
cd azure-iot-sdk-java
mvn install -DskipTests=true
```

建立自我簽署的 X.509 裝置憑證

在本節中，您會使用 OpenSSL 來建立自我簽署的 X.509 憑證和私密金鑰鑰。此憑證會上傳至佈建服務執行個體，並由服務驗證。

警告

本快速入門中使用 OpenSSL 建立的憑證僅適用於開發測試。請勿在生產環境中使用這些憑證。這些憑證會在 30 天后到後，而且可能包含硬式編碼的密碼，例如 1234。若要了解如何取得生產環境適用的憑證，請參閱 Azure IoT 中樞文件中的如何取得 X.509 CA 憑證。

在 Git Bash 提示字元中執行本節中的步驟。

在 Git Bash 提示字元中，瀏覽至您想要建立憑證的目錄。

執行以下命令：

Windows
Linux

winpty openssl req -outform PEM -x509 -sha256 -newkey rsa:4096 -keyout device-key.pem -out device-cert.pem -days 30 -extensions usr_cert -addext extendedKeyUsage=clientAuth -subj "//CN=my-x509-device"

重要

只需要針對主體名稱提供的額外正斜線 (//CN=my-x509-device) 以在 Windows 平台上使用 Git 逸出字串。

openssl req -outform PEM -x509 -sha256 -newkey rsa:4096 -keyout device-key.pem -out device-cert.pem -days 30 -extensions usr_cert -addext extendedKeyUsage=clientAuth -subj "/CN=my-x509-device"

當系統要求您輸入 PEM 複雜密碼：時，請使用複雜密碼 1234。
當系統要求驗證 - 輸入 PEM 複雜密碼：時，請再次使用複雜密碼 1234。

裝置憑證檔案 (device-cert.pem) 和私密金鑰檔案 (device-key.pem) 現在應該會在您執行 openssl 命令的目錄中產生。

憑證檔案的主體一般名稱 (CN) 設定為 my-x509-device。針對以 X.509 為基礎的註冊，註冊識別碼設定為通用名稱。註冊識別碼是一組不區分大小寫的字串，由英數字元和 '-'、'.'、'_'、':' 等特殊字元組成。最後一個字元必須是英數字元或虛線 ('-')。通用名稱必須遵循此格式。 DPS 支援最多 128 個字元的註冊識別碼；不過，X.509 憑證中主體通用名稱的最大長度為 64 個字元。因此，使用 X.509 憑證時，註冊識別碼限制為 64 個字元。

憑證檔案是以Base 64編碼。若要檢視主體一般名稱 (CN) 和其他憑證檔案的屬性，請輸入下列命令：

Windows
Linux

winpty openssl x509 -in device-cert.pem -text -noout

openssl x509 -in device-cert.pem -text -noout

Certificate:
Data:
    Version: 3 (0x2)
    Serial Number:
        77:3e:1d:e4:7e:c8:40:14:08:c6:09:75:50:9c:1a:35:6e:19:52:e2
    Signature Algorithm: sha256WithRSAEncryption
    Issuer: CN = my-x509-device
    Validity
        Not Before: May  5 21:41:42 2022 GMT
        Not After : Jun  4 21:41:42 2022 GMT
    Subject: CN = my-x509-device
    Subject Public Key Info:
        Public Key Algorithm: rsaEncryption
            RSA Public-Key: (4096 bit)
            Modulus:
                00:d2:94:37:d6:1b:f7:43:b4:21:c6:08:1a:d6:d7:
                e6:40:44:4e:4d:24:41:6c:3e:8c:b2:2c:b0:23:29:
                ...
                23:6e:58:76:45:18:03:dc:2e:9d:3f:ac:a3:5c:1f:
                9f:66:b0:05:d5:1c:fe:69:de:a9:09:13:28:c6:85:
                0e:cd:53
            Exponent: 65537 (0x10001)
    X509v3 extensions:
        X509v3 Basic Constraints:
            CA:FALSE
        Netscape Comment:
            OpenSSL Generated Certificate
        X509v3 Subject Key Identifier:
            63:C0:B5:93:BF:29:F8:57:F8:F9:26:44:70:6F:9B:A4:C7:E3:75:18
        X509v3 Authority Key Identifier:
            keyid:63:C0:B5:93:BF:29:F8:57:F8:F9:26:44:70:6F:9B:A4:C7:E3:75:18

        X509v3 Extended Key Usage:
            TLS Web Client Authentication
Signature Algorithm: sha256WithRSAEncryption
     82:8a:98:f8:47:00:85:be:21:15:64:b9:22:b0:13:cc:9e:9a:
     ed:f5:93:b9:4b:57:0f:79:85:9d:89:47:69:95:65:5e:b3:b1:
     ...
     cc:b2:20:9a:b7:f2:5e:6b:81:a1:04:93:e9:2b:92:62:e0:1c:
     ac:d2:49:b9:36:d2:b0:21

範例程式碼需要未加密的私密金鑰。執行下列命令以建立未加密的私密金鑰：

Windows
Linux

winpty openssl rsa -in device-key.pem -out unencrypted-device-key.pem

openssl rsa -in device-key.pem -out unencrypted-device-key.pem

當系統要求您輸入 device-key.pem: 的複雜密碼時，請使用您先前執行的相同複雜密碼 1234。

讓 Git Bash 提示保持開啟。稍後在本快速入門中需要用到。

C# 範例程式碼設定為使用儲存在受密碼保護之 PKCS#12 格式檔案 (certificate.pfx) 中的 X.509 憑證。您仍然需要剛才所建立的 PEM 格式公開金鑰檔案 (device-cert.pem)，以稍後在本快速入門中建立個別註冊項目。

若要產生範例預期的 PKCS12 格式檔案，請輸入下列命令：

Windows
Linux

winpty openssl pkcs12 -inkey device-key.pem -in device-cert.pem -export -out certificate.pfx

openssl pkcs12 -inkey device-key.pem -in device-cert.pem -export -out certificate.pfx

當系統要求您輸入 device-key.pem: 的複雜密碼時，請使用您先前執行的相同複雜密碼 1234。
當系統要求輸入匯出密碼：時，請使用密碼 1234。
當系統要求驗證 - 輸入匯出密碼：時，請再次使用密碼 1234。

PKCS12 格式化的憑證檔案 (certificate.pfx) 現在應該會在您執行 openssl 命令的目錄中產生。
將 PKCS12 格式化的憑證檔案複製到 X.509 裝置佈建範例的專案目錄。提供的路徑是相對於您所下載範例存放庫的位置。
```
cp certificate.pfx ./azure-iot-sdk-csharp/provisioning/device/samples/"Getting Started"/X509Sample
```

本快速入門的其餘部分不需要 Git Bash 提示。不過，如果後續步驟發生問題，您可能想要將其保持在開啟狀態以檢查憑證。

範例程式碼需要未加密的私密金鑰。執行下列命令以建立未加密的私密金鑰：

Windows
Linux

winpty openssl rsa -in device-key.pem -out unencrypted-device-key.pem

openssl rsa -in device-key.pem -out unencrypted-device-key.pem

當系統要求您輸入 device-key.pem: 的複雜密碼時，請使用您先前執行的相同複雜密碼 1234。
將裝置憑證和未加密的私密金鑰複製到 X.509 裝置裝置佈建的專案目錄。提供的路徑是相對於您所下載 SDK 的位置。
```
cp device-cert.pem ./azure-iot-sdk-node/provisioning/device/samples
cp unencrypted-device-key.pem ./azure-iot-sdk-node/provisioning/device/samples
```

本快速入門的其餘部分不需要 Git Bash 提示。不過，如果後續步驟發生問題，您可能想要將其保持在開啟狀態以檢查憑證。

將裝置憑證和私密金鑰複製到 X.509 裝置裝置佈建的專案目錄。提供的路徑是相對於您所下載 SDK 的位置。

cp device-cert.pem ./azure-iot-sdk-python/samples/async-hub-scenarios
cp device-key.pem ./azure-iot-sdk-python/samples/async-hub-scenarios

本快速入門的其餘部分不需要 Git Bash 提示。不過，如果後續步驟發生問題，您可能想要將其保持在開啟狀態以檢查憑證。

Java 範例程式碼需要未加密的私密金鑰。執行下列命令以建立未加密的私密金鑰：

Windows
Linux

winpty openssl pkey -in device-key.pem -out unencrypted-device-key.pem

openssl pkey -in device-key.pem -out unencrypted-device-key.pem

當系統要求您輸入 device-key.pem: 的複雜密碼時，請使用您先前執行的相同複雜密碼 1234。

讓 Git Bash 提示保持開啟。稍後在本快速入門中需要用到。

建立裝置註冊

Azure IoT 裝置佈建服務支援兩種類型的註冊：

註冊群組：用來註冊多個相關的裝置。
個別註冊：用來註冊單一裝置。

本文會針對要使用 IoT 中樞來佈建的單一裝置示範其個別註冊。

登入 Azure 入口網站，並瀏覽至您的裝置佈建服務執行個體。
從導覽功能表的 [設定] 區段選取 [管理註冊]。
選取 [個別註冊] 索引標籤，然後選取 [新增個別註冊]。

在 [新增註冊] 頁面的 [註冊 + 佈建] 上，提供下列資訊以設定註冊詳細資料：

欄位	描述
證明	選取 [X.509 用戶端憑證] 作為證明機制。
X.509 憑證設定	上傳將用於驗證此註冊裝置的一或兩個憑證。
佈建狀態	如果您想要讓此註冊可用於佈建其裝置，請核取 [啟用此註冊] 方塊。如果您想要停用註冊，請取消核取此方塊。您之後無法變更此設定。
重新佈建原則	選擇重新佈建原則，以反映您希望 DPS 如何處理要求重新佈建的裝置。如需詳細資訊，請參閱重新佈建原則 (部分機器翻譯)。

選取 [下一步: IoT 中樞]。

在 [新增註冊] 頁面的 [IoT 中樞] 索引標籤上，提供下列資訊以判斷註冊可將裝置佈建到哪些 IoT 中樞：

欄位	描述
目標 IoT 中樞	選取一或多個連結的 IoT 中樞，或是新增 IoT 中樞的連結。若要深入了解如何將 IoT 中樞連結到 DPS 執行個體，請參閱如何連結和管理 IoT 中樞。
配置原則	如果您選取了多個連結的 IoT 中樞，請選取要如何將裝置指派給不同的中樞。若要深入了解配置原則，請參閱如何使用配置原則。如果您只選取一個連結的 IoT 中樞，建議您使用 [權重相等的分佈] 原則。

選取 [下一步: 裝置設定]

在 [新增註冊] 頁面的 [裝置設定] 索引標籤上，提供下列資訊以定義新佈建裝置的設定方式：

欄位	描述
裝置識別碼	提供將在 IoT 中樞中指派至已佈建裝置的裝置識別碼。如果您未提供裝置識別碼，則會使用註冊識別碼。
IoT Edge	如果已佈建的裝置會執行 Azure IoT Edge (部分機器翻譯)，請核取 [在已佈建的裝置上啟用 IoT Edge]。如果此註冊適用於未啟用 IoT Edge 的裝置，請取消核取此方塊。
裝置標籤	使用此文字輸入框來提供您要為已佈建裝置的裝置對應項套用的任何標籤。
所需屬性	使用此文字輸入框來提供您要為已佈建裝置的裝置對應項套用的任何所需屬性。

如需詳細資訊，請參閱了解和使用 Azure IoT 中樞的裝置對應項。

完成時，選取 [下一步:檢閱 + 建立]。
在 [檢閱 + 建立] 索引標籤上，確認所有值，然後選取 [建立]。

準備並執行裝置佈建程式碼

在本節中，您可以更新範例程式碼來將裝置的開機順序傳送至裝置佈建服務執行個體。此開機順序會使裝置經過辨識，並指派給連結至 DPS 執行個體的 IoT 中樞。

在本節中，您會使用 Git Bash 命令提示字元和 Visual Studio IDE。

設定佈建裝置程式碼

在本節中，您會使用自己的裝置佈建服務執行個體資訊來更新範例程式碼。

在 Azure 入口網站中，選取您裝置佈建服務的 [概觀] 索引標籤。
複製 [識別碼範圍] 值。
啟動 Visual Studio 並開啟新的解決方案檔，此檔案是在您於 azure-iot-sdk-c git 存放庫之根目錄中建立的 cmake 目錄中建立。解決方案檔命名為 azure_iot_sdks.sln。
在 Visual Studio 的方案總管中，瀏覽至 [Provision_Samples] > [prov_dev_client_sample] > [來源檔案] 並開啟 prov_dev_client_sample.c。
找出 id_scope 常數，並將其值取代為您在步驟 2 中複製的 [識別碼範圍] 值。
```
static const char* id_scope = "0ne00000A0A";
```

在相同的檔案中找出 main() 函式的定義。確定 hsm_type 變數已設定為 SECURE_DEVICE_TYPE_X509。

SECURE_DEVICE_TYPE hsm_type;
//hsm_type = SECURE_DEVICE_TYPE_TPM;
hsm_type = SECURE_DEVICE_TYPE_X509;
//hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;

儲存您的變更。
以滑鼠右鍵按一下 [prov_dev_client_sample] 專案，然後選取 [設為起始專案]。

設定自訂 HSM 虛設常式程式碼

與實際安全硬體型存放裝置互動的細節會因硬體而異。因此，本快速入門中模擬裝置所使用的憑證和私密金鑰會在自訂硬體安全模組 (HSM) 虛設常式程式碼中進行硬式編碼。

若要更新自訂 HSM 虛設常式程式碼，以模擬識別碼為 my-x509-device 的裝置身分識別：

在 Visual Studio 的方案總管中，瀏覽至 [Provision_Samples] > [custom_hsm_example] > [來源檔案] 並開啟 custom_hsm_example.c。
使用您在產生裝置憑證 my-x509-device 時所使用的一般名稱，更新 COMMON_NAME 字串常數的字串值。
```
static const char* const COMMON_NAME = "my-x509-device";
```
使用您先前產生的裝置憑證 device-cert.pem，更新 CERTIFICATE 常數字串的字串值。

範例中的憑證文字語法必須遵循下列模式，不帶有額外空格，或由 Visual Studio 執行的剖析。
```
static const char* const CERTIFICATE = "-----BEGIN CERTIFICATE-----\n"
"MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n"
    ...
"MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n"
"-----END CERTIFICATE-----";        
```
手動更新此字串值很容易發生錯誤。若要產生適當的語法，您可以將下列命令複製並貼到 Git Bash 命令提示字元中，然後按 ENTER 鍵。此命令會產生 CERTIFICATE 字串常數值的語法，並將其寫入到輸出。
```
sed -e 's/^/"/;$ !s/$/""\\n"/;$ s/$/"/' device-cert.pem
```
複製並貼上常數值的輸出憑證文字。
將 PRIVATE_KEY 常數的字串值更新為您裝置憑證未加密的私密金鑰 unencrypted-device-key.pem。

私密金鑰文字的語法必須遵循下列模式，才不會有額外的空格，且 Visual Studio 也不會剖析。
```
static const char* const PRIVATE_KEY = "-----BEGIN RSA PRIVATE KEY-----\n"
"MIIJJwIBAAKCAgEAtjvKQjIhp0EE1PoADL1rfF/W6v4vlAzOSifKSQsaPeebqg8U\n"
    ...
"X7fi9OZ26QpnkS5QjjPTYI/wwn0J9YAwNfKSlNeXTJDfJ+KpjXBcvaLxeBQbQhij\n"
"-----END RSA PRIVATE KEY-----";
```
手動更新此字串值很容易發生錯誤。若要產生適當的語法，您可以將下列命令複製並貼到 Git Bash 命令提示字元中，然後按 ENTER 鍵。此命令會產生 PRIVATE_KEY 字串常數值的語法，並將其寫入到輸出。
```
sed -e 's/^/"/;$ !s/$/""\\n"/;$ s/$/"/' unencrypted-device-key.pem
```
複製並貼上常數值的輸出私密金鑰文字。
儲存您的變更。
以滑鼠右鍵按一下 custom_hsm_-_example 專案，然後選取 [建置]。

重要

在下一節中，您必須先建置 custom_hsm_example 專案，再建置方案的其餘部分。

執行範例

在 Visual Studio 功能表中，選取 [偵錯]>[啟動但不偵錯] 以執行解決方案。如果系統提示您重新建置專案，請選取 [是]，以在執行前重新建置專案。

下列輸出範例指出模擬裝置 my-x509-device 已成功啟動並連線到佈建服務。裝置已指派至 IoT 中樞資訊並已註冊：
```
Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-iot-hub-2.azure-devices.net, deviceId: my-x509-device
Press enter key to exit:
```

在本節中，您會使用 Windows 命令提示字元。

在 Azure 入口網站中，選取您裝置佈建服務的 [概觀] 索引標籤。
複製 [識別碼範圍] 值。
在您的 Windows 命令提示字元中，變更為 X509Sample 目錄。此目錄位於您在電腦上複製範例的目的地 .\azure-iot-sdk-csharp\provisioning\device\samples\getting started\X509Sample 目錄中。
輸入下列命令來建置並執行 X.509 裝置佈建範例 (以您在上一節中複製的識別碼範圍取代 <IDScope> 值。憑證檔案預設為 ./certificate.pfx，並且系統會提示您輸入 .pfx 密碼。
```
dotnet run -- -s <IDScope>
```
如果您想要將憑證和密碼作為參數傳遞，則可以使用下列格式。

注意

執行應用程式時，還可以傳遞其他參數來變更 TransportType (-t) 和 GlobalDeviceEndpoint (-g)。
```
dotnet run -- -s 0ne00000A0A -c certificate.pfx -p 1234
```

裝置會連線到 DPS，並指派給 IoT 中樞。然後，裝置會將遙測訊息傳送至 IoT 中樞。

Loading the certificate...
Enter the PFX password for certificate.pfx:
****
Found certificate: A33DB11B8883DEE5B1690ACFEAAB69E8E928080B CN=my-x509-device; PrivateKey: True
Using certificate A33DB11B8883DEE5B1690ACFEAAB69E8E928080B CN=my-x509-device
Initializing the device provisioning client...
Initialized for registration Id my-x509-device.
Registering with the device provisioning service...
Registration status: Assigned.
Device my-x509-device registered to MyExampleHub.azure-devices.net.
Creating X509 authentication for IoT Hub...
Testing the provisioned device with IoT Hub...
Sending a telemetry message...
Finished.

在本節中，您會使用 Windows 命令提示字元。

在 Azure 入口網站中，選取您裝置佈建服務的 [概觀] 索引標籤。
複製 [識別碼範圍] 值。

在您的 Windows 命令提示字元中，前往範例目錄，然後安裝範例所需的套件。所顯示的路徑是您複製 SDK 之目的地位置的相對路徑。

cd .\azure-iot-sdk-node\provisioning\device\samples
npm install

此範例使用五個環境變數透過 DPS 來驗證和佈建 IoT 裝置。這些環境變數包括：

變數名稱	描述
`PROVISIONING_HOST`	用於連線到 DPS 執行個體的端點。在本快速入門中，請使用全域端點 `global.azure-devices-provisioning.net`。
`PROVISIONING_IDSCOPE`	您 DPS 執行個體的識別碼範圍。
`PROVISIONING_REGISTRATION_ID`	您裝置的註冊識別碼。必須符合裝置憑證中的主體通用名稱。
`CERTIFICATE_FILE`	您裝置憑證檔案的路徑。
`KEY_FILE`	您裝置私密金鑰的路徑。

新增全域裝置端點和識別碼範圍的環境變數。將 <id-scope> 取代為您在步驟 2 中複製的值。
```
set PROVISIONING_HOST=global.azure-devices-provisioning.net
set PROVISIONING_IDSCOPE=<id-scope>
```
設定裝置註冊識別碼的環境變數。 IoT 裝置的註冊識別碼必須符合其裝置憑證上的主體通用名稱。如果您遵循本快速入門中的步驟來產生自我簽署的測試憑證，則 my-x509-device 同時會是裝置的主體名稱和註冊識別碼。
```
set PROVISIONING_REGISTRATION_ID=my-x509-device
```

設定裝置憑證和 (未加密) 裝置私密金鑰的環境變數。

set CERTIFICATE_FILE=.\device-cert.pem
set KEY_FILE=.\unencrypted-device-key.pem

執行範例，並確認已成功佈建裝置。

node register_x509.js

您應該會看到類似下列範例的結果：

registration succeeded
assigned hub=contoso-hub-2.azure-devices.net
deviceId=my-x509-device
Client connected
send status: MessageEnqueued

在本節中，您會使用 Windows 命令提示字元。

在 Azure 入口網站中，選取您裝置佈建服務的 [概觀] 索引標籤。
複製 [識別碼範圍] 和 [全域裝置端點] 值。

在您的 Windows 命令提示字元中，前往 provision_x509.py 範例的目錄。所顯示的路徑是您複製 SDK 之目的地位置的相對路徑。

cd ./azure-iot-sdk-python/samples/async-hub-scenarios

此範例使用六個環境變數透過 DPS 來驗證和佈建 IoT 裝置。這些環境變數包括：

變數名稱	描述
`PROVISIONING_HOST`	用於連線到 DPS 執行個體的全域端點。
`PROVISIONING_IDSCOPE`	您 DPS 執行個體的識別碼範圍。
`DPS_X509_REGISTRATION_ID`	您裝置的註冊識別碼。其也必須符合裝置憑證中的主體名稱。
`X509_CERT_FILE`	您裝置憑證檔案的路徑。
`X509_KEY_FILE`	您裝置憑證私密金鑰檔案的路徑。
`PASS_PHRASE`	用於加密憑證和私密金鑰檔案的複雜密碼 (`1234`)。

新增全域裝置端點和識別碼範圍的環境變數。

set PROVISIONING_HOST=global.azure-devices-provisioning.net
set PROVISIONING_IDSCOPE=<ID scope for your DPS resource>

設定註冊識別碼的環境變數。 IoT 裝置的註冊識別碼必須符合其裝置憑證上的主體名稱。如果您遵循本快速入門中的步驟來產生自我簽署的測試憑證，則 my-x509-device 同時會是裝置的主體名稱和註冊識別碼。
```
set DPS_X509_REGISTRATION_ID=my-x509-device
```

設定憑證檔案、私密金鑰檔案和複雜密碼的環境變數。

set X509_CERT_FILE=./device-cert.pem
set X509_KEY_FILE=./device-key.pem
set PASS_PHRASE=1234

檢閱 provision_x509.py 的程式碼。如果您未使用 Python 3.7 版或更新版本，請進行此處所述的程式碼變更以取代 asyncio.run(main())，並儲存變更。

執行範例。此範例會連線到 DPS，以將裝置佈建到 IoT 中樞。佈建裝置之後，此範例會將一些測試訊息傳送至 IoT 中樞。

$ python azure-iot-sdk-python/samples/async-hub-scenarios/provision_x509.py
RegistrationStage(RequestAndResponseOperation): Op will transition into polling after interval 2.  Setting timer.
The complete registration result is
my-x509-device
TestHub12345.azure-devices.net
initialAssignment
null
Will send telemetry from the provisioned device
sending message #4
sending message #7
sending message #2
sending message #8
sending message #5
sending message #9
sending message #1
sending message #6
sending message #10
sending message #3
done sending message #4
done sending message #7
done sending message #2
done sending message #8
done sending message #5
done sending message #9
done sending message #1
done sending message #6
done sending message #10
done sending message #3

在本節中，您會使用 Windows 命令提示字元和 Git Bash 命令提示字元。

在 Azure 入口網站中，選取您裝置佈建服務的 [概觀] 索引標籤。
複製 [識別碼範圍] 和 [全域裝置端點] 值。
在您的 Windows 命令提示字元中，瀏覽至範例專案資料夾。所顯示的路徑是您複製 SDK 之目的地位置的相對路徑
```
cd .\azure-iot-sdk-java\provisioning\provisioning-device-client-samples\provisioning-X509-sample
```
在範例程式碼中輸入佈建服務和 X.509 身分識別資訊。這項資訊會在佈建期間用於證明模擬裝置，再註冊裝置。
1. 在您慣用的文字編輯器中開啟檔案 .\src\main\java\samples\com\microsoft\azure\sdk\iot\ProvisioningX509Sample.java。
2. 使用您先前複製的識別碼範圍和佈建服務全域端點來更新下列值。
```
private static final String idScope = "[Your ID scope here]";
private static final String globalEndpoint = "[Your Provisioning Service Global Endpoint here]";
private static final ProvisioningDeviceClientTransportProtocol PROVISIONING_DEVICE_CLIENT_TRANSPORT_PROTOCOL = ProvisioningDeviceClientTransportProtocol.HTTPS;
```
3. 將 leafPublicPem 常數字串的值更新為您憑證的值 device-cert.pem。
  
  憑證文字語法必須遵循下列模式，沒有額外的空格或字元。
```
private static final String leafPublicPem = "-----BEGIN CERTIFICATE-----\n" +
"MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n" +
    ...
"MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n" +
"-----END CERTIFICATE-----";        
```
  手動更新此字串值很容易發生錯誤。若要產生適當的語法，您可以將下列命令複製並貼到 Git Bash 命令提示字元中，然後按 ENTER 鍵。此命令會產生 leafPublicPem 字串常數值的語法，並將其寫入到輸出。
```
sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' device-cert.pem
```
  複製並貼上常數值的輸出憑證文字。
4. 將 leafPrivateKey 常數的字串值更新為您裝置憑證未加密的私密金鑰 unencrypted-device-key.pem。
  
  私密金鑰文字的語法必須遵循下列模式，沒有額外的空格或字元。
```
private static final String leafPrivateKey = "-----BEGIN PRIVATE KEY-----\n" +
"MIIJJwIBAAKCAgEAtjvKQjIhp0EE1PoADL1rfF/W6v4vlAzOSifKSQsaPeebqg8U\n" +
    ...
"X7fi9OZ26QpnkS5QjjPTYI/wwn0J9YAwNfKSlNeXTJDfJ+KpjXBcvaLxeBQbQhij\n" +
"-----END PRIVATE KEY-----";
```
  手動更新此字串值很容易發生錯誤。若要產生適當的語法，您可以將下列命令複製並貼到 Git Bash 命令提示字元中，然後按 ENTER 鍵。此命令會產生 leafPrivateKey 字串常數值的語法，並將其寫入到輸出。
```
sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' unencrypted-device-key.pem
```
  複製並貼上常數值的輸出私密金鑰文字。
5. 儲存您的變更。
建置範例，然後前往 target 資料夾。
```
mvn clean install
cd target
```

此組建會以 provisioning-x509-sample-{version}-with-deps.jar 的檔案格式輸出 target 資料夾中的 .jar 檔案，例如：provisioning-x509-sample-1.8.1-with-deps.jar。執行 .jar 檔案。您可能需要取代下列命令中的版本。

java -jar ./provisioning-x509-sample-1.8.1-with-deps.jar

此範例會連線到 DPS，以將裝置佈建到 IoT 中樞。佈建裝置之後，此範例會將一些測試訊息傳送至 IoT 中樞。

Starting...
Beginning setup.
WARNING: sun.reflect.Reflection.getCallerClass is not supported. This will impact performance.
2022-05-11 09:42:05,025 DEBUG (main) [com.microsoft.azure.sdk.iot.provisioning.device.ProvisioningDeviceClient] - Initialized a ProvisioningDeviceClient instance using SDK version 2.0.0
2022-05-11 09:42:05,027 DEBUG (main) [com.microsoft.azure.sdk.iot.provisioning.device.ProvisioningDeviceClient] - Starting provisioning thread...
Waiting for Provisioning Service to register
2022-05-11 09:42:05,030 INFO (global.azure-devices-provisioning.net-6255a8ba-CxnPendingConnectionId-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Opening the connection to device provisioning service...
2022-05-11 09:42:05,252 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Connection to device provisioning service opened successfully, sending initial device registration message
2022-05-11 09:42:05,286 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-RegisterTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.RegisterTask] - Authenticating with device provisioning service using x509 certificates
2022-05-11 09:42:06,083 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Waiting for device provisioning service to provision this device...
2022-05-11 09:42:06,083 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Current provisioning status: ASSIGNING
Waiting for Provisioning Service to register
2022-05-11 09:42:15,685 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Device provisioning service assigned the device successfully
IotHUb Uri : MyExampleHub.azure-devices.net
Device ID : java-device-01
2022-05-11 09:42:25,057 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2022-05-11 09:42:25,080 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2022-05-11 09:42:25,087 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Initialized a DeviceClient instance using SDK version 2.0.3
2022-05-11 09:42:25,129 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - Opening MQTT connection...
2022-05-11 09:42:25,150 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT CONNECT packet...
2022-05-11 09:42:25,982 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT CONNECT packet was acknowledged
2022-05-11 09:42:25,983 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT SUBSCRIBE packet for topic devices/java-device-01/messages/devicebound/#
2022-05-11 09:42:26,068 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT SUBSCRIBE packet for topic devices/java-device-01/messages/devicebound/# was acknowledged
2022-05-11 09:42:26,068 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - MQTT connection opened successfully
2022-05-11 09:42:26,070 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - The connection to the IoT Hub has been established
2022-05-11 09:42:26,071 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Updating transport status to new status CONNECTED with reason CONNECTION_OK
2022-05-11 09:42:26,071 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceIO] - Starting worker threads
2022-05-11 09:42:26,073 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking connection status callbacks with new status details
2022-05-11 09:42:26,074 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Client connection opened successfully
2022-05-11 09:42:26,075 INFO (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Device client opened successfully
Sending message from device to IoT Hub...
2022-05-11 09:42:26,077 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Message was queued to be sent later ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [aaaa0000-bb11-2222-33cc-444444dddddd] )
Press any key to exit...
2022-05-11 09:42:26,079 DEBUG (MyExampleHub.azure-devices.net-java-device-01-ee6c362d-Cxn7a1fb819-e46d-4658-9b03-ca50c88c0440-azure-iot-sdk-IotHubSendTask) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Sending message ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [aaaa0000-bb11-2222-33cc-444444dddddd] )
2022-05-11 09:42:26,422 DEBUG (MQTT Call: java-device-01) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - IotHub message was acknowledged. Checking if there is record of sending this message ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [aaaa0000-bb11-2222-33cc-444444dddddd] )
2022-05-11 09:42:26,425 DEBUG (MyExampleHub.azure-devices.net-java-device-01-ee6c362d-Cxn7a1fb819-e46d-4658-9b03-ca50c88c0440-azure-iot-sdk-IotHubSendTask) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking the callback function for sent message, IoT Hub responded to message ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [aaaa0000-bb11-2222-33cc-444444dddddd] ) with status OK
Message sent!

確認您的裝置佈建註冊

若要查看裝置所佈建至的 IoT 中樞，請檢查您先前建立之個別註冊的註冊詳細資料：

在 Azure 入口網站中，移至您的裝置佈建服務。
在 [設定] 功能表中，選取 [管理註冊]。
選取 [個別註冊]。您先前建立的 X.509 註冊項目 my-x509-device 應該會出現在清單中。
選取註冊項目。您裝置指派至的 IoT 中樞及其裝置識別碼會出現在 [註冊狀態] 之下。

若要確認 IoT 中樞內的裝置：

在 Azure 入口網站中，前往您裝置的指派目的地 IoT 中樞。
在 [裝置管理] 功能表中，選取 [裝置]。
如果您的裝置已成功佈建，其裝置識別碼 (my-x509-device) 應該會出現在清單中，且 [狀態] 會設定為 [已啟用]。如果您沒有看到裝置，請選取 [重新整理]。

重要

如果您在裝置的註冊項目中變更了初始裝置對應項狀態 (變更自預設值)，它即可從中樞提取所需的對應項狀態並採取適當的動作。如需詳細資訊，請參閱了解和使用 Azure IoT 中樞的裝置對應項

清除資源

如果您打算繼續使用並探索裝置用戶端範例，請勿清除在本快速入門中建立的資源。如果您不打算繼續，請使用下列步驟來刪除本快速入門建立的所有資源。

刪除您的裝置註冊

在您的電腦上關閉裝置用戶端範例輸出視窗。
從 Azure 入口網站中的左側功能表，選取 [所有資源]。
選取您的裝置佈建服務。
在 [設定] 功能表中，選取 [管理註冊]。
選取 [個別註冊] 索引標籤。
選取您在本快速入門中所註冊裝置的註冊識別碼旁的核取方塊。
在頁面頂端，選取 [刪除]。

從 IoT 中樞刪除裝置註冊

從 Azure 入口網站中的左側功能表，選取 [所有資源]。
選取您的 IoT 中樞。
在 [總管] 功能表中，選取 [IoT 裝置]。
選取您在本快速入門中所註冊裝置的裝置識別碼旁的核取方塊。
在頁面頂端，選取 [刪除]。

下一步

在本快速入門中，您已使用個別註冊，將單一裝置布建至IoT中樞。接下來，瞭解如何跨多個中樞布建多個裝置。

教學課程：使用自定義配置原則管理IoT中樞指派

共用方式為

快速入門：佈建 X.509 憑證模擬裝置

必要條件

準備您的開發環境

建立自我簽署的 X.509 裝置憑證

建立裝置註冊

準備並執行裝置佈建程式碼

設定佈建裝置程式碼

設定自訂 HSM 虛設常式程式碼

執行範例

確認您的裝置佈建註冊

清除資源

刪除您的裝置註冊

從 IoT 中樞刪除裝置註冊

下一步

意見反應

其他資源