Esercitazione: Usare criteri di allocazione personalizzati con il servizio Device Provisioning

Articolo
04/05/2024

I criteri di allocazione personalizzati offrono un maggiore controllo sulla modalità di assegnazione dei dispositivi agli hub IoT. Con i criteri di allocazione personalizzati, è possibile definire criteri di allocazione personalizzati quando i criteri forniti dal servizio Device Provisioning (DPS) hub IoT di Azure non soddisfano i requisiti dello scenario. I criteri di allocazione personalizzati vengono implementati in un webhook ospitato in Funzioni di Azure e configurati in una o più registrazioni e/o gruppi di registrazione singoli. Quando un dispositivo viene registrato con dps usando una voce di registrazione configurata, dps chiama il webhook per individuare l'hub IoT in cui il dispositivo deve essere registrato e, facoltativamente, il relativo stato iniziale. Per altre informazioni, vedere Informazioni sui criteri di allocazione personalizzati.

Questa esercitazione illustra un criterio di allocazione personalizzato usando una funzione di Azure scritta in C#. I dispositivi vengono assegnati a uno dei due hub IoT che rappresentano una divisione contoso di tostapane e una divisione pompe di calore Contoso. Per essere accettati per il provisioning, i dispositivi che richiedono questo servizio devono avere un ID di registrazione con uno dei suffissi di seguito:

-contoso-tstrsd-007 per la divisione Tostapane contoso
-contoso-hpsd-088 per la divisione Pompe di calore Contoso

I dispositivi vengono simulati usando un esempio di provisioning incluso in Azure IoT C SDK.

In questa esercitazione si eseguiranno le operazioni seguenti:

Usare l'interfaccia della riga di comando di Azure per creare un'istanza dps e collegare due hub IoT della divisione Contoso (ContosoPanes Division e Contoso Heat Pump Division) a tale istanza.
Creare una funzione di Azure che implementa i criteri di allocazione personalizzati.
Creare un nuovo gruppo di registrazioni usa la funzione di Azure per i criteri di allocazione personalizzati.
Creare chiavi simmetriche del dispositivo per due dispositivi simulati.
Configurare l'ambiente di sviluppo per Azure IoT C SDK.
Simulare i dispositivi e verificare che venga effettuato il provisioning in base al codice di esempio nei criteri di allocazione personalizzati.

Se non si ha una sottoscrizione di Azure, creare un account Azure gratuito prima di iniziare.

Prerequisiti

I prerequisiti seguenti si riferiscono a un ambiente di sviluppo Windows. Per Linux o macOS, vedere la sezione appropriata in Preparare l'ambiente di sviluppo nella documentazione dell'SDK.

Visual Studio 2022 con il carico di lavoro "Sviluppo di applicazioni desktop con C++" abilitato. Sono supportati anche Visual Studio 2015 e Visual Studio 2017.
Git installato. Per altre informazioni, vedere Download git.
L'interfaccia della riga di comando di Azure installata. Per altre informazioni, vedere Come installare l'interfaccia della riga di comando di Azure. In alternativa, è possibile eseguire i comandi in questa esercitazione nell'ambiente Bash in Azure Cloud Shell.

Creare il servizio di provisioning e due hub IoT

In questa sezione si usa Azure Cloud Shell per creare un servizio di provisioning e due hub IoT che rappresentano la divisione ContosoPanes e la divisione Pompe di calore Contoso.

Prima di tutto, impostare le variabili di ambiente nell'area di lavoro per semplificare i comandi in questa esercitazione.

I nomi dps e hub IoT devono essere univoci a livello globale. Sostituire il SUFFIX segnaposto con il proprio valore.

Il codice della funzione di Azure creato più avanti in questa esercitazione cerca anche gli hub IoT con -toasters- o -heatpumps- nei relativi nomi. Se si modificano i valori suggeriti, assicurarsi di usare nomi contenenti le sottostringhe necessarie.
```
#!/bin/bash
export RESOURCE_GROUP="contoso-us-resource-group"
export LOCATION="westus"
export DPS="contoso-provisioning-service-SUFFIX"
export TOASTER_HUB="contoso-toasters-hub-SUFFIX"
export HEATPUMP_HUB="contoso-heatpumps-hub-SUFFIX"
```
```
# PowerShell
$env:RESOURCE_GROUP = "contoso-us-resource-group"
$env:LOCATION = "westus"
$env:DPS = "contoso-provisioning-service-SUFFIX"
$env:TOASTER_HUB = "contoso-toasters-hub-SUFFIX"
$env:HEATPUMP_HUB = "contoso-heatpumps-hub-SUFFIX"
```
Suggerimento

I comandi usati in questa esercitazione creano risorse nella posizione Stati Uniti occidentali per impostazione predefinita. È consigliabile creare le risorse nell'area più vicina che supporta il servizio Device Provisioning. È possibile visualizzare un elenco delle posizioni disponibili passando alla pagina Stato di Azure e cercando "Servizio Device Provisioning". Nei comandi, le posizioni possono essere specificate in un formato di parola o di più parole; ad esempio: westus, Stati Uniti occidentali, Stati Uniti occidentali e così via. Il valore non fa distinzione tra maiuscole e minuscole.
Usare il comando az group create per creare un gruppo di risorse di Azure. Un gruppo di risorse di Azure è un contenitore logico in cui le risorse di Azure vengono distribuite e gestite.

Nell'esempio seguente viene creato un gruppo di risorse. È consigliabile usare un singolo gruppo per tutte le risorse create in questa esercitazione. Questo approccio renderà più semplice la pulizia al termine dell'operazione.
```
az group create --name $RESOURCE_GROUP --location $LOCATION
```
Usare il comando az iot dps create per creare un'istanza del servizio Device Provisioning.Use the az iot dps create command to create an instance of the Device Provisioning Service (DPS). Il servizio di provisioning viene aggiunto a contoso-us-resource-group.
```
az iot dps create --name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION
```
Il completamento di questo comando potrebbe richiedere alcuni minuti.
Usare il comando az iot hub create per creare l'hub IoT ContosoPanes Division . L'hub IoT viene aggiunto a contoso-us-resource-group.
```
az iot hub create --name $TOASTER_HUB --resource-group $RESOURCE_GROUP --location $LOCATION --sku S1
```
Il completamento di questo comando potrebbe richiedere alcuni minuti.
Usare il comando az iot hub create per creare l'hub IoT di Contoso Heat Pump Division . Questo hub IoT viene aggiunto anche a contoso-us-resource-group.
```
az iot hub create --name $HEATPUMP_HUB --resource-group $RESOURCE_GROUP --location $LOCATION --sku S1
```
Il completamento di questo comando potrebbe richiedere alcuni minuti.

Eseguire i due comandi seguenti per ottenere i stringa di connessione per gli hub creati.

az iot hub connection-string show --hub-name $TOASTER_HUB --key primary --query connectionString -o tsv
az iot hub connection-string show --hub-name $HEATPUMP_HUB --key primary --query connectionString -o tsv

Eseguire i comandi seguenti per collegare gli hub alla risorsa dps. Sostituire i segnaposto con i stringa di connessione hub del passaggio precedente.

az iot dps linked-hub create --dps-name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION --connection-string <toaster_hub_connection_string>
az iot dps linked-hub create --dps-name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION --connection-string <heatpump_hub_connection_string>

Creare la funzione di allocazione personalizzata

In questa sezione viene creata una funzione di Azure che implementa il criterio di allocazione personalizzato. Questa funzione decide a quale hub IoT divisionale deve essere registrato un dispositivo in base al fatto che l'ID di registrazione contenga la stringa -contoso-tstrsd-007 o -contoso-hpsd-088. Imposta anche lo stato iniziale del dispositivo gemello in base al fatto che il dispositivo sia un tostapane o una pompa di calore.

Accedere al portale di Azure.
Nella casella di ricerca cercare e selezionare App per le funzioni.
Selezionare Crea o Crea app per le funzioni.

Nella pagina Crea app per le funzioni, nella scheda Informazioni di base immettere le impostazioni seguenti per la nuova app per le funzioni e selezionare Rivedi e crea:

Parametro	Valore
Abbonamento	Assicurarsi che sia selezionata la sottoscrizione in cui sono state create le risorse per questa esercitazione.
Gruppo di risorse	Selezionare il gruppo di risorse creato nella sezione precedente. Il valore predefinito fornito nella sezione precedente è contoso-us-resource-group.
Nome dell'app per le funzioni	Fornire un nome per l'app per le funzioni.
Distribuire codice o immagine del contenitore?	Codice
Stack di runtime	.NET
Versione	Selezionare qualsiasi versione del modello in-process.
Area	Selezionare un'area nelle vicinanze.

Nota

Per impostazione predefinita, la funzionalità Application Insights è abilitata. Application Insights non è necessario per questa esercitazione, ma può essere utile per comprendere e analizzare eventuali problemi riscontrati con l'allocazione personalizzata. Se si preferisce, è possibile disabilitare Application Insights selezionando la scheda Monitoraggio e quindi No per Abilita Application Insights.

Screenshot che mostra il modulo Crea app per le funzioni nel portale di Azure.

Nella scheda Rivedi e crea selezionare Crea per creare l'app per le funzioni.
La distribuzione potrebbe richiedere alcuni minuti. Al termine, selezionare Vai alla risorsa.
Nel riquadro sinistro della pagina Panoramica dell'app per le funzioni selezionare Crea funzione.
Nella pagina Crea funzione selezionare il modello Trigger HTTP e quindi selezionare Avanti.
Nella scheda Dettagli modello selezionare Anonimo come livello di autorizzazione e quindi selezionare Crea.

Suggerimento

Se si mantiene il livello di autorizzazione come Funzione, sarà necessario configurare le registrazioni dps con la chiave API della funzione. Per altre informazioni, vedere Funzioni di Azure trigger HTTP.
Quando si apre la funzione HttpTrigger1 , selezionare Codice e test nel riquadro sinistro. In questo modo è possibile modificare il codice per la funzione. Il file di codice run.csx deve essere aperto per la modifica.
Riferimento ai pacchetti NuGet necessari. Per creare il dispositivo gemello iniziale, la funzione di allocazione personalizzata usa classi definite in due pacchetti NuGet che devono essere caricati nell'ambiente di hosting. Con Funzioni di Azure, viene fatto riferimento ai pacchetti NuGet usando un file function.proj. In questo passaggio si salva e si carica un file function.proj per gli assembly necessari. Per altre informazioni, vedere Uso di pacchetti NuGet con Funzioni di Azure.
1. Copiare le righe seguenti nell'editor preferito e salvare il file nel computer come function.proj.
```
<Project Sdk="Microsoft.NET.Sdk">  
    <PropertyGroup>  
        <TargetFramework>netstandard2.0</TargetFramework>  
    </PropertyGroup>  
    <ItemGroup>  
        <PackageReference Include="Microsoft.Azure.Devices.Provisioning.Service" Version="1.18.1" />
        <PackageReference Include="Microsoft.Azure.Devices.Shared" Version="1.30.1" />
    </ItemGroup>  
</Project>
```
2. Selezionare il pulsante Carica posizionato sopra l'editor di codice per caricare il file function.proj . Dopo il caricamento, selezionare il file nell'editor di codice usando la casella di riepilogo a discesa per verificare il contenuto.
3. Selezionare il file function.proj nell'editor di codice e verificarne il contenuto. Se il file function.proj è vuoto, copiare le righe precedenti nel file e salvarlo. A volte il caricamento crea il file senza caricare il contenuto.

Assicurarsi che run.csx per HttpTrigger1 sia selezionato nell'editor di codice. Sostituire il codice per la funzione HttpTrigger1 con il codice seguente e selezionare Salva:

#r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

using Microsoft.Azure.Devices.Shared;               // For TwinCollection
using Microsoft.Azure.Devices.Provisioning.Service; // For TwinState

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    // Get request body
    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);

    log.LogInformation("Request.Body:...");
    log.LogInformation(requestBody);

    // Get registration ID of the device
    string regId = data?.deviceRuntimeContext?.registrationId;

    string message = "Uncaught error";
    bool fail = false;
    ResponseObj obj = new ResponseObj();

    if (regId == null)
    {
        message = "Registration ID not provided for the device.";
        log.LogInformation("Registration ID : NULL");
        fail = true;
    }
    else
    {
        string[] hubs = data?.linkedHubs?.ToObject<string[]>();

        // Must have hubs selected on the enrollment
        if (hubs == null)
        {
            message = "No hub group defined for the enrollment.";
            log.LogInformation("linkedHubs : NULL");
            fail = true;
        }
        else
        {
            // This is a Contoso Toaster Model 007
            if (regId.Contains("-contoso-tstrsd-007"))
            {
                //Find the "-toasters-" IoT hub configured on the enrollment
                foreach(string hubString in hubs)
                {
                    if (hubString.Contains("-toasters-"))
                        obj.iotHubHostName = hubString;
                }

                if (obj.iotHubHostName == null)
                {
                    message = "No toasters hub found for the enrollment.";
                    log.LogInformation(message);
                    fail = true;
                }
                else
                {
                    // Specify the initial tags for the device.
                    TwinCollection tags = new TwinCollection();
                    tags["deviceType"] = "toaster";

                    // Specify the initial desired properties for the device.
                    TwinCollection properties = new TwinCollection();
                    properties["state"] = "ready";
                    properties["darknessSetting"] = "medium";

                    // Add the initial twin state to the response.
                    TwinState twinState = new TwinState(tags, properties);
                    obj.initialTwin = twinState;
                }
            }
            // This is a Contoso Heat pump Model 008
            else if (regId.Contains("-contoso-hpsd-088"))
            {
                //Find the "-heatpumps-" IoT hub configured on the enrollment
                foreach(string hubString in hubs)
                {
                    if (hubString.Contains("-heatpumps-"))
                        obj.iotHubHostName = hubString;
                }

                if (obj.iotHubHostName == null)
                {
                    message = "No heat pumps hub found for the enrollment.";
                    log.LogInformation(message);
                    fail = true;
                }
                else
                {
                    // Specify the initial tags for the device.
                    TwinCollection tags = new TwinCollection();
                    tags["deviceType"] = "heatpump";

                    // Specify the initial desired properties for the device.
                    TwinCollection properties = new TwinCollection();
                    properties["state"] = "on";
                    properties["temperatureSetting"] = "65";

                    // Add the initial twin state to the response.
                    TwinState twinState = new TwinState(tags, properties);
                    obj.initialTwin = twinState;
                }
            }
            // Unrecognized device.
            else
            {
                fail = true;
                message = "Unrecognized device registration.";
                log.LogInformation("Unknown device registration");
            }
        }
    }

    log.LogInformation("\nResponse");
    log.LogInformation((obj.iotHubHostName != null) ? JsonConvert.SerializeObject(obj) : message);

    return (fail)
        ? new BadRequestObjectResult(message) 
        : (ActionResult)new OkObjectResult(obj);
}

public class ResponseObj
{
    public string iotHubHostName {get; set;}
    public TwinState initialTwin {get; set;}
}

Creare la registrazione

In questa sezione viene creato un nuovo gruppo di registrazione che usa i criteri di allocazione personalizzati. Per semplicità, questa esercitazione usa l'attestazione con chiave simmetrica con la registrazione. Per una soluzione più sicura è consigliabile usare l'attestazione del certificato X.509 con una catena di certificati.

Accedere al portale di Azure e aprire l'istanza del servizio Device Provisioning.
Selezionare Gestisci registrazioni nella sezione Impostazioni del menu di spostamento.
Selezionare Aggiungi gruppo di registrazione.

Nella scheda Registrazione e provisioning della pagina Aggiungi gruppo di registrazione specificare le informazioni seguenti per configurare i dettagli del gruppo di registrazione:

Campo	Descrizione
Attestazione	Selezionare Chiave simmetrica come meccanismo di attestazione.
Impostazioni della chiave simmetrica	Selezionare la casella Genera chiavi simmetriche automaticamente .
Nome gruppo	Immettere contoso-custom-allocate-devices come nome del gruppo.
Stato del provisioning	Selezionare la casella Abilita questa registrazione .

Selezionare Avanti: Hub IoT.

Nella scheda Hub IoT della pagina Aggiungi gruppo di registrazione specificare le informazioni seguenti per determinare gli hub IoT a cui il gruppo di registrazione può effettuare il provisioning dei dispositivi:

Campo	Descrizione
Hub IoT di destinazione	Selezionare uno o più hub IoT collegati oppure aggiungere un nuovo collegamento a un hub IoT.
Criteri di allocazione	Selezionare Personalizzato (usare la funzione di Azure). Selezionare Selezionare la funzione di Azure e quindi seguire le istruzioni per selezionare la funzione creata per questa esercitazione.

Selezionare Rivedi e crea.
Nella scheda Rivedi e crea verificare tutti i valori e quindi selezionare Crea.

Dopo aver salvato la registrazione, riaprirla e prendere nota della chiave primaria. È necessario salvare la registrazione prima di poter generare le chiavi. Questa chiave viene usata per generare chiavi univoca del dispositivo per i dispositivi simulati nella sezione successiva.

Derivare le chiavi univoche di dispositivo

I dispositivi non usano direttamente la chiave simmetrica primaria del gruppo di registrazione. Usare invece la chiave primaria per derivare una chiave del dispositivo per ogni dispositivo. In questa sezione si creeranno due chiavi univoche per i dispositivi. Una chiave viene usata per un dispositivo tostapane simulato. L'altra chiave viene usata per un dispositivo pompa di calore simulato.

Per derivare la chiave del dispositivo, usare la chiave primaria del gruppo di registrazione annotata in precedenza per calcolare HMAC-SHA256 dell'ID di registrazione del dispositivo per ogni dispositivo e convertire il risultato in formato Base 64. Per altre informazioni sulla creazione di chiavi di dispositivo derivate con i gruppi di registrazione, vedere la sezione sulle registrazioni di gruppo dell'articolo Attestazione con chiave simmetrica.

Per l'esempio in questa esercitazione, usare i due ID di registrazione del dispositivo seguenti e calcolare una chiave del dispositivo per entrambi i dispositivi. Entrambi gli ID di registrazione presentano un suffisso valido per il funzionamento con il codice di esempio per i criteri di allocazione personalizzati:

breakroom499-contoso-tstrsd-007
mainbuilding167-contoso-hpsd-088

L'estensione IoT per l'interfaccia della riga di comando di Azure fornisce il iot dps enrollment-group compute-device-key comando per la generazione di chiavi di dispositivo derivate. Questo comando può essere usato nei sistemi Windows o Linux, da PowerShell o da una shell Bash.

Sostituire il valore dell'argomento --key con la chiave primaria del gruppo di registrazione.

az iot dps enrollment-group compute-device-key --key <ENROLLMENT_GROUP_KEY> --registration-id breakroom499-contoso-tstrsd-007

az iot dps compute-device-key --key <ENROLLMENT_GROUP_KEY> --registration-id mainbuilding167-contoso-hpsd-088

Nota

È anche possibile fornire l'ID del gruppo di registrazione anziché la chiave simmetrica al iot dps enrollment-group compute-device-key comando. Ad esempio:

az iot dps enrollment-group compute-device-key -g contoso-us-resource-group --dps-name contoso-provisioning-service-1098 --enrollment-id contoso-custom-allocated-devices --registration-id breakroom499-contoso-tstrsd-007

I dispositivi simulati usano le chiavi del dispositivo derivate con ogni ID di registrazione per eseguire l'attestazione della chiave simmetrica.

Preparare un ambiente di sviluppo per Azure IoT C SDK

In questa sezione si prepara l'ambiente di sviluppo da usare per creare Azure IoT C SDK. L'SDK include il codice di esempio per il dispositivo simulato. Il dispositivo simulato tenterà di effettuare il provisioning durante la sequenza di avvio del dispositivo.

Questa sezione si riferisce a una workstation basata su Windows. Per un esempio di Linux, vedere la configurazione delle macchine virtuali in Esercitazione: Effettuare il provisioning per la latenza geografica.

Scaricare il sistema di compilazione CMake.

È importante che i prerequisiti di Visual Studio (Visual Studio e il carico di lavoro "Sviluppo di applicazioni desktop con C++") siano installati nel computer prima di avviare l'installazione di CMake. Quando i prerequisiti sono pronti e il download è stato verificato, installare il sistema di compilazione CMake.
Trovare il nome del tag per la versione più recente dell'SDK.
Aprire un prompt dei comandi o la shell Git Bash. Eseguire i comandi seguenti per clonare la versione più recente del repository GitHub azure IoT Device SDK per C . Usare il tag trovato nel passaggio precedente come valore per il -b parametro , ad esempio : lts_01_2023.
```
git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init
```
Il completamento di questa operazione richiederà alcuni minuti.
Creare una sottodirectory cmake nella directory radice del repository Git e passare a tale cartella. Eseguire i comandi seguenti dalla directory azure-iot-sdk-c:
```
mkdir cmake
cd cmake
```
Eseguire il comando seguente che compila una versione dell'SDK specifica per la piattaforma di sviluppo client. Verrà generata una soluzione di Visual Studio per il dispositivo simulato nella directory cmake.
```
cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
```
Se cmake non trova il compilatore C++, potrebbero verificarsi errori di compilazione durante l'esecuzione del comando. In tal caso, provare a eseguire il comando nel prompt dei comandi di Visual Studio.

Al termine della compilazione, le ultime righe di output saranno simili all'output seguente:
```
$ cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
-- Building for: Visual Studio 15 2017
-- Selecting Windows SDK version 10.0.16299.0 to target Windows 10.0.17134.
-- The C compiler identification is MSVC 19.12.25835.0
-- The CXX compiler identification is MSVC 19.12.25835.0

...

-- Configuring done
-- Generating done
-- Build files have been written to: E:/IoT Testing/azure-iot-sdk-c/cmake
```

Simulare i dispositivi

In questa sezione viene aggiornato un esempio di provisioning denominato prov_dev_client_sample disponibile nell'SDK C di Azure IoT configurato in precedenza.

Questo codice di esempio simula una sequenza di avvio di dispositivo che invia la richiesta di provisioning all'istanza del servizio Device Provisioning. La sequenza di avvio fa sì che il dispositivo tostapane venga riconosciuto e assegnato all'hub IoT usando i criteri di allocazione personalizzati.

Nella portale di Azure selezionare la scheda Panoramica per il servizio Device Provisioning e prendere nota del valore Ambito ID.
In Visual Studio aprire il file di soluzione azure_iot_sdks.sln generato in precedenza tramite l'esecuzione di CMake. Il file della soluzione deve trovarsi nel percorso seguente: azure-iot-sdk-c\cmake\azure_iot_sdks.sln.
Nella finestra Esplora soluzioni di Visual Studio passare alla cartella Provision_Samples. Espandere il progetto di esempio denominato prov_dev_client_sample. Espandere File di origine e aprire prov_dev_client_sample.c.
Trovare la costante id_scope e sostituire il valore con il valore Ambito ID copiato in precedenza.
```
static const char* id_scope = "0ne00002193";
```
Trovare la definizione per la funzione main() nello stesso file. Assicurarsi che la variabilehsm_type sia impostata su SECURE_DEVICE_TYPE_SYMMETRIC_KEY come illustrato di seguito:
```
SECURE_DEVICE_TYPE hsm_type;
//hsm_type = SECURE_DEVICE_TYPE_TPM;
//hsm_type = SECURE_DEVICE_TYPE_X509;
hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;
```
Nella funzione main() trovare la chiamata a Prov_Device_Register_Device(). Subito prima della chiamata aggiungere le righe di codice seguenti che usano Prov_Device_Set_Provisioning_Payload() per passare un payload JSON personalizzato durante il provisioning. Questo payload può essere usato per fornire altre informazioni alle funzioni di allocazione personalizzate. Può essere usato anche per passare il tipo di dispositivo invece di esaminare l'ID registrazione. Per altre informazioni sull'invio e la ricezione di payload di dati personalizzati con DPS, vedere Come trasferire payload tra dispositivi e DPS.
```
// An example custom payload
const char* custom_json_payload = "{\"MyDeviceFirmwareVersion\":\"12.0.2.5\",\"MyDeviceProvisioningVersion\":\"1.0.0.0\"}";

prov_device_result = Prov_Device_Set_Provisioning_Payload(prov_device_handle, custom_json_payload);
if (prov_device_result != PROV_DEVICE_RESULT_OK)
{
    (void)printf("\r\nFailure setting provisioning payload: %s\r\n", MU_ENUM_TO_STRING(PROV_DEVICE_RESULT, prov_device_result));
}
```
Fare clic con il pulsante destro del mouse sul progetto prov_dev_client_sample e scegliere Imposta come progetto di avvio.

Simulare il dispositivo toaster di Contoso

Per simulare il dispositivo tostapane, trovare la chiamata a prov_dev_set_symmetric_key_info() in prov_dev_client_sample.c , che è impostata come commento.
```
// Set the symmetric key if using they auth type
//prov_dev_set_symmetric_key_info("<symm_registration_id>", "<symmetric_Key>");
```
Rimuovere il commento dalla chiamata alla funzione e sostituire i valori segnaposto (incluse le parentesi angolari) con l'ID registrazione del toaster e la chiave di dispositivo derivata generata in precedenza. Il valore di chiave JC8F96eayuQwwz+PkE7IzjH2lIAjCUnAa61tDigBnSs= visualizzato di seguito viene fornito solo come esempio.
```
// Set the symmetric key if using they auth type
prov_dev_set_symmetric_key_info("breakroom499-contoso-tstrsd-007", "JC8F96eayuQwwz+PkE7IzjH2lIAjCUnAa61tDigBnSs=");
```
Salvare il file.

Nel menu di Visual Studio selezionare Debug>Avvia senza eseguire debug per eseguire la soluzione. Nella richiesta di ricompilare il progetto fare clic su Sì per ricompilare il progetto prima dell'esecuzione.

L'output seguente è un esempio del dispositivo tostapane simulato che viene avviato correttamente e si connette all'istanza del servizio di provisioning da assegnare all'hub IoT dei tostapane tramite i criteri di allocazione personalizzati:

Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-toasters-hub-1098.azure-devices.net, deviceId: breakroom499-contoso-tstrsd-007

Press enter key to exit:

L'output seguente è l'esempio di output di registrazione del codice della funzione di allocazione personalizzata in esecuzione per il dispositivo tostapane. Si noti che per un dispositivo toaster è stato correttamente selezionare un hub. Si noti anche la payload proprietà che contiene il contenuto JSON personalizzato aggiunto al codice. Può essere usato dal codice all'interno del deviceRuntimeContext.

Questa registrazione è disponibile facendo clic su Log sotto il codice della funzione nel portale:

2022-08-03T20:34:41.178 [Information] Executing 'Functions.HttpTrigger1' (Reason='This function was programmatically called via the host APIs.', Id=12950752-6d75-4f41-844b-c253a6653d4f)
2022-08-03T20:34:41.340 [Information] C# HTTP trigger function processed a request.
2022-08-03T20:34:41.341 [Information] Request.Body:...
2022-08-03T20:34:41.341 [Information] {"enrollmentGroup":{"enrollmentGroupId":"contoso-custom-allocated-devices","attestation":{"type":"symmetricKey"},"capabilities":{"iotEdge":false},"etag":"\"0000f176-0000-0700-0000-62eaad1e0000\"","provisioningStatus":"enabled","reprovisionPolicy":{"updateHubAssignment":true,"migrateDeviceData":true},"createdDateTimeUtc":"2022-08-03T17:15:10.8464255Z","lastUpdatedDateTimeUtc":"2022-08-03T17:15:10.8464255Z","allocationPolicy":"custom","iotHubs":["contoso-toasters-hub-1098.azure-devices.net","contoso-heatpumps-hub-1098.azure-devices.net"],"customAllocationDefinition":{"webhookUrl":"https://contoso-function-app-1098.azurewebsites.net/api/HttpTrigger1?****","apiVersion":"2021-10-01"}},"deviceRuntimeContext":{"registrationId":"breakroom499-contoso-tstrsd-007","currentIotHubHostName":"contoso-toasters-hub-1098.azure-devices.net","currentDeviceId":"breakroom499-contoso-tstrsd-007","symmetricKey":{},"payload":{"MyDeviceFirmwareVersion":"12.0.2.5","MyDeviceProvisioningVersion":"1.0.0.0"}},"linkedHubs":["contoso-toasters-hub-1098.azure-devices.net","contoso-heatpumps-hub-1098.azure-devices.net"]}
2022-08-03T20:34:41.382 [Information] Response
2022-08-03T20:34:41.398 [Information] {"iotHubHostName":"contoso-toasters-hub-1098.azure-devices.net","initialTwin":{"properties":{"desired":{"state":"ready","darknessSetting":"medium"}},"tags":{"deviceType":"toaster"}}}
2022-08-03T20:34:41.399 [Information] Executed 'Functions.HttpTrigger1' (Succeeded, Id=12950752-6d75-4f41-844b-c253a6653d4f, Duration=227ms)

Simulare il dispositivo pompa di calore di Contoso

Per simulare il dispositivo pompa di calore, aggiornare nuovamente la chiamata a prov_dev_set_symmetric_key_info() in prov_dev_client_sample.c con l'ID registrazione della pompa di calore e la chiave del dispositivo derivata generata in precedenza. Il valore di chiave 6uejA9PfkQgmYylj8Zerp3kcbeVrGZ172YLa7VSnJzg= visualizzato di seguito viene fornito solo come esempio.
```
// Set the symmetric key if using they auth type
prov_dev_set_symmetric_key_info("mainbuilding167-contoso-hpsd-088", "6uejA9PfkQgmYylj8Zerp3kcbeVrGZ172YLa7VSnJzg=");
```
Salvare il file.
Nel menu di Visual Studio selezionare Debug>Avvia senza eseguire debug per eseguire la soluzione. Nella richiesta di ricompilare il progetto fare clic su Sì per ricompilare il progetto prima dell'esecuzione.

L'output seguente è un esempio del dispositivo pompa di calore simulato che viene avviato correttamente e si connette all'istanza del servizio di provisioning da assegnare all'hub IoT delle pompe di calore Contoso in base ai criteri di allocazione personalizzati:
```
Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-heatpumps-hub-1098.azure-devices.net, deviceId: mainbuilding167-contoso-hpsd-088

Press enter key to exit:
```

Risolvere i problemi relativi ai criteri di allocazione personalizzati

La tabella seguente illustra gli scenari previsti e i codici di errore dei risultati che è possibile ricevere. Usare questa tabella come supporto per la risoluzione dei problemi relativi ai criteri di allocazione personalizzati con le Funzioni di Azure.

Scenario	Risultato della registrazione dal servizio di provisioning	Effettuare il provisioning dei risultati SDK
Il webhook restituisce 200 OK con 'iotHubHostName' impostato su un nome host dell'hub IoT valido	Stato del risultato: Assegnato	L'SDK restituisce PROV_DEVICE_RESULT_OK insieme alle informazioni dell'hub
Il webhook restituisce 200 OK con 'iotHubHostName' incluso nella risposta ma impostato su una stringa vuota o Null	Stato del risultato: Non riuscito Codice di errore: CustomAllocationIotHubNotSpecified (400208)	L'SDK restituisce PROV_DEVICE_RESULT_HUB_NOT_SPECIFIED
Il webhook restituisce 401 - Non autorizzato	Stato del risultato: Non riuscito Codice di errore: CustomAllocationUnauthorizedAccess (400209)	L'SDK restituisce PROV_DEVICE_RESULT_UNAUTHORIZED
È stata creata una registrazione singola per disabilitare il dispositivo	Stato del risultato: Non disponibile	L'SDK restituisce PROV_DEVICE_RESULT_DISABLED
Il webhook restituisce il codice >di errore = 429	L'orchestrazione del servizio Device Provisioning riprova più volte. I criteri di ripetizione sono attualmente: - Numero di tentativi: 10 - Intervallo iniziale: 1 s - Incremento: 9 s	L'SDK ignorerà l'errore e invierà un altro messaggio per l'ottenimento dello stato nel periodo specificato
Il webhook restituisce qualsiasi altro codice di stato	Stato del risultato: Non riuscito Codice di errore: CustomAllocationFailed (400207)	L'SDK restituisce PROV_DEVICE_RESULT_DEV_AUTH_ERROR

Pulire le risorse

Se si prevede di continuare a usare le risorse create in questa esercitazione, è possibile lasciarle. Se non si prevede di continuare a usare le risorse, seguire questa procedura per eliminare tutte le risorse create in questa esercitazione per evitare addebiti non necessari.

I passaggi seguenti presuppongono che tutte le risorse in questa esercitazione siano state create come indicato nello stesso gruppo di risorse denominato contoso-us-resource-group.

Importante

L'eliminazione di un gruppo di risorse è irreversibile. Il gruppo di risorse e tutte le risorse in esso contenute vengono eliminati in modo permanente. Assicurarsi di non eliminare accidentalmente il gruppo di risorse sbagliato o le risorse errate. Se si è creato l'hub IoT all'interno di un gruppo di risorse esistente che contiene risorse che si vogliono conservare, eliminare solo la risorsa dell'hub IoT invece di eliminare il gruppo di risorse.

Per eliminare il gruppo di risorse per nome:

Accedere al portale di Azure e selezionare Gruppi di risorse.
Nella casella di testo Filtra per nome... digitare il nome del gruppo di risorse che contiene le risorse di interesse, contoso-us-resource-group.
A destra del gruppo di risorse nell'elenco dei risultati selezionare ... quindi su Elimina gruppo di risorse.
Verrà chiesto di confermare l'eliminazione del gruppo di risorse. Digitare di nuovo il nome del gruppo di risorse per confermare e quindi selezionare Elimina. Dopo qualche istante il gruppo di risorse e tutte le risorse che contiene vengono eliminati.

Passaggi successivi

Per altre informazioni sui criteri di allocazione personalizzati, vedere

Informazioni sui criteri di allocazione personalizzati