Azure IoT Hub Device Provisioning Service에서 사용자 지정 할당 정책 이해

아티클
03/18/2023

사용자 지정 할당 정책을 사용하면 디바이스를 IoT Hub에 할당하는 방법을 더 자세히 제어할 수 있습니다. 사용자 지정 할당 정책을 사용하면 DPS(Device Provisioning Service)에서 제공하는 기본 제공 정책이 시나리오의 요구 사항을 충족하지 않을 경우 자체 할당 정책을 정의할 수 있습니다.

예를 들어 프로비저닝 중에 디바이스에서 사용하는 인증서를 검사하고 인증서 속성을 기반으로 IoT 허브에 디바이스를 할당할 수 있습니다. 또는 디바이스에 대한 정보가 데이터베이스에 저장되어 있고 데이터베이스를 쿼리하여 디바이스에 할당해야 하는 IoT 허브 또는 디바이스의 초기 트윈을 설정하는 방법을 확인해야 할 수 있습니다.

Azure Functions에서 호스트되는 웹후크에서 사용자 지정 할당 정책을 구현합니다. 그런 다음, 하나 이상의 개별 등록 및 등록 그룹에서 웹후크를 구성할 수 있습니다. 디바이스가 구성된 등록 항목을 통해 등록하는 경우 DPS는 IoT Hub를 반환하는 웹후크를 호출하여 디바이스를 에 등록하고, 필요에 따라 디바이스의 초기 트윈 설정과 디바이스에 직접 반환할 모든 정보를 등록합니다.

개요

다음 단계에서는 사용자 지정 할당 정책이 작동하는 방식을 설명합니다.

사용자 지정 할당 개발자는 의도한 할당 정책을 구현하고 Azure Functions에 HTTP 트리거 함수로 배포하는 웹후크를 개발합니다. 웹후크는 DPS 등록 항목 및 디바이스에 대한 정보를 가져와서 디바이스를 등록해야 하는 IoT 허브를 반환하고, 필요에 따라 디바이스의 초기 상태에 대한 정보를 반환합니다.
IoT 운영자는 사용자 지정 할당을 위해 하나 이상의 개별 등록 및/또는 등록 그룹을 구성하고 Azure Functions에서 사용자 지정 할당 웹후크에 대한 호출 세부 정보를 제공합니다.
사용자 지정 할당 웹후크에 대해 구성된 등록 항목을 통해 디바이스를 등록하면 DPS는 요청 본문이 AllocationRequest 요청 개체로 설정된 상태에서 POST 요청을 웹후크로 보냅니다. AllocationRequest 개체에는 프로비저닝하려는 디바이스 및 프로비저닝하는 개별 등록 또는 등록 그룹에 대한 정보가 포함됩니다. 디바이스 정보에는 등록 요청 시 디바이스에서 보낸 선택적 사용자 지정 페이로드가 포함될 수 있습니다. 자세한 내용은 사용자 지정 할당 정책 요청을 참조하세요.
Azure Function은 성공 시 AllocationResponse 개체를 실행하고 반환합니다. AllocationResponse 개체에는 디바이스를 프로비저닝해야 하는 IoT 허브, 초기 트윈 상태, 디바이스로 돌아갈 선택적 사용자 지정 페이로드가 포함됩니다. 자세한 내용은 사용자 지정 할당 정책 응답을 참조하세요.
DPS는 응답에 표시된 IoT Hub에 디바이스를 할당하고 초기 트윈이 반환되는 경우 그에 따라 디바이스의 초기 트윈을 설정합니다. 사용자 지정 페이로드가 웹후크에서 반환되는 경우 DPS의 등록 응답에서 할당된 IoT Hub 및 인증 세부 정보와 함께 디바이스에 전달됩니다.
디바이스는 할당된 IoT Hub에 연결하고 초기 상태 상태를 다운로드합니다. 사용자 지정 페이로드가 등록 응답에서 반환되는 경우 디바이스는 자체 클라이언트 쪽 논리에 따라 이를 사용합니다.

다음 섹션에서는 사용자 지정 할당 요청 및 응답, 사용자 지정 페이로드 및 정책 구현에 대해 자세히 설명합니다. 사용자 지정 할당 정책의 전체 엔드투엔드 예제는 사용자 지정 할당 정책 사용을 참조하세요.

사용자 지정 할당 정책 요청

DPS는 https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger} 엔드포인트에서 웹후크에 POST 요청을 보냅니다.

요청 본문은 AllocationRequest 개체입니다.

Property name	설명
individualEnrollment	할당 요청이 시작된 개별 등록과 연결된 속성을 포함하는 개별 등록 레코드입니다. 디바이스가 개별 등록을 통해 등록하는 경우 표시합니다.
enrollmentGroup	할당 요청이 시작된 등록 그룹과 연결된 속성을 포함하는 등록 그룹 레코드입니다. 디바이스가 등록 그룹을 통해 등록하는 경우 표시합니다.
deviceRuntimeContext	등록 중인 디바이스와 연결된 속성을 포함하는 개체입니다. 항상 있습니다.
linkedHubs	할당 요청이 시작된 등록 항목에 연결된 IoT Hub의 호스트 이름을 포함하는 배열입니다. 디바이스는 이러한 IoT Hub 중 하나에 할당될 수 있습니다. 항상 있습니다.

DeviceRuntimeContext 개체의 속성은 다음과 같습니다.

속성	Type	설명
registrationId	string	런타임에 디바이스에서 제공하는 등록 ID입니다. 항상 있습니다.
currentIotHubHostName	string	디바이스가 이전에 할당된 IoT Hub의 호스트 이름입니다(있는 경우). 초기 할당인 경우 존재하지 않습니다. 이 속성을 사용하여 디바이스에 대한 초기 할당인지 또는 디바이스가 이전에 할당되었는지 여부를 확인할 수 있습니다.
currentDeviceId	string	디바이스의 이전 할당(있는 경우) 디바이스 ID입니다. 초기 할당인 경우 존재하지 않습니다.
x509	X509DeviceAttestation	X.509 증명의 경우 인증서 세부 정보가 포함됩니다.
symmetricKey	SymmetricKeyAttestation	대칭 키 증명의 경우 기본 및 보조 키 세부 정보가 포함됩니다.
tpm	TpmAttestation	TPM 증명의 경우 인증 키 및 스토리지 루트 키 세부 정보가 포함됩니다.
payload	개체	등록하는 동안 페이로드 속성의 디바이스에서 지정한 속성을 포함합니다. 디바이스가 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 속성에는 디바이스의 등록 ID 및 인증 세부 정보만 포함됩니다. 다음 JSON은 동일한 디바이스를 등록하기 위한 후속 호출에 대한 deviceRuntimeContext를 보여 줍니다. 현재 IoT Hub 호스트 이름 및 디바이스 ID가 요청에 포함되어 있습니다.

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

사용자 지정 할당 정책 응답

성공적인 요청은 AllocationResponse 개체를 반환합니다.

속성	설명
initialTwin	선택 사항. 할당된 IoT Hub의 초기 트윈에서 설정할 원하는 속성 및 태그를 포함하는 개체입니다. DPS는 initialTwin 속성을 사용하여 초기 할당 시 할당된 IoT Hub에서 초기 트윈을 설정하거나 등록 항목의 마이그레이션 정책이 다시 프로비저닝 및 초기 구성으로 설정되는 경우 다시 프로비저닝할 때 설정합니다. 두 경우 모두 initialTwin이 반환되지 않거나 null로 설정된 경우 DPS는 할당된 IoT Hub의 트윈을 등록 항목의 초기 트윈 설정으로 설정합니다. DPS는 등록 항목의 다른 모든 다시 프로비저닝 설정에 대한 initialTwin을 무시합니다. 자세한 내용은 구현 세부 정보를 참조하세요.
iotHubHostName	필수입니다. 디바이스를 할당할 IoT Hub의 호스트 이름입니다. 요청의 linkedHubs 속성에 전달된 IoT Hub 중 하나여야 합니다.
payload	선택 사항. 등록 응답에서 디바이스에 다시 전달할 데이터가 들어 있는 개체입니다. 정확한 데이터는 디바이스와 사용자 지정 할당 함수 간에 개발자가 정의한 암시적 계약에 따라 달라집니다.

다음 JSON은 위의 등록 예제에 대해 사용자 지정 할당 함수가 DPS에 반환한 AllocationResponse 개체를 보여 줍니다.

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

사용자 지정 할당에서 디바이스 페이로드 사용

디바이스는 DPS에 의해 전달되는 사용자 지정 페이로드를 사용자 지정 할당 웹후크로 보낼 수 있으며, 이 페이로드는 해당 논리에서 해당 데이터를 사용할 수 있습니다. 웹후크는 여러 가지 방법으로 이 데이터를 사용하여 디바이스를 할당할 IoT Hub를 결정하거나 초기 트윈에서 속성을 설정하는 데 사용할 수 있는 외부 데이터베이스의 정보를 조회할 수 있습니다. 반대로 웹후크는 디바이스의 클라이언트 쪽 논리에 사용될 수 있는 DPS를 통해 디바이스로 데이터를 다시 반환할 수 있습니다.

예를 들어 디바이스 모델을 기반으로 디바이스를 할당할 수 있습니다. 이 경우 DPS에 등록할 때 요청 페이로드에 해당 모델 정보를 보고하도록 디바이스를 구성할 수 있습니다. DPS는 이 페이로드를 사용자 지정 할당 웹후크에 전달합니다. 그러면 디바이스 모델 정보를 기반으로 디바이스가 프로비저닝될 IoT Hub가 결정됩니다. 필요한 경우 웹후크는 웹후크 응답에서 JSON 개체로 DPS에 데이터를 다시 반환할 수 있으며, 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는 사용자 지정 할당 웹후크에 데이터 페이로드를 보냅니다.

디바이스에 등록 요청 페이로드가 포함된 경우 DPS는 사용자 지정 할당 웹후크를 호출할 때 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 속성도 포함됩니다.

사용자 지정 할당 웹후크가 DPS에 데이터 반환

사용자 지정 할당 정책 웹후크는 웹후크 응답의 AllocationResponse.payload 속성을 사용하여 디바이스용 데이터를 JSON 개체의 DPS에 반환할 수 있습니다.

다음 JSON은 페이로드를 포함하는 웹후크 응답을 보여 줍니다.

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

DPS가 디바이스에 데이터 페이로드를 보냅니다.

DPS가 웹후크 응답에서 페이로드를 수신하는 경우 등록 성공 시 응답의 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"}
   }
}

구현 세부 정보

이전에 DPS(초기 할당)를 통해 등록되지 않은 디바이스 또는 이전에 DPS(다시 프로비저닝)를 통해 등록된 디바이스의 경우 사용자 지정 할당 웹후크를 호출할 수 있습니다. DPS는 데이터 다시 프로비저닝 및 마이그레이션, 다시 프로비저닝하고 초기 구성으로 다시 설정, 다시 프로비저닝 안 함 등의 다시 프로비저닝 정책을 지원합니다. 이러한 정책은 이전에 프로비저닝된 디바이스가 새 IoT Hub에 할당될 때마다 적용됩니다. 자세한 내용은 다시 프로비저닝을 참조하세요.

다음 포인트에서는 사용자 지정 할당 웹후크가 확인해야 하는 요구 사항과 웹후크를 디자인할 때 알아야 할 동작에 대해 설명합니다.

디바이스는 AllocationRequest.linkedHubs 속성의 IoT Hub 중 하나에 할당되어야 합니다. 이 속성에는 디바이스를 할당할 수 있는 호스트 이름별 IoT Hub 목록이 포함됩니다. 일반적으로 등록 항목에 대해 선택된 IoT Hub로 구성됩니다. 등록 항목에서 IoT Hub를 선택하지 않으면 DPS 인스턴스에 연결된 모든 IoT Hub가 포함됩니다. 마지막으로 디바이스가 다시 프로비저닝되고 등록 항목에서 다시 프로비저닝 안 함 정책이 설정된 경우 디바이스가 현재 할당된 IoT 허브만 포함됩니다.
초기 할당 시 웹후크에서 initialTwin 속성을 반환하는 경우 DPS는 그에 따라 할당된 IoT Hub에서 디바이스에 대한 초기 트윈을 설정합니다. initialTwin 속성을 생략하거나 null인 경우 DPS는 디바이스의 초기 트윈을 등록 항목에 지정된 초기 트윈 설정으로 설정합니다.
다시 프로비저닝 시 DPS는 등록 항목에 설정된 다시 프로비저닝 정책을 따릅니다. DPS는 현재 IoT Hub가 변경되고 등록 항목에 설정된 다시 프로비저닝 정책이 다시 프로비저닝하고 초기 구성으로 다시 설정인 경우에만 응답에서 initialTwin 속성을 사용합니다. 이 경우 DPS는 새 IoT Hub의 디바이스에 대한 초기 트윈을 이전 글머리 기호에서 초기 할당 중에 수행했던 방식 그대로 설정합니다. 다른 모든 경우에서 DPS는 initialTwin 속성을 무시합니다.
페이로드 속성이 응답에 설정된 경우 DPS는 요청이 초기 할당 또는 다시 프로비저닝에 대한 것인지에 관계없이 항상 디바이스로 반환합니다.
디바이스가 이전에 IoT Hub에 프로비저닝된 경우 AllocationRequest.deviceRuntimeContext에는 현재 디바이스가 할당된 IoT Hub의 호스트 이름으로 설정되는 currentIotHubHostName 속성이 포함됩니다.
요청에서 AllocationRequest.individualEnrollment 또는 AllocationRequest.enrollmentGroup 속성의 reprovisionPolicy 속성을 검사하여 등록 항목에 현재 설정된 다시 프로비저닝 정책을 확인할 수 있습니다. 다음 JSON은 데이터 다시 프로비저닝 및 마이그레이션 정책에 대한 설정을 보여 줍니다.
```
       "reprovisionPolicy":{
          "updateHubAssignment":true,
          "migrateDeviceData":true
       }
```

SDK 지원

DPS 디바이스 SDK는 C, C#, Java, Node.js API를 제공하여 DPS에 디바이스를 등록하는 데 도움이 됩니다. IoT Hub SDK와 DPS SDK는 모두 사용자 지정 할당 웹후크를 개발할 때 유용할 수 있는 디바이스 트윈과 등록 항목과 같이 디바이스 및 서비스 아티팩트(예: 디바이스 및 서비스 아티팩트)를 나타내는 클래스를 제공합니다. IoT Hub 및 IoT Hub Device Provisioning 서비스에 사용할 수 있는 Azure IoT SDK에 대해 자세히 알아보려면 Azure IoT Hub SDK 및 Azure DPS SDK를 참조하세요.

다음 단계

사용자 지정 할당 정책을 사용하는 엔드투엔드 예는 사용자 지정 할당 정책 사용을 참조하세요.
Azure Functions에 대해 자세히 알아보려면 Azure 함수 설명서를 참조하세요.

다음을 통해 공유