瞭解搭配 Azure IoT 中樞裝置佈建服務的自訂配置原則

發行項
06/13/2024

自訂配置原則可讓您進一步掌控將裝置指派給 IoT 中樞的方式。使用自訂配置原則，您可在裝置佈建服務 (DPS) 所提供的內建原則不符合案例的需求時，定義您自己的配置原則。

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

您可以在裝載於 Azure Functions 的 Webhook 中實作自訂配置原則。接著，您可以在一或多個個別註冊和註冊群組中設定 Webhook。當裝置透過設定的註冊項目登錄時，DPS 會呼叫 Webhook，此 Webhook 會傳回裝置要登錄的 IoT 中樞，且可選擇性傳回裝置的初始對應項設定，還有能直接傳回裝置的任何資訊。

概觀

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

自訂配置開發人員會開發實作預期配置原則的 Webhook，並將其部署到 Azure Functions 作為 HTTP 觸發程序函數。 Webhook 會取得 DPS 註冊項目和裝置的相關資訊，並傳回裝置應登錄的 IoT 中樞，以及選擇性傳回裝置初始狀態的相關資訊。
IoT 操作員會針對自訂配置設定一或多個個別註冊和/或註冊群組，並提供 Azure Functions 中自訂配置 Webhook 的呼叫詳細資料。
當裝置透過針對自訂配置 Webhook 設定的註冊項目登錄時，DPS 會將 POST 要求傳送至 Webhook，並將要求本文設定為 AllocationRequest 要求物件。 AllocationRequest 物件包含嘗試佈建的裝置相關資訊，以及要透過哪個個別註冊或註冊群組進行佈建。裝置資訊可包含從裝置在其註冊要求中傳送的選擇性自訂承載。如需詳細資訊，請參閱自訂配置原則要求。
Azure Function 會執行並在成功時傳回 AllocationResponse 物件。 AllocationResponse 物件包含應佈建裝置的 IoT 中樞、初始對應項狀態，以及要傳回裝置的選擇性自訂承載。如需詳細資訊，請參閱自訂配置原則回應。
DPS 會將裝置指派給回應中指定的 IoT 中樞，如果有傳回初始對應項，便會據以設定裝置的初始對應項。如果 Webhook 有傳回自訂承載，則會連同來自 DPS 的註冊回應中指派的 IoT 中樞和驗證詳細資料一起傳遞至裝置。
裝置會連線到指派的 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 或未將 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 能以其邏輯使用該資料。 Webhook 可以透過多種方式使用此資料，也許是判斷要將裝置指派給哪個 IoT 中樞，或查閱外部資料庫中可能用來設定初始對應項屬性的資訊。相反地，Webhook 可以透過 DPS 將資料傳回裝置，然後以裝置的用戶端邏輯使用。

例如，您可能需要根據裝置型號來配置裝置。在此情況下，您可以在透過 DPS 登錄時，將裝置設定為在要求承載中報告其型號資訊。 DPS 會將此承載傳遞至自訂配置 Webhook，進而根據裝置型號資訊來判斷要將裝置佈建至哪個 IoT 中樞。如有需要，Webhook 可以將資料作為 Webhook 回應中的 JSON 物件傳回 DPS，而 DPS 會將此資料透過登錄回應傳回給裝置。

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

裝置會呼叫登錄 API 以透過 DPS 登錄。您可以選擇性使用 payload 屬性來增強要求。這個屬性可以包含任何有效的 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 裝置的成功登錄回應，其中包含 payload 屬性：

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

實作詳細資料

您可以針對先前未透過 DPS 登錄的裝置 (初始指派)，或是先前已透過 DPS 登錄的裝置 (重新佈建) 呼叫自訂配置 Webhook。 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 屬性。
如果回應中有設定 payload 屬性，不論要求是要進行初始指派還是重新佈建，DPS 一律都會傳回給裝置。
如果裝置先前已佈建至 IoT 中樞，AllocationRequest.deviceRuntimeContext 會包含 currentIotHubHostName 屬性，這會設定為目前受指派裝置的 IoT 中樞主機名稱。
您可以檢查要求中 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。

下一步

如需使用自訂配置原則的端對端範例，請參閱使用自訂配置原則
若要深入瞭解 Azure Functions，請參閱 Azure Functions 文件

共用方式為