Descripción de las directivas de asignación personalizadas con Azure IoT Hub Device Provisioning Service

Artículo
03/18/2023

Las directivas de asignación personalizadas ofrece más control sobre la forma en que se asignan los dispositivos a los centro de IoT. Al usar directivas de asignación personalizadas, puede definir sus propias directivas de asignación cuando las directivas integradas de Device Provisioning Service (DPS) no cumplan los requisitos de su escenario.

Por ejemplo, quizás le interese examinar el certificado que usa un dispositivo durante el aprovisionamiento y asignar el dispositivo a un centro de IoT según una propiedad del certificado. También, es posible que tenga la información almacenada en una base de datos para los dispositivos y necesite consultarla para determinar a qué centro de IoT se debe asignar el dispositivo o cómo debe establecerse el gemelo inicial del dispositivo.

Implementa una directiva de asignación personalizada en un webhook hospedado en Azure Functions. Después, puede configurar el webhook en una o varias inscripciones individuales y grupos de inscripción. Cuando un dispositivo se registra a través de una entrada de inscripción configurada, DPS llama al webhook que devuelve el centro de IoT en el que registrar el dispositivo y, opcionalmente, la configuración del gemelo inicial para el dispositivo y cualquier información que se va a devolver directamente al dispositivo.

Información general

En los pasos siguientes se describe cómo funcionan las directivas de asignación personalizadas:

Un desarrollador de asignación personalizada desarrolla un webhook que implementa la directiva de asignación prevista y lo implementa como una función de desencadenador HTTP para Azure Functions. El webhook toma información sobre la entrada de inscripción de DPS y el dispositivo y devuelve el centro de IoT en el que se debe registrar el dispositivo y, opcionalmente, información sobre el estado inicial del dispositivo.
Un operador de IoT configura una o varias inscripciones individuales o grupos de inscripción para la asignación personalizada y proporciona detalles de llamada para el webhook de asignación personalizada en Azure Functions.
Cuando un dispositivo se registra a través de una entrada de inscripción configurada para el webhook de asignación personalizada, DPS envía una solicitud POST al webhook con el cuerpo de la solicitud establecido en un objeto de solicitud AllocationRequest. El objeto AllocationRequest contiene información sobre el dispositivo que intenta aprovisionar y la inscripción individual o el grupo de inscripción mediante el que se aprovisiona. La información del dispositivo puede incluir una carga personalizada opcional enviada desde el dispositivo en su solicitud de registro. Para más información, consulte Solicitud de directiva de asignación personalizada.
La función de Azure ejecuta y devuelve un objeto AllocationResponse si se ejecuta correctamente. El objeto AllocationResponse contiene el centro de IoT en el que se debe aprovisionar el dispositivo, el estado del gemelo inicial y una carga personalizada opcional para volver al dispositivo. Para más información, consulte Respuesta de directiva de asignación personalizada.
DPS asigna el dispositivo al centro de IoT indicado en la respuesta y, si se devuelve un gemelo inicial, establece el gemelo inicial para el dispositivo en consecuencia. Si el webhook devuelve una carga personalizada, se pasa al dispositivo junto con el centro de IoT asignado y los detalles de autenticación en la respuesta de registro de DPS.
El dispositivo se conecta al centro de IoT asignado y descarga su estado de gemelo inicial. Si se devuelve una carga personalizada en la respuesta de registro, el dispositivo lo usa según su propia lógica del lado cliente.

En las secciones siguientes se proporcionan más detalles sobre la solicitud y la respuesta de asignación personalizada, las cargas personalizadas y la implementación de directivas. Para obtener un ejemplo completo de una directiva de asignación personalizada, consulte Uso de directivas de asignación personalizadas.

Solicitud de directiva de asignación personalizada

DPS envía una solicitud POST al webhook en el siguiente punto de conexión: https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

El cuerpo de la solicitud es un objeto AllocationRequest:

Nombre de propiedad	Descripción
individualEnrollment	Un registro de inscripción individual que contiene propiedades asociadas a la inscripción individual de la que se originó la solicitud de asignación. Presente si el dispositivo se registra a través de una inscripción individual.
enrollmentGroup	Un registro de grupo de inscripción que contiene las propiedades asociadas al grupo de inscripción del que procede la solicitud de asignación. Presente si el dispositivo se registra a través de un grupo de inscripción.
deviceRuntimeContext	Objeto que contiene propiedades asociadas al dispositivo que se está registrando. Siempre presente.
linkedHubs	Matriz que contiene los nombres de host de los centros de IoT que están vinculados a la entrada de inscripción de la que procede la solicitud de asignación. El dispositivo se puede asignar a cualquiera de estos centros de IoT. Siempre presente.

El objeto DeviceRuntimeContext tiene estas propiedades:

Propiedad	Type	Descripción
registrationId	cadena	Identificador de registro proporcionado por el dispositivo en el entorno de ejecución. Siempre presente.
currentIotHubHostName	cadena	Nombre de host del centro de IoT al que se asignó anteriormente el dispositivo (si existe). No está presente si se trata de una asignación inicial. Puede usar esta propiedad para determinar si se trata de una asignación inicial para el dispositivo o si el dispositivo se ha asignado previamente.
currentDeviceId	cadena	Identificador de dispositivo de la asignación anterior del dispositivo (si existe). No está presente si se trata de una asignación inicial.
x509	X509DeviceAttestation	Para la atestación X.509, contiene los detalles del certificado.
symmetricKey	SymmetricKeyAttestation	Para la atestación de clave simétrica, contiene los detalles de clave principal y secundaria.
tpm	TpmAttestation	Para la atestación de TPM, contiene la clave de aprobación y los detalles de la clave raíz de almacenamiento.
payload	object	Contiene las propiedades especificadas por el dispositivo en la propiedad de carga durante el registro. Presente si el dispositivo envía una carga personalizada en la solicitud de registro de DPS.

El siguiente JSON muestra el objeto AllocationRequest enviado por DPS para un dispositivo que se registra a través de un grupo de inscripción basado en claves simétricas.

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

Dado que este es el registro inicial del dispositivo, la propiedad deviceRuntimeContext solo contiene el identificador de registro y los detalles de autenticación del dispositivo. El siguiente JSON muestra el valor deviceRuntimeContext para una llamada posterior para registrar el mismo dispositivo. Tenga en cuenta que el nombre de host y el identificador de dispositivo actuales de IoT Hub se incluyen en la solicitud.

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

Respuesta de directiva de asignación personalizada

Una solicitud correcta devuelve un objeto AllocationResponse.

Propiedad	Descripción
initialTwin	Opcional. Objeto que contiene las propiedades y etiquetas deseadas que se van a establecer en el gemelo inicial en el centro de IoT asignado. DPS usa la propiedad initialTwin para establecer el gemelo inicial en el centro de IoT asignado en la asignación inicial o al volver a aprovisionar si la directiva de migración de la entrada de inscripción está establecida en Volver a aprovisionar y restablecer la configuración inicial. En ambos casos, si no se devuelve initialTwin o se establece en NULL, DPS establece el gemelo en el centro de IoT asignado a la configuración inicial del gemelo en la entrada de inscripción. DPS omite la inicialTwin para todas las demás opciones de reaprovisionamiento en la entrada de inscripción. Para más información, consulte Detalles de implementación.
iotHubHostName	Necesario. Nombre de host del centro de IoT al que se va a asignar el dispositivo. Debe ser uno de los centros de IoT pasados en la propiedad linkedHubs de la solicitud.
payload	Opcional. Objeto que contiene los datos que se van a devolver al dispositivo en la respuesta de registro. Los datos exactos dependerán del contrato implícito definido por el desarrollador entre el dispositivo y la función de asignación personalizada.

El siguiente JSON muestra el objeto AllocationResponse devuelto por una función de asignación personalizada a DPS para el registro de ejemplo anterior.

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

Uso de cargas de dispositivo en la asignación personalizada

Los dispositivos pueden enviar una carga personalizada que DPS pasa a su webhook de asignación personalizada, que luego puede usar esos datos en su lógica. El webhook puede usar estos datos de varias maneras, quizás para determinar a qué centro de IoT asignar el dispositivo o para buscar información en una base de datos externa que se pueda usar para establecer propiedades en el gemelo inicial. A la inversa, el webhook puede devolver datos al dispositivo a través de DPS, que se pueden usar en la lógica del lado cliente del dispositivo.

Por ejemplo, puede querer asignar los dispositivos en función del modelo de dispositivo. En este caso, puede configurar el dispositivo para que comunique la información de su modelo en la carga de la solicitud cuando se registre con DPS. DPS pasará esta carga al webhook de asignación personalizada, que determinará en qué centro de IoT se aprovisionará el dispositivo en función de la información del modelo del dispositivo. Si es necesario, el webhook puede devolver datos a DPS como un objeto JSON en la respuesta del webhook, y DPS devolverá estos datos al dispositivo en la respuesta de registro.

El dispositivo envía la carga útil de datos a DPS

Un dispositivo llama a la API de registro para registrarse en DPS. La solicitud se puede mejorar con la propiedad payload opcional. Esta propiedad puede contener cualquier objeto JSON válido. El contenido exacto dependerá de los requisitos de la solución.

Para la atestación con TPM, el cuerpo de la solicitud tiene el siguiente aspecto:

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

Envío de la carga de datos al webhook de asignación personalizada por DPS

Si un dispositivo incluye una carga en su solicitud de registro, DPS pasa la carga en la propiedad AllocationRequest.deviceRuntimeContext.payload cuando llama al webhook de asignación personalizada.

Para la solicitud de registro de TPM en la sección anterior, el contexto del entorno de ejecución del dispositivo tendrá un aspecto similar al siguiente:

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

Si no es el registro inicial del dispositivo, el contexto del entorno de ejecución también incluirá las propiedades currentIoTHubHostname y currentDeviceId.

Devolución de datos a DPS por el webhook de asignación personalizada

El webhook de la directiva de asignación personalizada puede devolver datos destinados a un dispositivo a DPS en un objeto JSON mediante la propiedad AllocationResponse.payload en la respuesta del webhook.

El siguiente JSON muestra una respuesta de webhook que incluye una carga:

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

Envío de la carga de datos al dispositivo por DPS

Si DPS recibe una carga en la respuesta de webhook, devuelve estos datos al dispositivo en la propiedad RegistrationOperationStatus.registrationState.payload de la respuesta en un registro correcto. La propiedad registrationState es del tipo DeviceRegistrationResult.

El siguiente JSON muestra una respuesta de registro correcta para un dispositivo TPM que incluye la propiedad de carga:

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

Detalles de la implementación

Se puede llamar al webhook de asignación personalizada para un dispositivo que no se ha registrado previamente a través de DPS (asignación inicial) o para un dispositivo que se ha registrado previamente a través de DPS (reaprovisionamiento). DPS admite las siguientes directivas de reaprovisionamiento: Volver a aprovisionar y migrar datos, Volver a aprovisionar y restablecer la configuración inicial y Nunca volver a aprovisionar. Estas directivas se aplican cada vez que se asigna un dispositivo aprovisionado previamente a un nuevo centro de IoT. Para más información, consulte Reaprovisionamiento.

En los puntos siguientes se describen los requisitos que el webhook de asignación personalizada debe observar y el comportamiento que debe tener en cuenta al diseñar el webhook:

El dispositivo debe asignarse a uno de los centros de IoT en la propiedad AllocationRequest.linkedHubs. Esta propiedad contiene la lista de centros de IoT por nombre de host a los que se puede asignar el dispositivo. Normalmente se compone de los centros de IoT seleccionados para la entrada de inscripción. Si no se selecciona ningún centro de IoT en la entrada de inscripción, contendrá todos los centros de IoT vinculados a la instancia de DPS. Por último, si el dispositivo se vuelve a aprovisionar y la directiva Never reprovision está establecida en la entrada de inscripción, solo contendrá el centro de IoT al que está asignado actualmente el dispositivo.
En la asignación inicial, si el webhook devuelve la propiedad initialTwin, DPS establecerá el gemelo inicial para el dispositivo en el centro de IoT asignado en consecuencia. Si se omite la propiedad initialTwin o es NULL, DPS establece el gemelo inicial para el dispositivo en la configuración del gemelo inicial especificada en la entrada de inscripción.
Al volver a aprovisionar, DPS sigue la directiva de reaprovisionamiento establecida en la entrada de inscripción. DPS solo usa la propiedad initialTwin en la respuesta si se cambia el centro de IoT actual y la directiva de reaprovisionamiento establecida en la entrada de inscripción es Volver a aprovisionar y restablecer la configuración inicial. En este caso, DPS establece el gemelo inicial para el dispositivo en el nuevo centro de IoT exactamente como lo haría durante la asignación inicial en la viñeta anterior. En todos los demás casos, DPS omite la propiedad initialTwin.
Si la propiedad payload se establece en la respuesta, DPS siempre la devolverá al dispositivo independientemente de si la solicitud es para la asignación inicial o el reaprovisionamiento.
Si un dispositivo se ha aprovisionado anteriormente en un centro de IoT, AllocationRequest.deviceRuntimeContext contendrá una propiedad currentIotHubHostName, que se establecerá en el nombre de host del centro de IoT donde está asignado actualmente el dispositivo.
Puede determinar cuál de las directivas de reaprovisionamiento está establecida actualmente en la entrada de inscripción examinando la propiedad reprovisionPolicy de AllocationRequest.individualEnrollment o la propiedad AllocationRequest.enrollmentGroup en la solicitud. el siguiente JSON muestra la configuración de la directiva de reaprovisionamiento y migración de datos :
```
       "reprovisionPolicy":{
          "updateHubAssignment":true,
          "migrateDeviceData":true
       }
```

Soporte técnico de SDK

Los SDK de dispositivo de DPS proporcionan API en C, C#, Java y Node.js para ayudarle a registrar dispositivos con DPS. Tanto los SDK de IoT Hub como los SDK de DPS proporcionan clases que representan artefactos de dispositivo y servicio, como dispositivos gemelos y entradas de inscripción que pueden resultar útiles al desarrollar webhooks de asignación personalizada. Para obtener más información sobre los SDK de Azure IoT disponibles para IoT Hub y el servicio IoT Hub Device Provisioning, consulte SDK de Azure IoT Hub y SDK de DPS de Azure.

Pasos siguientes

Para obtener un ejemplo completo de una directiva de asignación personalizada, consulte Uso de directivas de asignación personalizadas.
Para obtener más información sobre Azure Functions, vea la documentación de Azure Functions.