快速入門：佈建模擬的對稱金鑰裝置

發行項
10/24/2024

在本快速入門中，您會在 Windows 機器上建立模擬裝置。模擬裝置會設定為使用對稱金鑰證明 (部分機器翻譯) 機制來進行驗證。設定好裝置之後，便會使用 Azure IoT 中樞裝置佈建服務將其佈建至 IoT 中樞。

如果您不熟悉佈建程序，請檢閱佈建 (部分機器翻譯) 概觀。

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

必要條件

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

如果您使用 Windows 開發環境，請安裝 Visual Studio 2019，並啟用「使用 C++ 的桌面開發」 (部分機器翻譯) 工作負載。也會支援 Visual Studio 2015 和 Visual Studio 2017。針對 Linux 或 macOS，請參閱 SDK 文件中準備您的開發環境中的適當章節。

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

安裝 Node.js v4.0+。

在您的 Windows 型機器上安裝 Python 3.7 或更新版本。您可以藉由執行 python --version 來檢查您的 Python 版本。

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

安裝最新版的 Git。確定 Git 已新增至可存取命令視窗的環境變數中。請參閱 Software Freedom Conservancy 的 Git 用戶端工具以取得要安裝的最新版 git 工具，其中包括 Git Bash (您可用來與本機 Git 存放庫互動的命令列應用程式)。

準備您的開發環境

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

下載最新的 CMake 建置系統 (英文)。

重要

在開始安裝 CMake 之前，請確認您的電腦上已安裝 Visual Studio 必要條件 (Visual Studio 和 [使用 C++ 的桌面開發] 工作負載)。在符合先決條件，並且驗證過下載項目之後，請安裝 CMake 建置系統。另請注意，舊版的 CMake 建置系統無法產生本文中所用的解決方案檔案。請務必使用最新版的 CMake。
開啟網頁瀏覽器，然後移至 Azure IoT C SDK 的 [版本] 頁面 (英文)。
選取頁面頂端的 [標籤] 索引標籤。
複製最新版 Azure IoT C SDK 的標籤名稱。
開啟命令提示字元或 Git Bash 殼層。執行下列命令以複製最新版的 Azure IoT 裝置 SDK for C (英文) 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
```
程式碼範例會使用對稱金鑰來提供證明。執行下列命令以建置開發用戶端平台專屬的 SDK 版本，其包含裝置佈建用戶端:
```
cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
```
提示

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

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

$ cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
-- Building for: Visual Studio 16 2019
-- Selecting Windows SDK version 10.0.19041.0 to target Windows 10.0.19042.
-- The C compiler identification is MSVC 19.29.30040.0
-- The CXX compiler identification is MSVC 19.29.30040.0

...

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

開啟 Git CMD 或 Git Bash 命令列環境。
使用下列命令複製 Azure IoT C# SDK (英文) GitHub 存放庫:
```
git clone https://github.com/Azure/azure-iot-sdk-csharp.git
```

開啟 Git CMD 或 Git Bash 命令列環境。
使用下列命令複製適用於 Node.js 的 Azure IoT SDK GitHub 存放庫：
```
git clone https://github.com/Azure/azure-iot-sdk-node.git --recursive
```

開啟 Git CMD 或 Git Bash 命令列環境。
使用下列命令複製 Azure IoT SDK for Python (英文) GitHub 存放庫：
```
git clone -b v2 https://github.com/Azure/azure-iot-sdk-python.git --recursive
```
注意

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

開啟 Git CMD 或 Git Bash 命令列環境。

使用下列命令複製 Azure IoT Java SDK (英文) 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
```

建立裝置註冊

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

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

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

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

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

欄位	描述
證明	選取 [對稱金鑰] 作為 [證明機制]。
對稱金鑰設定	如果您想要使用隨機產生的金鑰，請核取 [自動產生對稱金鑰] 方塊。如果您想要提供自己的金鑰，請取消核取此方塊。
註冊識別碼	為裝置提供唯一的註冊識別碼。
佈建狀態	如果您想要讓此註冊可用於佈建其裝置，請核取 [啟用此註冊] 方塊。如果您想要停用註冊，請取消核取此方塊。您之後無法變更此設定。
重新佈建原則	選擇重新佈建原則，以反映您希望 DPS 如何處理要求重新佈建的裝置。如需詳細資訊，請參閱重新佈建原則 (部分機器翻譯)。

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

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

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

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

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

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

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

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

在建立個別註冊後，便會產生「主要金鑰」和「次要金鑰」並將其新增至註冊項目。您會在本快速入門稍後的裝置範例中使用主要金鑰。

若要檢視模擬的對稱金鑰裝置註冊，請選取 [個別註冊] 索引標籤。
從個別註冊清單中選取裝置的註冊識別碼。
複製所產生 [主要金鑰] 的值。

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

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

範例佈建程式碼會依序完成下列工作：

使用下列三個參數，向裝置佈建資源驗證您的裝置:
- 裝置佈建服務的識別碼範圍
- 裝置註冊的註冊識別碼。
- 裝置註冊的主要對稱金鑰。
將裝置指派給已連結至裝置佈建服務執行個體的 IoT 中樞。

若要使用您的裝置資訊來更新並執行佈建範例:

在裝置佈建服務的主功能表中，選取 [概觀]。
複製 [識別碼範圍] 值。
在 Visual Studio 中，開啟透過執行 CMake 而產生的 azure_iot_sdks.sln 方案檔案。該方案檔案應位於下列位置：
```
\azure-iot-sdk-c\cmake\azure_iot_sdks.sln
```
提示

如果檔案不是在您的 cmake 目錄中產生，請確定您使用的是最新版本的 CMake 組建系統。
在 Visual Studio 的 [方案總管] 視窗中，移至 Provision_Samples 資料夾。展開名為 prov_dev_client_sample 的範例專案。展開 [來源檔案]，然後開啟 prov_dev_client_sample.c。
尋找 id_scope 常數，並將該值更換為您在步驟 2 複製的 [識別碼範圍] 值。
```
static const char* id_scope = "0ne00002193";
```

在相同的檔案中找出 main() 函式的定義。確定 hsm_type 變數已設定為 SECURE_DEVICE_TYPE_SYMMETRIC_KEY，如下列範例所示：

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.c 中尋找 prov_dev_set_symmetric_key_info() 的呼叫。

// Set the symmetric key if using they auth type
//prov_dev_set_symmetric_key_info("<symm_registration_id>", "<symmetric_Key>");

將函式呼叫取消註解，並將預留位置值 (包括角括號) 取代為您先前複製的裝置註冊識別碼和主要金鑰值。

// Set the symmetric key if using they auth type
prov_dev_set_symmetric_key_info("symm-key-device-007", "your primary key here");

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

在 Visual Studio 功能表中，選取 [偵錯]>[啟動但不偵錯] 以執行解決方案。出現重新建置專案的提示時，選取 [是]，以在執行前重新建置專案。

下列輸出是裝置成功連線到佈建服務執行個體以準備指派給 IoT 中樞的範例：

Provisioning API Version: 1.2.8

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service:
test-docs-hub.azure-devices.net, deviceId: device-007
Press enter key to exit:

範例佈建程式碼會完成下列工作:

使用下列三個參數，向裝置佈建資源驗證您的裝置:
- 裝置佈建服務的識別碼範圍
- 裝置註冊的註冊識別碼。
- 裝置註冊的主要對稱金鑰。
將裝置指派給已連結至裝置佈建服務執行個體的 IoT 中樞。
將測試遙測訊息傳送至 IoT 中樞。

若要使用您的裝置資訊來更新並執行佈建範例:

在裝置佈建服務的主功能表中，選取 [概觀]。
複製 [識別碼範圍] 值。

開啟命令提示字元，並移至所複製 SDK 存放庫中的 SymmetricKeySample:

cd '.\azure-iot-sdk-csharp\provisioning\device\samples\how to guides\SymmetricKeySample\'

在 SymmetricKeySample 資料夾中，於文字編輯器中開啟 Parameters.cs。此檔案會顯示範例的可用參數。在執行範例時，本文只會使用前三個必要參數。檢閱此檔案中的程式碼。不需要任何變更。

參數	必要	描述
`--i` 或 `--IdScope`	True	DPS 執行個體的識別碼範圍
`--r` 或 `--RegistrationId`	True	登錄識別碼 (registration ID) 是一個不區分大小寫的字串 (長度最多為 128 個字元)，該字串可包含英數字元加上特殊字元：`'-'`、`'.'`、`'_'`、`':'`。最後一個字元必須是英數字元或虛線 (`'-'`)。
`--p` 或 `--PrimaryKey`	True	個別註冊的主要金鑰或群組註冊的衍生裝置金鑰。如需如何產生衍生金鑰，請參閱 ComputeDerivedSymmetricKeySample (英文)。
`--g` 或 `--GlobalDeviceEndpoint`	False	裝置要連線到的全域端點。預設為 `global.azure-devices-provisioning.net`
`--t` 或 `--TransportType`	False	要用來與裝置佈建執行個體通訊的傳輸。預設為 `Mqtt`。可能的值包括 `Mqtt`、`Mqtt_WebSocket_Only`、`Mqtt_Tcp_Only`、`Amqp`、`Amqp_WebSocket_Only`、`Amqp_Tcp_only` 和 `Http1`。

在 SymmetricKeySample 資料夾中，用文字編輯器開啟 ProvisioningDeviceClientSample.cs。此檔案會顯示 SecurityProviderSymmetricKey 類別與 ProvisioningDeviceClient 類別如何搭配使用以佈建模擬的對稱金鑰裝置。檢閱此檔案中的程式碼。不需要任何變更。
使用下列命令建置和執行範例程式碼：
- 將 <id-scope> 取代為您在步驟 2 中複製的 [識別碼範圍]。
- 將 <registration-id> 取代為您為裝置註冊提供的 [註冊識別碼]。
- 將 <primarykey> 取代為您從裝置註冊複製的 [主要金鑰]。
```
dotnet run --i <id-scope> --r <registration-id> --p <primarykey>
```

您應該會看到類似下列輸出的內容。系統會將「TestMessage」字串作為測試訊息來傳送給中樞。

D:\azure-iot-sdk-csharp\provisioning\device\samples\how to guides\SymmetricKeySample>dotnet run --i 0ne00000A0A --r symm-key-csharp-device-01 --p sbDDeEzRuEuGKag+kQKV+T1QGakRtHpsERLP0yPjwR93TrpEgEh/Y07CXstfha6dhIPWvdD1nRxK5T0KGKA+nQ==

Initializing the device provisioning client...
Initialized for registration Id symm-key-csharp-device-01.
Registering with the device provisioning service...
Registration status: Assigned.
Device csharp-device-01 registered to ExampleIoTHub.azure-devices.net.
Creating symmetric key authentication for IoT Hub...
Testing the provisioned device with IoT Hub...
Sending a telemetry message...
Finished.
Enter any key to exit.

範例佈建程式碼會依序完成下列工作:

使用下列四個參數，向裝置佈建資源驗證您的裝置:
- PROVISIONING_HOST
- PROVISIONING_IDSCOPE
- PROVISIONING_REGISTRATION_ID
- PROVISIONING_SYMMETRIC_KEY
將裝置指派給已連結至裝置佈建服務執行個體的 IoT 中樞。
將測試遙測訊息傳送至 IoT 中樞。

若要使用您的裝置資訊來更新並執行佈建範例:

在裝置佈建服務的主功能表中，選取 [概觀]。
複製 [識別碼範圍] 和 [全域裝置端點] 值。
開啟用於執行 Node.js 命令的命令提示字元，然後移至下列目錄:
```
cd azure-iot-sdk-node/provisioning/device/samples
```
在佈建/裝置/範例資料夾中，開啟 register_symkey.js 並檢閱程式碼。請注意，範例程式碼會設定自訂承載：
```
provisioningClient.setProvisioningPayload({a: 'b'});
```
您可以將此程式碼註解化，因為本快速入門不會用到。需要有自訂承載，才能使用自訂配置函式將裝置指派給 IoT 中樞。如需詳細資訊，請參閱教學課程：使用自訂配置原則 (部分機器翻譯)。

provisioningClient.register() 方法會嘗試註冊您的裝置。

不需要進一步的變更。
在命令提示字元中，執行下列命令以設定範例所使用的環境變數：
- 將 <provisioning-global-endpoint> 取代為您在步驟 2 複製的 [全域裝置端點]。
- 將 <id-scope> 取代為您在步驟 2 中複製的 [識別碼範圍]。
- 將 <registration-id> 取代為您為裝置註冊提供的 [註冊識別碼]。
- 將 <primarykey> 取代為您從裝置註冊複製的 [主要金鑰]。
```
set PROVISIONING_HOST=<provisioning-global-endpoint>
```
```
set PROVISIONING_IDSCOPE=<id-scope>
```
```
set PROVISIONING_REGISTRATION_ID=<registration-id>
```
```
set PROVISIONING_SYMMETRIC_KEY=<primarykey>
```
使用下列命令建置和執行範例程式碼：
```
 npm install
```
```
node register_symkey.js
```

現在應會看到類似下列輸出的內容。系統會將 "Hello World" 字串當成測試訊息傳送至中樞。

D:\azure-iot-samples-csharp\provisioning\device\samples>node register_symkey.js
registration succeeded
assigned hub=ExampleIoTHub.azure-devices.net
deviceId=nodejs-device-01
payload=undefined
Client connected
send status: MessageEnqueued

範例佈建程式碼會依序完成下列工作:

使用下列四個參數，向裝置佈建資源驗證您的裝置:
- PROVISIONING_HOST
- PROVISIONING_IDSCOPE
- PROVISIONING_REGISTRATION_ID
- PROVISIONING_SYMMETRIC_KEY
將裝置指派給已連結至裝置佈建服務執行個體的 IoT 中樞。
將測試遙測訊息傳送至 IoT 中樞。

若要使用您的裝置資訊來更新並執行佈建範例:

在裝置佈建服務的主功能表中，選取 [概觀]。
複製 [識別碼範圍] 和 [全域裝置端點] 值。
開啟命令提示字元，然後移至範例檔案 provision_symmetric_key.py 所在的目錄。
```
cd azure-iot-sdk-python\samples\async-hub-scenarios
```
在命令提示字元中，執行下列命令以設定範例所使用的環境變數：
- 將 <provisioning-global-endpoint> 取代為您在步驟 2 複製的 [全域裝置端點]。
- 將 <id-scope> 取代為您在步驟 2 中複製的 [識別碼範圍]。
- 將 <registration-id> 取代為您為裝置註冊提供的 [註冊識別碼]。
- 將 <primarykey> 取代為您從裝置註冊複製的 [主要金鑰]。
```
set PROVISIONING_HOST=<provisioning-global-endpoint>
```
```
set PROVISIONING_IDSCOPE=<id-scope>
```
```
set PROVISIONING_REGISTRATION_ID=<registration-id>
```
```
set PROVISIONING_SYMMETRIC_KEY=<primarykey>
```
執行下列命令來安裝 azure-iot-device 程式庫。
```
pip install azure-iot-device
```
在 provision_symmetric_key.py 中執行 Python 範例程式碼。
```
python provision_symmetric_key.py
```

現在應會看到類似下列輸出的內容。部分範例風速遙測訊息也會當成測試傳送給中樞。

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

範例佈建程式碼會依序完成下列工作:

使用下列四個參數，向裝置佈建資源驗證您的裝置:
- GLOBAL_ENDPOINT
- SCOPE_ID
- REGISTRATION_ID
- SYMMETRIC_KEY
將裝置指派給已連結至裝置佈建服務執行個體的 IoT 中樞。
將測試遙測訊息傳送至 IoT 中樞。

若要使用您的裝置資訊來更新並執行佈建範例:

在裝置佈建服務的主功能表中，選取 [概觀]。
複製 [識別碼範圍] 和 [全域裝置端點] 值。這兩個值分別是 SCOPE_ID 和 GLOBAL_ENDPOINT 參數。
開啟 Java 裝置範例程式碼以供編輯。裝置範例程式碼的完整路徑為：

azure-iot-sdk-java/provisioning/provisioning-device-client-samples/provisioning-symmetrickey-individual-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ProvisioningSymmetricKeyIndividualEnrollmentSample.java
為您的 DPS 和裝置註冊設定下列變數的值:
- 將 <id-scope> 取代為您在步驟 2 中複製的 [識別碼範圍]。
- 將 <provisioning-global-endpoint> 取代為您在步驟 2 複製的 [全域裝置端點]。
- 將 <registration-id> 取代為您為裝置註冊提供的 [註冊識別碼]。
- 將 <primarykey> 取代為您從裝置註冊複製的 [主要金鑰]。
```
private static final String SCOPE_ID = "<id-scope>";
private static final String GLOBAL_ENDPOINT = "<provisioning-global-endpoint>";
private static final String SYMMETRIC_KEY = "<primarykey>";
private static final String REGISTRATION_ID = "<registration-id>";
```

開啟命令提示字元以便建置。移至 Java SDK 存放庫的佈建範例專案資料夾。

cd azure-iot-sdk-java\provisioning\provisioning-device-client-samples\provisioning-symmetrickey-individual-sample

建置 (Build) 範例。
```
mvn clean install
```
移至 target 資料夾，並執行已建立的 .jar 檔案。在 java 命令中，將 {version} 預留位置更換為您機器上 .jar 檔案名稱中的版本。
```
cd target
java -jar ./provisioning-symmetrickey-individual-sample-{version}-with-deps.jar
```

現在應會看到類似下列輸出的內容。

Starting...
Beginning setup.
Initialized a ProvisioningDeviceClient instance using SDK version 1.11.0
Starting provisioning thread...
Waiting for Provisioning Service to register
Opening the connection to device provisioning service...
Connection to device provisioning service opened successfully, sending initial device registration message
Authenticating with device provisioning service using symmetric key
Waiting for device provisioning service to provision this device...
Current provisioning status: ASSIGNING
Device provisioning service assigned the device successfully
IotHUb Uri : <Your IoT hub name>.azure-devices.net
Device ID : java-device-007
Sending message from device to IoT Hub...
Press any key to exit...
Message received! Response status: OK_EMPTY