Configurare gli upload dei file nell'hub IoT tramite l'interfaccia della riga di comando di Azure

  • Articolo

Questo articolo illustra come configurare i caricamenti di file nell'hub IoT usando l'interfaccia della riga di comando di Azure.

Per usare la funzionalità di caricamento file nell'hub IoT, è prima necessario associare un account di archiviazione di Azure e un contenitore BLOB all'hub IoT. L'hub IoT genera automaticamente URI di firma di accesso condiviso con autorizzazioni di scrittura per questo contenitore BLOB che possono essere usati dai dispositivi durante il caricamento di file. Oltre all'account di archiviazione e al contenitore BLOB, è possibile impostare la durata (TTL) per l'URI di firma di accesso condiviso e il tipo di autenticazione usato dall'hub IoT con Archiviazione di Azure. È anche possibile configurare le impostazioni per le notifiche di caricamento file facoltative che l'hub IoT può recapitare ai servizi back-end.

Prerequisiti

  • Un account Azure attivo. Se non si ha un account, è possibile crearne uno gratuito in pochi minuti.

  • Un hub IoT nella sottoscrizione di Azure. Se non si ha ancora un hub, è possibile seguire la procedura descritta in Creare un hub IoT.

  • Un account di archiviazione di Azure. Se non si ha un account di archiviazione di Azure, è possibile usare l'interfaccia della riga di comando di Azure per crearne uno. Per altre informazioni, vedere Creare un account di archiviazione.

Nota

Questo articolo usa la versione più recente dell'estensione Azure IoT, denominata azure-iot. La versione legacy viene chiamata azure-cli-iot-ext. Deve essere installata solo una versione alla volta. È possibile usare il comando az extension list per convalidare le estensioni attualmente installate.

Usare az extension remove --name azure-cli-iot-ext per rimuovere la versione legacy dell'estensione.

Usare az extension add --name azure-iot per aggiungere la nuova versione dell'estensione.

Per visualizzare le estensioni installate, usare az extension list.

Accedere all'account Azure e impostarlo

Accedere al proprio account Azure e selezionare la sottoscrizione. Se si usa Azure Cloud Shell, si dovrebbe avere già eseguito l'accesso. Tuttavia, potrebbe essere comunque necessario selezionare la sottoscrizione di Azure se si hanno più sottoscrizioni.

  1. Al prompt dei comandi eseguire il comando per l'accesso:

    az login

    Seguire le istruzioni per l'autenticazione tramite il codice e accedere all'account Azure con un Web browser.

  2. Se si usano più sottoscrizioni di Azure, effettuando l'accesso ad Azure è possibile accedere a tutti gli account Azure associati alle credenziali. Usare il seguente comando per elencare gli account Azure che è possibile usare:

    az account list

    Usare il comando seguente per selezionare la sottoscrizione che si vuole usare per eseguire i comandi per creare l'hub IoT. È possibile usare il nome o l'ID della sottoscrizione dall'output del comando precedente:

    az account set --subscription {your subscription name or id}

Recuperare i dettagli dell'account di archiviazione

I passaggi seguenti presuppongono che l'account di archiviazione sia stato creato tramite il modello di distribuzione di Resource Manager e non tramite quello Classico.

Per configurare i caricamenti dei file dai propri dispositivi, è necessario disporre della stringa di connessione di un account di archiviazione di Azure. L'account di archiviazione deve trovarsi nella stessa sottoscrizione dell'hub IoT. È inoltre necessario il nome del contenitore BLOB nell'account di archiviazione. Usare il comando seguente per recuperare le chiavi dell'account di archiviazione:

az storage account show-connection-string --name {your storage account name} \
  --resource-group {your storage account resource group}

La stringa di connessione sarà simile all'output seguente:

{
  "connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName={your storage account name};AccountKey={your storage account key}"
}

Annotare il valore connectionString. sarà necessario nei passaggi successivi.

Per i caricamenti dei file, è possibile usare un contenitore BLOB esistente oppure crearne uno nuovo:

  • Per elencare i contenitori BLOB esistenti nell'account di archiviazione, usare i comandi seguenti:

    az storage container list --connection-string "{your storage account connection string}"

  • Per creare un contenitore BLOB nell'account di archiviazione, usare i comandi seguenti:

    az storage container create --name {container name} \
  --connection-string "{your storage account connection string}"

Configurare l'hub IoT

È ora possibile configurare l'hub IoT per abilitare il caricamento dei file nell'hub IoT usando i dettagli dell'account di archiviazione.

La configurazione richiede i valori seguenti:

  • Contenitore di archiviazione: un contenitore BLOB in un account di archiviazione di Azure nella sottoscrizione corrente da associare all'hub IoT. Le informazioni necessarie sull'account di archiviazione sono state recuperate nella sezione precedente. L'hub IoT genera automaticamente URI di firma di accesso condiviso con autorizzazioni di scrittura per questo contenitore BLOB che possono essere usati dai dispositivi durante il caricamento di file.

  • Receive notifications for uploaded files (Ricezione di notifiche per i file caricati): abilitare o disabilitare le notifiche di caricamento del file.

  • SAS TTL(TTL di firma di accesso condiviso): questa impostazione indica la durata degli URI di firma di accesso condiviso restituiti dal dispositivo tramite l’hub IoT. Il valore è un'ora per impostazione predefinita.

  • Impostazioni di notifica file - Durata (TTL) predefinita: durata (TTL) di una notifica di caricamento di file prima della scadenza. Il valore è un giorno per impostazione predefinita.

  • File notification maximum delivery count(Numero massimo di recapiti per le notifiche dei file): numero di tentativi che verranno eseguiti dall'hub IoT per distribuire una notifica di caricamento del file. Il valore è 10 per impostazione predefinita.

  • Durata blocco delle notifiche file: durata del blocco per la coda di notifica file. Impostata su 60 secondi per impostazione predefinita.

  • Tipo di autenticazione: tipo di autenticazione che verrà usato dall'hub IoT con Archiviazione di Azure. Questa impostazione determina il modo in cui l'hub IoT esegue l'autenticazione e l'autorizzazione con Archiviazione di Azure. Il valore predefinito è l'autenticazione basata su chiave. È tuttavia possibile usare anche le identità gestite assegnate dal sistema e assegnate dall'utente. Le identità gestite offrono ai servizi di Azure un'identità gestita automaticamente in Microsoft Entra ID in modo sicuro. Per informazioni su come configurare le identità gestite nell'hub IoT e nell'account di archiviazione di Azure, vedere Supporto dell'hub IoT per le identità gestite. Dopo la configurazione, è possibile impostare una delle identità gestite da usare per l'autenticazione con Archiviazione di Azure.

    Nota

    L'impostazione del tipo di autenticazione configura la modalità di autenticazione dell'hub IoT con l'account di archiviazione di Azure. I dispositivi eseguono sempre l'autenticazione con Archiviazione di Azure usando l'URI di firma di accesso condiviso ottenuto dall'hub IoT.

I comandi seguenti illustrano come configurare le impostazioni di caricamento file nell'hub IoT. Questi comandi vengono visualizzati separatamente per maggiore chiarezza, ma in genere si esegue un singolo comando con tutti i parametri necessari per lo scenario. Includere le virgolette nella posizione in cui vengono visualizzate nella riga di comando. Non includere le parentesi graffe. Altre informazioni su ogni parametro sono disponibili nella documentazione dell'interfaccia della riga di comando di Azure per il comando az iot hub update.

Il comando seguente configura l'account di archiviazione e il contenitore BLOB.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-connectionstring "{your storage account connection string}" \
    --fileupload-storage-container-name "{your container name}"

Il comando seguente imposta la durata (TTL) dell'URI di firma di accesso condiviso sul valore predefinito (un'ora).

az iot hub update --name {your iot hub name} \
    --fileupload-sas-ttl 1

Il comando seguente abilita le notifiche dei file e imposta le proprietà di notifica dei file sui valori predefiniti. La durata della notifica di caricamento dei file è impostata su un'ora e la durata del blocco è impostata su 60 secondi.

az iot hub update --name {your iot hub name} \
    --fileupload-notifications true  \
    --fileupload-notification-max-delivery-count 10 \
    --fileupload-notification-ttl 1 \
    --fileupload-notification-lock-duration 60

Il comando seguente configura l'autenticazione basata su chiave:

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type keyBased

Il comando seguente configura l'autenticazione usando l'identità gestita assegnata dal sistema dell'hub IoT. Prima di poter eseguire questo comando, è necessario abilitare l'identità gestita assegnata dal sistema per l'hub IoT e concederle il ruolo di controllo degli accessi in base al ruolo corretto nell'account di archiviazione di Azure. Per informazioni sulla procedura, vedere Supporto dell'hub IoT per le identità gestite.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity [system]

I comandi seguenti recuperano le identità gestite assegnate dall'utente configurate nell'hub IoT e configurano l'autenticazione con una di esse. Prima di poter usare un'identità gestita assegnata dall'utente per l'autenticazione, è necessario configurarla nell'hub IoT e concederle un ruolo di controllo degli accessi in base al ruolo appropriato nell'account di archiviazione di Azure. Per informazioni dettagliate e per la procedura, vedere Supporto dell'hub IoT per le identità gestite.

Per eseguire una query sulle identità gestite assegnate dall'utente nell'hub IoT, usare il comando az iot hub identity show.

az iot hub identity show --name {your iot hub name} --query userAssignedIdentities

Il comando restituisce una raccolta delle identità gestite assegnate dall'utente configurate nell'hub IoT. L'output seguente mostra una raccolta che contiene una singola identità gestita assegnata dall'utente.

{
  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}": 
  {
    "clientId": "<client ID GUID>",
    "principalId": "<principal ID GUID>"
  }
}

Il comando seguente configura l'autenticazione per l'uso dell'identità assegnata dall'utente precedente.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}"

È possibile verificare le impostazioni nell'hub IoT usando il comando seguente:

az iot hub show --name {your iot hub name}

Per verificare solo le impostazioni di caricamento file, usare il comando seguente:

az iot hub show --name {your iot hub name}
    --query '[properties.storageEndpoints, properties.enableFileUploadNotifications, properties.messagingEndpoints.fileNotifications]'

Per la maggior parte delle situazioni, la soluzione più facile prevede l'uso dei parametri denominati nei comandi dell'interfaccia della riga di comando di Azure. È tuttavia possibile configurare le impostazioni di caricamento dei file con il parametro --set. I comandi seguenti consentono di comprendere come.

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.connectionString="{your storage account connection string}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.containerName="{your storage container name}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.sasTtlAsIso8601=PT1H0M0S

az iot hub update --name {your iot hub name} \
  --set properties.enableFileUploadNotifications=true

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.maxDeliveryCount=10

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.ttlAsIso8601=PT1H0M0S

Passaggi successivi