Condividi tramite

Informazioni sui criteri di allocazione personalizzati con hub IoT di Azure servizio Device Provisioning

  • Articolo

I criteri di allocazione personalizzati offrono un maggiore controllo sulla modalità di assegnazione dei dispositivi agli hub IoT. Usando criteri di allocazione personalizzati, è possibile definire criteri di allocazione personalizzati quando i criteri predefiniti forniti dal servizio Device Provisioning (DPS) non soddisfano i requisiti dello scenario.

Si potrebbe ad esempio scegliere di esaminare il certificato in uso su un dispositivo durante il provisioning e assegnare il dispositivo a un hub IoT in base a una proprietà del certificato. In alternativa, si dispone di informazioni archiviate in un database per i dispositivi ed è necessario eseguire query sul database per determinare l'hub IoT a cui deve essere assegnato un dispositivo o come deve essere impostato il dispositivo gemello iniziale del dispositivo.

Si implementano criteri di allocazione personalizzati in un webhook ospitato in Funzioni di Azure. È quindi possibile configurare il webhook in una o più registrazioni e gruppi di registrazione singoli. Quando un dispositivo viene registrato tramite una voce di registrazione configurata, dps chiama il webhook che restituisce l'hub IoT per registrare il dispositivo in e, facoltativamente, le impostazioni iniziali del dispositivo gemello per il dispositivo e le informazioni da restituire direttamente al dispositivo.

Panoramica

I passaggi seguenti descrivono il funzionamento dei criteri di allocazione personalizzati:

  1. Uno sviluppatore di allocazione personalizzato sviluppa un webhook che implementa i criteri di allocazione previsti e lo distribuisce come funzione trigger HTTP per Funzioni di Azure. Il webhook acquisisce informazioni sulla voce di registrazione dps e sul dispositivo e restituisce l'hub IoT a cui il dispositivo deve essere registrato e, facoltativamente, informazioni sullo stato iniziale del dispositivo.

  2. Un operatore IoT configura una o più registrazioni singole e/o gruppi di registrazione per l'allocazione personalizzata e fornisce i dettagli delle chiamate per il webhook di allocazione personalizzato in Funzioni di Azure.

  3. Quando un dispositivo viene registrato tramite una voce di registrazione configurata per il webhook di allocazione personalizzata, DPS invia una richiesta POST al webhook con il corpo della richiesta impostato su un oggetto richiesta AllocationRequest . L'oggetto AllocationRequest contiene informazioni sul dispositivo che tenta di effettuare il provisioning e sulla registrazione o sul gruppo di registrazione individuale tramite cui viene effettuato il provisioning. Le informazioni sul dispositivo possono includere un payload personalizzato facoltativo inviato dal dispositivo nella richiesta di registrazione. Per altre informazioni, vedere Richiesta di criteri di allocazione personalizzata.

  4. La funzione di Azure viene eseguita e restituisce un oggetto AllocationResponse in caso di esito positivo. L'oggetto AllocationResponse contiene l'hub IoT in cui deve essere effettuato il provisioning del dispositivo, lo stato iniziale del gemello e un payload personalizzato facoltativo per tornare al dispositivo. Per altre informazioni, vedere Risposta dei criteri di allocazione personalizzata.

  5. Dps assegna il dispositivo all'hub IoT indicato nella risposta e, se viene restituito un gemello iniziale, imposta di conseguenza il gemello iniziale per il dispositivo. Se un payload personalizzato viene restituito dal webhook, viene passato al dispositivo insieme ai dettagli di autenticazione e dell'hub IoT assegnati nella risposta di registrazione del servizio Device Provisioning.

  6. Il dispositivo si connette all'hub IoT assegnato e scarica lo stato iniziale del dispositivo gemello. Se viene restituito un payload personalizzato nella risposta di registrazione, il dispositivo lo usa in base alla propria logica lato client.

Nelle sezioni seguenti vengono fornite informazioni più dettagliate sulla richiesta e la risposta di allocazione personalizzata, i payload personalizzati e l'implementazione dei criteri. Per un esempio end-to-end completo di criteri di allocazione personalizzati, vedere Usare criteri di allocazione personalizzati.

Richiesta di criteri di allocazione personalizzata

Dps invia una richiesta POST al webhook nell'endpoint seguente: https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

Il corpo della richiesta è un oggetto AllocationRequest :

Nome proprietà Descrizione
individualEnrollment Un singolo record di registrazione contenente le proprietà associate alla registrazione singola da cui ha avuto origine la richiesta di allocazione. Presente se il dispositivo esegue la registrazione tramite una registrazione singola.
enrollmentGroup Record del gruppo di registrazione che contiene le proprietà associate al gruppo di registrazione da cui ha avuto origine la richiesta di allocazione. Presente se il dispositivo esegue la registrazione tramite un gruppo di registrazione.
deviceRuntimeContext Oggetto che contiene le proprietà associate al dispositivo che sta registrando. Sempre presente.
linkedHubs Matrice che contiene i nomi host degli hub IoT collegati alla voce di registrazione da cui ha avuto origine la richiesta di allocazione. Il dispositivo può essere assegnato a uno di questi hub IoT. Sempre presente.

L'oggetto DeviceRuntimeContext ha le proprietà seguenti:

Proprietà Type Descrizione
registrationId string ID di registrazione fornito dal dispositivo in fase di esecuzione. Sempre presente.
currentIotHubHostName string Nome host dell'hub IoT a cui il dispositivo è stato precedentemente assegnato (se presente). Non presente se si tratta di un'assegnazione iniziale. È possibile usare questa proprietà per determinare se si tratta di un'assegnazione iniziale per il dispositivo o se il dispositivo è stato assegnato in precedenza.
currentDeviceId string ID dispositivo dell'assegnazione precedente del dispositivo (se presente). Non presente se si tratta di un'assegnazione iniziale.
x509 X509DeviceAttestation Per l'attestazione X.509, contiene i dettagli del certificato.
symmetricKey SymmetricKeyAttestation Per l'attestazione della chiave simmetrica, contiene i dettagli della chiave primaria e secondaria.
tpm TpmAttestation Per l'attestazione TPM, contiene i dettagli della chiave radice di verifica dell'autenticità e della chiave radice di archiviazione.
payload oggetto Contiene le proprietà specificate dal dispositivo nella proprietà payload durante la registrazione. Presente se il dispositivo invia un payload personalizzato nella richiesta di registrazione dps.

Il codice JSON seguente mostra l'oggetto AllocationRequest inviato da DPS per un dispositivo che registra tramite un gruppo di registrazione basato su chiave simmetrica.

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

Poiché si tratta della registrazione iniziale per il dispositivo, la proprietà deviceRuntimeContext contiene solo l'ID registrazione e i dettagli di autenticazione per il dispositivo. Il codice JSON seguente illustra deviceRuntimeContext per una chiamata successiva per registrare lo stesso dispositivo. Si noti che nella richiesta sono inclusi il nome host e l'ID dispositivo correnti hub IoT.

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

Risposta dei criteri di allocazione personalizzata

Una richiesta con esito positivo restituisce un oggetto AllocationResponse .

Proprietà Descrizione
initialTwin Facoltativo. Oggetto che contiene le proprietà e i tag desiderati da impostare nel gemello iniziale nell'hub IoT assegnato. DPS usa la proprietà initialTwin per impostare il gemello iniziale nell'hub IoT assegnato durante l'assegnazione iniziale o durante il reprovisioning se i criteri di migrazione della voce di registrazione sono impostati su Reprovision e reimpostano la configurazione iniziale. In entrambi questi casi, se initialTwin non viene restituito o è impostato su Null, DPS imposta il gemello nell'hub IoT assegnato sulle impostazioni iniziali del gemello nella voce di registrazione. DPS ignora l'oggetto initialTwin per tutte le altre impostazioni di reprovisioning nella voce di registrazione. Per altre informazioni, vedere Dettagli sull'implementazione.
iotHubHostName Obbligatorio. Nome host dell'hub IoT a cui assegnare il dispositivo. Deve essere uno degli hub IoT passati nella proprietà linkedHubs nella richiesta.
payload Facoltativo. Oggetto che contiene i dati da passare di nuovo al dispositivo nella risposta di registrazione. I dati esatti dipendono dal contratto implicito definito dallo sviluppatore tra il dispositivo e la funzione di allocazione personalizzata.

Il codice JSON seguente mostra l'oggetto AllocationResponse restituito da una funzione di allocazione personalizzata a DPS per la registrazione di esempio precedente.

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

Usare i payload del dispositivo nell'allocazione personalizzata

I dispositivi possono inviare un payload personalizzato passato dal servizio Device Provisioning al webhook di allocazione personalizzato, che può quindi usare tali dati nella logica. Il webhook può usare questi dati in diversi modi, ad esempio per determinare l'hub IoT a cui assegnare il dispositivo o per cercare informazioni in un database esterno che potrebbe essere usato per impostare le proprietà nel gemello iniziale. Al contrario, il webhook può restituire i dati al dispositivo tramite DPS, che può essere usato nella logica lato client del dispositivo.

Ad esempio, è possibile allocare i dispositivi in base al modello di dispositivo. In questo caso, è possibile configurare il dispositivo per segnalare le informazioni sul modello nel payload della richiesta quando viene registrato con DPS. Dps passerà questo payload al webhook di allocazione personalizzata, che determinerà l'hub IoT a cui verrà effettuato il provisioning del dispositivo in base alle informazioni sul modello di dispositivo. Se necessario, il webhook può restituire i dati al servizio Device Provisioning come oggetto JSON nella risposta del webhook e DPS restituirà questi dati al dispositivo nella risposta di registrazione.

Il dispositivo invia il payload dei dati al servizio Device Provisioning

Un dispositivo chiama l'API di registrazione per la registrazione con dps. La richiesta può essere migliorata con la proprietà payload facoltativa. Questa proprietà può contenere qualsiasi oggetto JSON valido. Il contenuto esatto dipenderà dai requisiti della soluzione.

Per l'attestazione con TPM, il corpo della richiesta è simile al seguente:

{ 
    "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 invia il payload dei dati al webhook di allocazione personalizzato

Se un dispositivo include una richiesta di registrazione del payload, DPS passa il payload nella proprietà AllocationRequest.deviceRuntimeContext.payload quando chiama il webhook di allocazione personalizzato.

Per la richiesta di registrazione TPM nella sezione precedente, il contesto di runtime del dispositivo sarà simile al seguente:

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

Se non è la registrazione iniziale per il dispositivo, il contesto di runtime includerà anche currentIoTHubHostname e le proprietà currentDeviceId.

Il webhook di allocazione personalizzata restituisce i dati al servizio Device Provisioning

Il webhook dei criteri di allocazione personalizzato può restituire dati destinati a un dispositivo al servizio Device Provisioning in un oggetto JSON usando la proprietà AllocationResponse.payload nella risposta del webhook.

Il codice JSON seguente mostra una risposta webhook che include un payload:

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

DPS invia il payload dei dati al dispositivo

Se DPS riceve un payload nella risposta del webhook, questi dati vengono passati al dispositivo nella proprietà RegistrationOperationStatus.registrationState.payload nella risposta in caso di esito positivo della registrazione. La proprietà registrationState è di tipo DeviceRegistrationResult.

Il codice JSON seguente mostra una risposta di registrazione riuscita per un dispositivo TPM che include la proprietà 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"}
   }
}

Dettagli sull'implementazione

Il webhook di allocazione personalizzato può essere chiamato per un dispositivo che non è stato registrato in precedenza tramite DPS (assegnazione iniziale) o per un dispositivo registrato in precedenza tramite DPS (reprovisioning). Dps supporta i criteri di reprovisioning seguenti: effettuare il reprovisioning e eseguire la migrazione dei dati, effettuare il reprovisioning e reimpostare la configurazione iniziale e Non eseguire mai il provisioning. Questi criteri vengono applicati ogni volta che un dispositivo di cui è stato effettuato il provisioning in precedenza viene assegnato a un nuovo hub IoT. Per altri dettagli, vedere Reprovisioning.

I punti seguenti descrivono i requisiti che il webhook di allocazione personalizzata deve osservare e tenere presente quando si progetta il webhook:

  • Il dispositivo deve essere assegnato a uno degli hub IoT nella proprietà AllocationRequest.linkedHubs . Questa proprietà contiene l'elenco di hub IoT in base al nome host a cui il dispositivo può essere assegnato. Si tratta in genere di hub IoT selezionati per la voce di registrazione. Se non sono selezionati hub IoT nella voce di registrazione, conterrà tutti gli hub IoT collegati all'istanza del servizio Device Provisioning. Infine, se il dispositivo esegue il reprovisioning e il criterio Non è mai stato impostato nella voce di registrazione, conterrà solo l'hub IoT a cui è attualmente assegnato il dispositivo.

  • Durante l'assegnazione iniziale, se la proprietà initialTwin viene restituita dal webhook, DPS imposta il gemello iniziale per il dispositivo nell'hub IoT assegnato di conseguenza. Se la proprietà initialTwin viene omessa o è null, DPS imposta il gemello iniziale per il dispositivo sull'impostazione iniziale del gemello specificata nella voce di registrazione.

  • Durante il reprovisioning, DPS segue i criteri di provisioning impostati nella voce di registrazione. DPS usa solo la proprietà initialTwin nella risposta se l'hub IoT corrente viene modificato e il criterio di reprovisioning impostato nella voce di registrazione è Reprovision e reimposta la configurazione iniziale. In questo caso, DPS imposta il gemello iniziale per il dispositivo nel nuovo hub IoT esattamente come durante l'assegnazione iniziale nel punto elenco precedente. In tutti gli altri casi, DPS ignora la proprietà initialTwin .

  • Se la proprietà payload è impostata nella risposta, dps lo restituirà sempre al dispositivo indipendentemente dal fatto che la richiesta sia per l'assegnazione iniziale o il nuovo provisioning.

  • Se in precedenza è stato effettuato il provisioning di un dispositivo in un hub IoT, AllocationRequest.deviceRuntimeContext conterrà una proprietà currentIotHubHostName , che verrà impostata sul nome host dell'hub IoT in cui è attualmente assegnato il dispositivo.

  • È possibile determinare quale dei criteri di reprovisioning è attualmente impostato nella voce di registrazione esaminando la proprietà reprovisionPolicy della proprietà AllocationRequest.individualEnrollment o AllocationRequest.enrollmentGroup nella richiesta. il codice JSON seguente mostra le impostazioni per il reprovisioning e la migrazione dei criteri di dati :

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

Supporto SDK

Gli SDK per dispositivi DPS forniscono API in C, C#, Java e Node.js per registrare i dispositivi con DPS. Sia gli SDK hub IoT che gli SDK DPS forniscono classi che rappresentano artefatti del dispositivo e del servizio, ad esempio dispositivi gemelli e voci di registrazione che potrebbero essere utili quando si sviluppano webhook di allocazione personalizzati. Per altre informazioni sugli SDK di Azure IoT disponibili per hub IoT e hub IoT servizio Device Provisioning, vedere SDK hub IoT di Azure e AZURE DPS SDK.

Passaggi successivi