使用Azure IoT 中樞裝置布建服務瞭解自訂配置原則

  • 發行項

自訂配置原則可讓您更充分掌控如何將裝置指派給 IoT 中樞。 藉由使用自訂配置原則，當裝置布建服務提供的內建原則不符合案例的需求時，您可以定義自己的配置原則。

例如，您可能想要檢查裝置在布建期間所使用的憑證，並根據憑證屬性將裝置指派給 IoT 中樞。 或者，您可能有儲存在裝置資料庫中的資訊，而且需要查詢資料庫，以判斷裝置應該指派給哪個 IoT 中樞，或裝置的初始對應項應如何設定。

您可以在裝載于 Azure Functions 的 Webhook 中實作自訂配置原則。 接著，您可以在一或多個個別註冊和註冊群組中設定 Webhook。 當裝置透過設定的註冊專案註冊時，DPS 會呼叫 Webhook，以傳回 IoT 中樞，以便註冊裝置的初始對應項設定，以及直接傳回裝置的任何資訊。

概觀

下列步驟說明自訂配置原則的運作方式：

  1. 自訂配置開發人員會開發 Webhook，以實作預期的配置原則，並將其部署為 Azure Functions 的 HTTP 觸發程式函式。 Webhook 會取得 DPS 註冊專案和裝置的相關資訊，並傳回裝置應該註冊的 IoT 中樞，並選擇性地傳回裝置初始狀態的相關資訊。

  2. IoT 操作員會針對自訂配置設定一或多個個別註冊和/或註冊群組，並提供 Azure Functions 中自訂配置 Webhook 的呼叫詳細資料。

  3. 當裝置 透過針對自訂配置 Webhook 設定的註冊專案註冊 時，DPS 會將 POST 要求傳送至 Webhook，並將要求本文設定為 AllocationRequest 要求物件。 AllocationRequest 物件包含嘗試布建的裝置相關資訊，以及其布建的個別註冊或註冊群組。 裝置資訊可以在其註冊要求中包含從裝置傳送的選擇性自訂承載。 如需詳細資訊，請參閱 自訂配置原則要求 。

  4. Azure 函式會在成功時執行並傳回 AllocationResponse 物件。 AllocationResponse 物件包含應該布建裝置的 IoT 中樞、初始對應項狀態，以及要返回裝置的選擇性自訂承載。 如需詳細資訊，請參閱 自訂配置原則回應 。

  5. DPS 會將裝置指派給回應中指示的 IoT 中樞，如果傳回初始對應項，請據以設定裝置的初始對應項。 如果 Webhook 傳回自訂承載，則會連同來自 DPS 的 註冊回應 中指派的 IoT 中樞和驗證詳細資料一起傳遞至裝置。

  6. 裝置會連線到指派的 IoT 中樞，並下載其初始對應項狀態。 如果在註冊回應中傳回自訂承載，裝置會根據自己的用戶端邏輯使用它。

下列各節提供自訂配置要求和回應、自訂承載和原則實作的詳細資料。 如需自訂配置原則的完整端對端範例，請參閱 使用自訂配置原則 。

自訂配置原則要求

DPS 會在下列端點上將 POST 要求傳送至您的 Webhook： https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

要求本文是 AllocationRequest 物件：

屬性名稱 描述
individualEnrollment 個別 註冊記錄 ，其中包含與配置要求源自之個別註冊相關聯的屬性。 如果裝置正在透過個別註冊進行註冊，則為存在。
enrollmentGroup 註冊群組記錄 ，其中包含與配置要求源自之註冊群組相關聯的屬性。 如果裝置是透過註冊群組進行註冊，則為存在。
deviceRuntimeCoNtext 物件，包含與註冊裝置相關聯的屬性。 一律存在。
linkedHubs 陣列，其中包含 IoT 中樞的主機名稱，這些主機名稱會連結到配置要求的來源註冊專案。 裝置可指派給其中任何一個 IoT 中樞。 一律存在。

DeviceRuntimeCoNtext 物件具有下列屬性：

屬性 類型​ 描述
registrationId string 裝置在執行時間提供的註冊識別碼。 一律存在。
currentIotHubHostName string 裝置先前指派給 IoT 中樞的主機名稱（如果有的話）。 如果這是初始指派，則不存在。 您可以使用這個屬性來判斷這是裝置的初始指派，還是先前是否已指派裝置。
currentDeviceId string 來自裝置先前指派的裝置識別碼（如果有的話）。 如果這是初始指派，則不存在。
x509 X509DeviceAttestation 針對 X.509 證明，包含憑證詳細資料。
symmetricKey SymmetricKeyAttestation 針對對稱金鑰證明，包含主要和次要金鑰詳細資料。
Tpm TpmAttestation 針對 TPM 證明，包含簽署金鑰和儲存體根金鑰詳細資料。
承載 object 在註冊期間，包含裝置在承載屬性中指定的屬性。 如果裝置在 DPS 註冊要求中傳送自訂承載，則為存在。

下列 JSON 顯示 DPS 針對透過對稱金鑰型註冊群組註冊的裝置所傳送的 AllocationRequest 物件。

{
   "enrollmentGroup":{
      "enrollmentGroupId":"contoso-custom-allocated-devices",
      "attestation":{
         "type":"symmetricKey"
      },
      "capabilities":{
         "iotEdge":false
      },
      "etag":"\"13003fea-0000-0300-0000-62d1d5e50000\"",
      "provisioningStatus":"enabled",
      "reprovisionPolicy":{
         "updateHubAssignment":true,
         "migrateDeviceData":true
      },
      "createdDateTimeUtc":"2022-07-05T21:27:16.8123235Z",
      "lastUpdatedDateTimeUtc":"2022-07-15T21:02:29.5922255Z",
      "allocationPolicy":"custom",
      "iotHubs":[
         "custom-allocation-toasters-hub.azure-devices.net",
         "custom-allocation-heatpumps-hub.azure-devices.net"
      ],
      "customAllocationDefinition":{
         "webhookUrl":"https://custom-allocation-function-app-3.azurewebsites.net/api/HttpTrigger1?****",
         "apiVersion":"2021-10-01"
      }
   },
   "deviceRuntimeContext":{
      "registrationId":"breakroom499-contoso-tstrsd-007",
      "symmetricKey":{
         
      }
   },
   "linkedHubs":[
      "custom-allocation-toasters-hub.azure-devices.net",
      "custom-allocation-heatpumps-hub.azure-devices.net"
   ]
}

因為這是裝置的初始註冊， 因此 deviceRuntimeCoNtext 屬性只包含裝置的註冊識別碼和驗證詳細資料。 下列 JSON 會顯示 deviceRuntimeCoNtext ，以供後續呼叫註冊相同的裝置。 請注意，要求中包含目前的IoT 中樞主機名稱和裝置識別碼。

{
   "deviceRuntimeContext":{
      "registrationId":"breakroom499-contoso-tstrsd-007",
      "currentIotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
      "currentDeviceId":"breakroom499-contoso-tstrsd-007",
      "symmetricKey":{
         
      }
   },
}

自訂配置原則回應

成功的要求會 傳回 AllocationResponse 物件。

屬性 說明
initialTwin 選擇性。 物件，包含所指派 IoT 中樞上初始對應項中設定所需的屬性和標籤。 DPS 會使用 initialTwin 屬性，在初始指派的 IoT 中樞上設定初始對應項，或在註冊專案的移轉原則設定為 [重新布建] 並重設為初始設定 時重新布建時。在這兩種情況下，如果未傳回 initialTwin 或設定為 null，DPS 會將指派 IoT 中樞上的對應項設定設為註冊專案中的初始對應項設定。 DPS 會忽略註冊專案中所有其他重新布建設定的 initialTwin。 若要深入瞭解，請參閱 實作詳細資料 。
iotHubHostName 必要。 要指派裝置的 IoT 中樞主機名稱。 這必須是要求中 linkedHubs 屬性中傳遞的 其中一個 IoT 中樞。
承載 選擇性。 物件，其中包含要傳回註冊回應中裝置的資料。 確切的資料將取決於裝置與自訂配置函式之間開發人員所定義的隱含合約。

下列 JSON 顯示 針對上述範例註冊，自訂配置函式傳回給 DPS 的 AllocationResponse 物件。

{
   "iotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
   "initialTwin":{
      "properties":{
         "desired":{
            "state":"ready",
            "darknessSetting":"medium"
         }
      },
      "tags":{
         "deviceType":"toaster"
      }
   }
}

在自訂配置中使用裝置承載

裝置可以將 DPS 傳遞的自訂承載傳送至您的自訂配置 Webhook，然後就可以在其邏輯中使用該資料。 Webhook 可能會以數種方式使用此資料，或許可以判斷要將裝置指派給哪個 IoT 中樞，或查閱外部資料庫中可能用來設定初始對應項屬性的資訊。 相反地，您的 Webhook 可以透過 DPS 將資料傳回裝置，這可用於裝置的用戶端邏輯中。

例如，您可能想要根據裝置型號配置裝置。 在此情況下，您可以在向 DPS 註冊時，將裝置設定為在要求承載中報告其模型資訊。 DPS 會將此承載傳遞至自訂配置 Webhook，這會根據裝置型號資訊來決定將裝置布建至哪個 IoT 中樞。 如有需要，Webhook 可以將資料傳回 DPS 做為 Webhook 回應中的 JSON 物件，DPS 會在註冊回應中將此資料傳回您的裝置。

裝置會將資料承載傳送至 DPS

裝置會 呼叫註冊 API 以向 DPS 註冊。 您可以使用選擇性 承載 屬性來增強要求。 這個屬性可以包含任何有效的 JSON 物件。 確切的內容將取決於您解決方案的需求。

若要使用 TPM 進行證明，要求本文看起來如下：

{ 
    "registrationId": "mydevice", 
    "tpm": { 
        "endorsementKey": "xxxx-device-endorsement-key-xxxxx", 
        "storageRootKey": "xxxx-device-storage-root-key-xxxxx" 
    }, 
    "payload": { "property1": "value1", "property2": {"propertyA":"valueA", "property2-2":1234}, .. } 
}

DPS 會將資料承載傳送至自訂配置 Webhook

如果裝置包含其註冊要求的承載，DPS 會在呼叫自訂配置 Webhook 時，在 AllocationRequest.deviceRuntimeCoNtext.payload 屬性中 傳遞承載 。

針對上一節中的 TPM 註冊要求，裝置執行時間內容看起來會如下所示：

{ 
    "registrationId": "mydevice", 
    "tpm": { 
        "endorsementKey": "xxxx-device-endorsement-key-xxxxx", 
        "storageRootKey": "xxxx-device-storage-root-key-xxxxx" 
    }, 
    "payload": { "property1": "value1", "property2": {"propertyA":"valueA", "property2-2":1234}, .. } 
}

如果這不是裝置的初始註冊，則執行時間內容也會包含 currentIoTHubHostname 和 currentDeviceId 屬性。

自訂配置 Webhook 會將資料傳回 DPS

自訂配置原則 Webhook 可以使用 Webhook 回應中的 AllocationResponse.payload 屬性，將適用于裝置的資料傳回 JSON 物件 中的 DPS。

下列 JSON 顯示包含承載的 Webhook 回應：

{
   "iotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
   "initialTwin":{
      "properties":{
         "desired":{
            "state":"ready",
            "darknessSetting":"medium"
         }
      },
      "tags":{
         "deviceType":"toaster"
      }
   },
   "payload": { "property1": "value1" } 
}

DPS 會將資料承載傳送至裝置

如果 DPS 在 Webhook 回應中收到承載，則會在成功註冊的回應中 ，將此資料傳回 RegistrationOperationStatus.registrationState.payload 屬性中的裝置。 registrationState 屬性的類型 為 DeviceRegistrationResult 。

下列 JSON 顯示包含承載 屬性之 TPM 裝置 的成功註冊回應：

{
   "operationId":"5.316aac5bdc130deb.b1e02da8-xxxx-xxxx-xxxx-7ea7a6b7f550",
   "status":"assigned",
   "registrationState":{
      "assignedHub":"myIotHub",
      "createdDateTimeUtc" : "2022-08-01T22:57:47Z",
      "deviceId" : "myDeviceId",
      "etag" : "xxxx-etag-value-xxxxx",
      "lastUpdatedDateTimeUtc" : "2022-08-01T22:57:47Z",
      "payload": { "property1": "value1" },
      "registrationId": "mydevice", 
      "status": assigned,
      "substatus": initialAssignment,
      "tpm": {"authenticationKey": "xxxx-encrypted-authentication-key-xxxxx"}
   }
}

實作詳細資料

自訂配置 Webhook 可以針對先前尚未透過 DPS 註冊的裝置（初始指派）或先前透過 DPS 註冊的裝置（重新布建）。 DPS 支援下列重新布建原則： 重新布建和移轉資料 、 重新布建和重設為初始設定 ，以及 永不重新布建 。 每當先前布建的裝置指派給新的 IoT 中樞時，就會套用這些原則。 如需詳細資訊，請參閱 重新布建 。

下列幾點說明自訂配置 Webhook 在設計 Webhook 時必須注意的需求和行為：

  • 裝置應該指派給 AllocationRequest.linkedHubs 屬性中的其中一個 IoT 中 樞。 此屬性包含可由裝置指派給的主機名稱的 IoT 中樞清單。 這通常是由針對註冊專案選取的 IoT 中樞所組成。 如果未在註冊專案中選取 IoT 中樞，則會包含連結至 DPS 實例的所有 IoT 中樞。 最後，如果裝置正在重新布建，且 註冊專案上已設定永不重新 布建原則，則它只會包含裝置目前指派的 IoT 中樞。

  • 在初始指派時 ，如果 webhook 傳回 initialTwin 屬性，DPS 會據以在指派的 IoT 中樞上設定裝置的初始對應項。 如果省略 initialTwin 屬性或為 Null，DPS 會將裝置的初始對應項設定設定為註冊專案中指定的初始對應項設定。

  • 在重新布建時，DPS 會遵循註冊專案中設定的重新布建原則。 如果目前的 IoT 中樞已變更，且註冊專案上設定的重新布建原則是 重新布建，並重設為初始設定 ，DPS 只會在 回應中使用 initialTwin 屬性。在此情況下，DPS 會設定新 IoT 中樞上裝置的初始對應項，就像在上一個專案符號的初始指派期間一樣。 在其他所有情況下，DPS 會 忽略 initialTwin 屬性。

  • 如果在回應中設定承載 屬性，不論要求是初始指派還是重新布建，DPS 都會一律將它傳回裝置。

  • 如果裝置先前已布建至 IoT 中 樞，AllocationRequest.deviceRuntimeCoNtext 將包含 currentIotHubHostName 屬性，此屬性將會設定為目前指派裝置的 IoT 中樞主機名稱。

  • 您可以檢查 Request 中 AllocationRequest.individualEnrollment 或 AllocationRequest.enrollmentGroup 屬性的 reprovisionPolicy 屬性 ，以判斷註冊專案上目前設定了哪一個重新布建原則。 下列 JSON 顯示重新布建和移轉資料 原則的 設定：

           "reprovisionPolicy":{
          "updateHubAssignment":true,
          "migrateDeviceData":true
       }

SDK 支援

DPS 裝置 SDK 會在 C、C#、JAVA 和 Node.js 中提供 API，以協助您向 DPS 註冊裝置。 IoT 中樞 SDK 和 DPS SDK 都提供類別，這些類別代表裝置和服務成品，例如裝置對應項和服務成品，以及開發自訂配置 Webhook 時可能會有説明的註冊專案。 若要深入瞭解適用于IoT 中樞和IoT 中樞裝置布建服務的 Azure IoT SDK，請參閱 Azure IoT 中樞 SDK 和 Azure DPS SDK 。

下一步