Condividi tramite

Creare ed eliminare route ed endpoint usando Azure Resource Manager

  • Articolo

Questo articolo illustra come esportare il modello di hub IoT di Azure, aggiungere una route all'hub IoT e quindi ridistribuire il modello nell'hub IoT usando l'interfaccia della riga di comando di Azure o Azure PowerShell. Usare un modello di Azure Resource Manager per creare route ed endpoint. hub IoT supporta i servizi di Azure seguenti come endpoint:

  • Contenitori di archiviazione
  • Hub eventi di
  • Code del bus di servizio
  • Argomenti del bus di servizio
  • Cosmos DB

I modelli di Azure Resource Manager sono utili quando si vogliono definire le risorse usando un file JSON. Ogni risorsa di Azure ha un modello che definisce i componenti usati in tale risorsa. È possibile esportare tutti i modelli di risorse di Azure.

Importante

Quando si usa un modello di Resource Manager per distribuire una risorsa, il modello sostituisce qualsiasi risorsa esistente del tipo che si sta distribuendo.

Quando si crea un nuovo hub IoT, la sovrascrittura di una risorsa distribuita esistente non è un problema. Per creare un nuovo hub IoT, è possibile usare un modello di base con le proprietà necessarie anziché esportare un modello esistente da un hub IoT già distribuito.

Tuttavia, se si aggiunge una route a un hub IoT esistente, usare un modello esportato dall'hub IoT per assicurarsi che tutte le risorse e le proprietà esistenti rimangano connesse dopo la distribuzione del modello aggiornato. Le risorse già distribuite non verranno sostituite. Ad esempio, un modello di Resource Manager esportato distribuito in precedenza potrebbe contenere informazioni di archiviazione per l'hub IoT se è stato connesso all'archiviazione.

Per altre informazioni sul funzionamento del routing nell'hub IoT, vedere Usare il routing dei messaggi dell'hub IoT per inviare messaggi da dispositivo a cloud a endpoint differenti. Per eseguire la procedura per configurare una route che invia messaggi all'archiviazione e quindi eseguire il test su un dispositivo simulato, vedere Esercitazione: Inviare dati del dispositivo a Archiviazione di Azure usando hub IoT routing dei messaggi.

Prerequisiti

Esaminare i prerequisiti per questo articolo in base al tipo di endpoint a cui si vuole indirizzare i messaggi.

Modello di Azure Resource Manager

Questo articolo usa un modello di Azure Resource Manager nel portale di Azure per usare hub IoT e altri servizi di Azure. Per altre informazioni su come usare i modelli di Resource Manager, vedere Che cosa sono i modelli di Azure Resource Manager?

Creare una route

Nell'hub IoT è possibile creare una route per inviare messaggi o acquisire eventi. Ogni route ha un'origine dati e un endpoint. L'origine dati è la posizione in cui hanno origine i messaggi o i log eventi. L'endpoint è la posizione in cui finiscono i messaggi o i log eventi. È possibile scegliere le posizioni per l'origine dati e l'endpoint quando si crea una nuova route nell'hub IoT. Successivamente, è possibile usare le query di routing per filtrare i messaggi o gli eventi prima del passaggio agli all'endpoint.

È possibile usare un hub eventi, una coda o un argomento bus di servizio o un account di archiviazione di Azure come endpoint per la route dell'hub IoT. Il servizio usato per creare l'endpoint deve prima esistere nell'account Azure.

Esportare il modello di Resource Manager dell'hub IoT

Prima di tutto, esportare un modello di Resource Manager dall'hub IoT. Esportando il modello dall'hub IoT, è possibile aggiungere risorse endpoint e route e ridistribuire senza perdere l'impostazione esistente.

  1. Nel portale di Azure passare all'hub IoT. Nel menu delle risorse in Automazione selezionare Esporta modello.

    Screenshot che mostra il percorso dell'opzione Esporta modello nel menu di una risorsa hub IoT.

  2. Nella scheda Modello in Esporta modello completare questa procedura:

    1. Visualizzare il file JSON generato per l'hub IoT.

    2. Deselezionare la casella di controllo Includi parametri .

    3. Selezionare Scarica per scaricare una copia locale del file JSON.

    Screenshot che mostra il percorso del pulsante Scarica nel riquadro Esporta modello.

    Il modello include diversi segnaposto che è possibile usare per aggiungere funzionalità o servizi all'hub IoT. Per questo articolo, aggiungere valori solo alle proprietà in o annidate in routing.

Aggiungere un endpoint al modello

Ogni route punta a un endpoint, in cui i messaggi o i log eventi finiscono. Creare un endpoint nell'hub IoT a cui può fare riferimento la route. È possibile usare un hub eventi, una coda o un argomento bus di servizio, un account di archiviazione di Azure o un contenitore Cosmos DB come endpoint per la route dell'hub IoT. Il servizio usato per creare l'endpoint deve prima esistere nell'account Azure.

L'hub IoT necessita delle autorizzazioni di accesso per qualsiasi risorsa endpoint a cui invia messaggi o log. È possibile fornire l'accesso usando identità gestite e MICROSOFT Entra ID o usando stringa di connessione. Microsoft consiglia di eseguire l'autenticazione con Entra ID come opzione più sicura.

Aggiungere un endpoint di Hub eventi al modello di Resource Manager. Per altre informazioni, vedere RoutingEventHubProperties del modello di Azure Resource Manager.

  1. Nel file JSON trovare la "endpoints": [] proprietà annidata in "routing".

  2. Sostituire la "endpoints": [] riga con il codice JSON seguente:

    "endpoints": {
    "serviceBusQueues": [],
    "serviceBusTopics": [],
    "eventHubs": [
        {
            "endpointUri": "",
            "entityPath": "",
            "authenticationType": "identityBased",
            "identity": {
                "userAssignedIdentity": ""
            },
            "name": "",
            "id": "",
            "subscriptionId": "",
            "resourceGroup": ""
        }
    ],
    "storageContainers": [],
    "cosmosDBSqlContainers": []
},

  3. Aggiornare il codice JSON con le informazioni seguenti sulla risorsa di Hub eventi:

    Proprietà valore
    endpointUri (Se il tipo di autenticazione è identityBased; in caso contrario, eliminare. Nome host dello spazio dei nomi di Hub eventi nel formato sb://<eventhubs_namespace_name>.servicebus.windows.net
    entityPath (Se il tipo di autenticazione è identityBased; in caso contrario, eliminare. Nome dell'hub eventi.
    authenticationType identityBased o keyBased. Microsoft consiglia l'autenticazione basata sull'identità come opzione più sicura.
    identity Se il tipo di autenticazione è identityBased.) È possibile usare un'identità gestita assegnata dall'utente o un'identità gestita assegnata dal sistema se l'hub IoT identità gestita assegnata dal sistema è abilitata.

    Per l'utente assegnato: ID esterno dell'identità gestita con autorizzazioni di accesso all'hub eventi nel formato /subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity_name>.

    Per assegnata dal sistema: lasciare il parametro Identity come elenco vuoto. Ad esempio, "identity": {},
    connectionString Se il tipo di autenticazione è keyBased.) Il stringa di connessione primario da uno dei criteri di accesso condiviso dell'hub eventi nel formato <connection_string>;EntityPath=<event_hub_name>. È possibile recuperare il valore stringa di connessione dal portale di Azure, quindi aggiungere il percorso dell'entità.
    name Specificare un valore univoco per assegnare un nome all'endpoint.
    id Lasciare una stringa vuota. Il servizio di Azure fornisce un valore quando si crea l'endpoint.
    subscriptionId ID della sottoscrizione che contiene l'hub eventi.
    resourceGroup Nome del gruppo di risorse che contiene l'hub eventi.

    Suggerimento

    Per la gestione dei segreti, è possibile creare un file di parametri o Usare Azure Key Vault per passare i valori dei parametri protetti durante la distribuzione.

Aggiungere una route al modello

Aggiungere una definizione di route al modello di Resource Manager. Per altre informazioni, vedere RouteProperties del modello di Azure Resource Manager.

  1. Nel file JSON trovare la "routes": [] proprietà annidata in "routing"e aggiungere una nuova route.

    Attenzione

    Se si sostituiscono valori esistenti per "routes" con i valori di route usati negli esempi di codice seguenti, le route esistenti vengono rimosse durante la distribuzione. Per mantenere le route esistenti, aggiungere il nuovo oggetto route all'elenco "routes" .

    "routes": [
    {
        "name": "",
        "source": "DeviceConnectionStateEvents",
        "condition": "true",
        "endpointNames": [
            ""
        ],
        "isEnabled": true
    }
],

  2. Aggiornare il codice JSON con le informazioni seguenti sulla risorsa Cosmos DB:

    Proprietà valore
    name Specificare un valore univoco per assegnare un nome alla route.
    source Selezionare l'origine del messaggio o dei log eventi da instradare all'endpoint. Per un elenco delle opzioni di origine, vedere az iot hub route.
    condizione Query per filtrare i dati di origine. Se non è necessaria alcuna condizione, dire true. Per altre informazioni, vedere Sintassi delle query di routing dei messaggi dell'hub IoT.
    endpointNames Nome dell'endpoint esistente in cui verranno indirizzati questi dati. Attualmente è consentito un solo endpoint.
    isEnabled Impostare su true per abilitare la route o false disabilitare la route.

  3. Salvare il file JSON.

Distribuire il modello di Resource Manager

Dopo aver aggiunto il nuovo endpoint e la route al modello di Resource Manager, è ora possibile distribuire di nuovo il file JSON nell'hub IoT.

Distribuzione locale

az deployment group create \
  --name my-iot-hub-template \
  --resource-group my-resource-group \
  --template-file "my\path\to\template.json"

Distribuzione di Azure Cloud Shell

Poiché Azure Cloud Shell viene eseguito in un Web browser, è possibile caricare il file modello prima di eseguire il comando di distribuzione. Dopo aver caricato il file, è necessario solo il nome del file modello (anziché l'intero percorso del file) da usare nel template-file parametro .

Screenshot che mostra il percorso del pulsante in Azure Cloud Shell per caricare un file. 

az deployment group create \
  --name my-iot-hub-template \
  --resource-group my-resource-group \
  --template-file "template.json"

Nota

Se la distribuzione non viene eseguita, utilizzare l'opzione -verbose per ottenere informazioni sulle risorse create. Usare l'opzione -debug per ottenere ulteriori informazioni su come eseguire il debug.

Verificare la distribuzione

Per verificare che il modello sia stato distribuito correttamente in Azure, nella portale di Azure passare alla risorsa del gruppo di risorse. Nel menu delle risorse in Impostazioni selezionare Distribuzioni per visualizzare il modello in un elenco delle distribuzioni.

Screenshot che mostra un elenco di distribuzioni per una risorsa nella portale di Azure, con un modello di test evidenziato.

Per visualizzare la nuova route nel portale di Azure, passare alla risorsa hub IoT. Nel riquadro Routing messaggi, nella scheda Route, verificare che la route sia elencata.

Passaggi successivi

In questo articolo di istruzioni si è appreso come creare una route e un endpoint per Hub eventi, code e argomenti del Bus di servizio e Archiviazione di Azure.

Per altre informazioni sul routing dei messaggi, vedere Esercitazione: Inviare dati dei dispositivi ad Archiviazione di Azure usando il routing dei messaggi dell'hub IoT. Nell'esercitazione viene creata una route di archiviazione che viene testata con un dispositivo nell'hub IoT.