Esercitazione: Usare criteri di allocazione personalizzati con il servizio di provisioning di dispositivi (DPS)

I criteri di allocazione personalizzati offrono un maggiore controllo sulla modalità di assegnazione dei dispositivi agli hub IoT. Con criteri di allocazione personalizzati, è possibile definire criteri di allocazione personalizzati qualora quelli integrati forniti dal Servizio Device Provisioning in hub IoT di Azure non soddisfino i requisiti di uno specifico scenario. I criteri di allocazione personalizzati vengono implementati in un webhook ospitato in Funzioni di Azure e configurati in una o più registrazioni singole e/o gruppi di registrazione. 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 con il servizio Device Provisioning in hub IoT di Azure.

Questa esercitazione illustra i criteri di allocazione personalizzati che usano una funzione di Azure scritta in C#. I dispositivi vengono assegnati a uno dei due hub IoT che rappresentano una Divisione Contoso Toasters e una Divisione Contoso Heat Pumps. 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 Contoso Toasters
-contoso-hpsd-088 per la Divisione Contoso Heat Pumps

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

In questa esercitazione vengono eseguite le azioni seguenti:

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

Se non si ha un account Azure, creare un account 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 di Git.
Interfaccia della riga di comando di Azure installata. Per altre informazioni, vedere 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 userà Azure Cloud Shell per creare un servizio di provisioning e due nuovi hub IoT per rappresentare la Divisione Contoso Toasters e la Divisione Contoso Heat Pumps.

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 segnaposto SUFFIXcon 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 faciliterà la pulizia una volta completate le operazioni.
```
az group create --name $RESOURCE_GROUP --location $LOCATION
```
Usare il comando az iot dps create per create per creare un'istanza del servizio Device Provisioning (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 della Divisione Contoso Toasters. 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 della Divisione Contoso Heat Pumps. 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
Sottoscrizione	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.
Stack di esecuzione	.NET
Versione	Selezionare qualsiasi versione del modello in-Process.
Area	Selezionare un'area nelle vicinanze.

Note

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 la pagina 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, quindi selezionare Avanti.
Nella scheda Dettagli modello selezionare Anonimo come livello di autorizzazione, quindi selezionare Crea.

Suggerimento

Se si mantiene il livello di autorizzazione come Funzione, è necessario configurare le registrazioni dps con la chiave API della funzione. Per altre informazioni, vedere Trigger HTTP di Funzioni di Azure.
Quando si apre la funzione HttpTrigger1 , selezionare Codice e test nel riquadro sinistro. Questa selezione consente di 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.
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 della 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 si crea un nuovo gruppo di registrazioni che usa il criterio di allocazione personalizzato. Per praticità, in questa esercitazione viene usata l'attestazione con chiave simmetrica per 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 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 in 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 Personalizzata (funzione di Azure). Selezionare Seleziona funzione di Azure, 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, aprirla nuovamente e annotare la 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.

Suggerimento

Quando si crea un gruppo di registrazione nel portale di Azure e si seleziona un criterio di allocazione personalizzato, il portale di Azure recupera e incorpora automaticamente la chiave di funzione per conto dell'utente. Se si crea una registrazione a livello di codice, è necessario fornire la chiave come parte del passaggio di creazione.

Derivare le chiavi univoche di dispositivo

I dispositivi non usano direttamente la chiave simmetrica primaria del gruppo di registrazione. Al contrario, la chiave primaria viene usata per derivare una chiave per ogni dispositivo. In questa sezione si creeranno due chiavi univoche per i dispositivi. Una chiave viene utilizzata per simulare un dispositivo toaster. L'altra chiave viene usata per simulare un dispositivo pompa di calore.

Per derivare la chiave del dispositivo, usare la chiave primaria del gruppo di registrazione annotata in precedenza per calcolare l'hash 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 Raggruppare le registrazioni con chiavi simmetriche dell'attestazione con chiave simmetrica.

Per l'esempio di questa esercitazione, usare i due ID di registrazione del dispositivo seguenti e calcolare una chiave di 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 comando iot dps enrollment-group compute-device-key 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 enrollment-group compute-device-key --key <ENROLLMENT_GROUP_KEY> --registration-id mainbuilding167-contoso-hpsd-088

Note

È anche possibile fornire l'ID del gruppo di registrazione anziché la chiave simmetrica al comando iot dps enrollment-group compute-device-key. 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 di dispositivo derivate con ogni ID di registrazione per eseguire l'attestazione con 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. Questo dispositivo simulato cerca 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 sezione Creare macchine virtuali Linux a livello di area di 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 SDK per dispositivi per C. Usare il tag trovato nel passaggio precedente come valore per il parametro -b, ad esempio: lts_03_2025.
```
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. Viene 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 si aggiorna un esempio di provisioning denominato prov_dev_client_sample che si trova in Azure IoT C SDK precedentemente configurato.

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 toaster sia riconosciuto e assegnato all'hub IoT usando i criteri di allocazione personalizzati.

Nel portale di Azure selezionare la scheda Panoramica per il servizio Device Provisioning e prendere nota del valore di Ambito ID.
In Visual Studio aprire il file di soluzione azure_iot_sdks.sln generato in precedenza tramite l'esecuzione di CMake. Il file di 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 variabile hsm_type sia impostata su SECURE_DEVICE_TYPE_SYMMETRIC_KEY come illustrato nell'esempio seguente:
```
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 personalizzato può essere usato per fornire altre informazioni alle funzioni di allocazione personalizzate. Questo payload 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 Usare i payload dei dispositivi nell'allocazione personalizzata.
```
// 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 toaster, individuare 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 chiave JC8F96eayuQwwz+PkE7IzjH2lIAjCUnAa61tDigBnSs= illustrato nel codice seguente 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.

Il seguente output è un esempio di dispositivo toaster simulato che si sta avviando correttamente e connettendo all'istanza del servizio di provisioning che i criteri di allocazione personalizzati assegneranno all'hub IoT dei toaster:

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 è un esempio di output di registrazione del codice della funzione di allocazione personalizzata in esecuzione nel dispositivo toaster. Si noti che per un dispositivo toaster è stato correttamente selezionare un hub. Si noti anche la proprietà payload che contiene il codice JSON personalizzato aggiunto al codice. Questo contenuto è disponibile per essere utilizzato dal tuo codice all'interno di 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 di nuovo la chiamata a prov_dev_set_symmetric_key_info() in prov_dev_client_sample.c con l'ID registrazione del dispositivo pompa di calore e la chiave di dispositivo derivata generata in precedenza. Il valore della chiave 6uejA9PfkQgmYylj8Zerp3kcbeVrGZ172YLa7VSnJzg= illustrato nel codice seguente 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.

Il seguente output è un esempio di dispositivo pompa di calore simulato che si sta avviando correttamente e connettendo all'istanza del servizio di provisioning che i criteri di allocazione personalizzati assegneranno all'hub IoT delle pompe di calore di Contoso:
```
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 si potrebbero ricevere. Usare questa tabella come supporto per la risoluzione dei problemi relativi ai criteri di allocazione personalizzati con le Funzioni di Azure.

Sceneggiatura	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' presente 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	La ripetizione dei tentativi di orchestrazione del DPS viene ritentata più volte. I criteri di ripetizione sono attualmente: - Numero di tentativi: 10 - Intervallo iniziale: 1 s - Incremento: 9 s	L'SDK ignora l'errore e invia un altro messaggio per ottenere lo stato nel tempo 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 intende continuare a usare le risorse create in questa esercitazione, è possibile mantenerle. Se non si prevede di continuare, seguire questa procedura per eliminare tutte le risorse create in questa esercitazione in modo da evitare inutili addebiti.

Questi passaggi 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 è stato creato l'hub IoT all'interno di un gruppo di risorse esistente che contiene le risorse da mantenere, 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

Comprendere i criteri di allocazione personalizzati con Azure IoT Hub Device Provisioning Service

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-11-24