Endpoint dell'hub IoT
hub IoT di Azure espone vari endpoint per supportare i dispositivi e i servizi che interagiscono con esso.
Nota
Alcune delle funzionalità indicate in questo articolo, come la messaggistica da cloud a dispositivo, i dispositivi gemelli e la gestione dei dispositivi, sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli Basic e Standard/Gratuito dell'hub IoT, vedere Scegliere il livello appropriato dell'hub IoT per la soluzione.
Nomi dell'hub IoT
È possibile trovare il nome host di un hub IoT nella portale di Azure, nel riquadro di lavoro Panoramica dell'hub IoT. Per impostazione predefinita, il nome DNS di un hub IoT è simile all'esempio seguente:
{your iot hub name}.azure-devices.net
hub IoT endpoint per lo sviluppo e la gestione
hub IoT di Azure è un servizio multi-tenant che ne espone le funzionalità a vari attori. Il diagramma seguente mostra i vari endpoint esposti dall'hub IoT.
L'elenco seguente offre una descrizione degli endpoint:
Provider di risorse: un'interfaccia di Azure Resource Manager . Questa interfaccia consente ai proprietari della sottoscrizione di Azure di creare ed eliminare gli hub IoT, nonché di aggiornare le proprietà degli hub IoT. hub IoT proprietà regolano i criteri di accesso condiviso a livello di hub, anziché il controllo di accesso a livello di dispositivo e le opzioni funzionali per la messaggistica da cloud a dispositivo e da dispositivo a cloud. Il provider di risorse dell'hub IoT consente anche di esportare le identità dei dispositivi.
Gestione delle identità dei dispositivi: un set di endpoint REST HTTPS per gestire le identità dei dispositivi (creare, recuperare, aggiornare ed eliminare). Le identità dei dispositivi vengono usate per l'autenticazione dei dispositivi e il controllo di accesso.
Gestione dei dispositivi gemelli: un set di endpoint REST HTTPS rivolto al servizio per eseguire query e aggiornare i dispositivi gemelli (aggiornare tag e proprietà).
Gestione dei processi: un set di endpoint REST HTTPS con connessione al servizio per eseguire query e gestire i processi.
Endpoint dispositivo: un set di endpoint per ogni dispositivo nel registro delle identità. Tranne dove indicato, questi endpoint vengono esposti usando i protocolli MQTT v3.1.1, HTTPS 1.1 e AMQP 1.0 . AMQP e MQTT sono disponibili anche su WebSocket sulla porta 443. Questi endpoint dispositivo includono:
Inviare messaggi da dispositivo a cloud
Ricezione di messaggi da cloud a dispositivo
Avviare i caricamenti di file
Recuperare e aggiornare le proprietà dei dispositivi gemelli (HTTPS non è supportato)
Ricevere richieste di metodi diretti (HTTPS non è supportato)
Endpoint di servizio: un set di endpoint per il back-end della soluzione per comunicare con i dispositivi. Con un'eccezione, questi endpoint vengono esposti solo usando i protocolli AMQP e AMQP su WebSocket. L'endpoint di chiamata al metodo diretto viene esposto tramite il protocollo HTTPS.
Ricevere messaggi da dispositivo a cloud: questo endpoint è l'endpoint predefinito descritto nei concetti di routing dei messaggi. e può essere usato da un servizio back-end per leggere i messaggi da dispositivo a cloud inviati dai dispositivi. Oltre a questo endpoint predefinito, è possibile creare endpoint personalizzati sull'hub IoT.
Inviare messaggi da cloud a dispositivo e ricevere riconoscimenti di recapito
Ricevere notifiche di caricamento file
Richiamare il metodo diretto
L'articolo hub IoT di Azure SDK descrive i vari modi per accedere a questi endpoint.
Tutti gli endpoint dell'hub IoT usano il protocollo TLS e non vengono mai esposti su canali non crittografati o non protetti.
Importante
Le funzionalità seguenti per i dispositivi che usano l'autenticazione dell'autorità di certificazione X.509 non sono ancora disponibili a livello generale e la modalità di anteprima deve essere abilitata:
- HTTPS, MQTT su WebSocket e AMQP su protocolli WebSocket.
- Caricamenti di file (tutti i protocolli).
Queste funzionalità sono disponibili a livello generale nei dispositivi che usano l'autenticazione con identificazione personale X.509. Per altre informazioni sull'autenticazione X.509 con l'hub IoT, vedere Certificati X.509 supportati.
Endpoint personalizzati per il routing dei messaggi
È possibile collegare i servizi di Azure esistenti nelle sottoscrizioni di Azure all'hub IoT per fungere da endpoint per il routing dei messaggi. Questi endpoint agiscono come endpoint di servizio e vengono usati come sink per il ruoting dei messaggi. I dispositivi non possono scrivere direttamente in questi endpoint. Per altre informazioni sul routing dei messaggi, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint diversi.
Attualmente, l'hub IoT supporta questi servizi di Azure come endpoint personalizzati:
- Contenitori di archiviazione
- Hub eventi
- Code del bus di servizio
- Argomenti del bus di servizio
- Cosmos DB
Per i limiti sugli endpoint per hub, vedere Quote e limitazioni.
Endpoint predefinito
È possibile usare l'integrazione standard di Hub eventi e gli SDK per ricevere i messaggi da dispositivo a cloud dall'endpoint predefinito (messaggi/eventi). Dopo aver creato una route, i dati smette di passare all'endpoint predefinito, a meno che non venga creata una route a tale endpoint. Anche se non viene creata alcuna route, è necessario abilitare una route di fallback per indirizzare i messaggi all'endpoint predefinito. Se si crea l'hub tramite il portale o l’interfaccia della riga di comando, il fallback è abilitato per impostazione predefinita.
Archiviazione di Azure come endpoint di routing
Esistono due servizi di archiviazione hub IoT possono instradare i messaggi agli account: Archiviazione BLOB di Azure e Azure Data Lake Storage Gen2 (ADLS Gen2). Entrambi usano i BLOB per l'archiviazione.
hub IoT supporta la scrittura di dati in Archiviazione di Azure nel formato Apache Avro e nel formato JSON. Il valore predefinito è AVRO. Per usare la codifica JSON, impostare la proprietà contentType su application/json e la proprietà contentEncoding su UTF-8 nelle proprietà del sistema dei messaggi. Entrambi questi valori non fanno distinzione tra maiuscole e minuscole. Se la codifica del contenuto non è impostata, hub IoT scrive i messaggi in formato con codifica base 64.
Il formato di codifica può essere impostato solo quando è configurato l'endpoint di archiviazione BLOB; non può essere modificato per un endpoint esistente.
hub IoT raggruppa i messaggi e scrive i dati nella risorsa di archiviazione ogni volta che il batch raggiunge una determinata dimensione o una determinata quantità di tempo è trascorsa. hub IoT per impostazione predefinita viene predefinito la convenzione di denominazione dei file seguente: {iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm}.
È possibile usare qualsiasi convenzione di denominazione dei file, ma è necessario usare tutti i token elencati. hub IoT scrive in un BLOB vuoto se non sono presenti dati da scrivere.
È consigliabile elencare i BLOB o i file e quindi eseguirne l'iterazione, per assicurarsi che tutti i BLOB o i file vengano letti senza fare ipotesi di partizione. L'intervallo di partizione potrebbe potenzialmente cambiare durante un failover avviato da Microsofto un failover manuale dell'hub IoT. È possibile usare l'API Elenca BLOB per enumerare l'elenco di BLOB o l'API List ADLS Gen2 per l'elenco dei file. Ad esempio:
public void ListBlobsInContainer(string containerName, string iothub)
{
var storageAccount = CloudStorageAccount.Parse(this.blobConnectionString);
var cloudBlobContainer = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
if (cloudBlobContainer.Exists())
{
var results = cloudBlobContainer.ListBlobs(prefix: $"{iothub}/");
foreach (IListBlobItem item in results)
{
Console.WriteLine(item.Uri);
}
}
}
Per creare un account di archiviazione compatibile con Azure Data Lake Gen2, creare un nuovo account di archiviazione V2 e selezionare Abilita spazio dei nomi gerarchico nella sezione Data Lake Storage Gen2 della scheda Avanzate , come illustrato nell'immagine seguente:
bus di servizio code e argomenti di bus di servizio come endpoint di routing
Nelle code e negli argomenti del bus di servizio usati come endpoint dell'hub IoT non devono essere abilitati le sessioni e il rilevamento duplicati. Se una di queste opzioni è abilitata, l'endpoint risulta non raggiungibile nel portale di Azure.
Hub eventi come endpoint di routing
Oltre all'endpoint compatibile con Hub eventi predefinito, è anche possibile indirizzare i dati a endpoint personalizzati di tipo Hub eventi.
Azure Cosmos DB come endpoint di routing
È possibile inviare dati direttamente ad Azure Cosmos DB da hub IoT. hub IoT supporta la scrittura in Cosmos DB in JSON (se specificato nel tipo di contenuto del messaggio) o come file binario con codifica base 64.
Per supportare scenari su larga scala, è possibile abilitare chiavi di partizione sintetiche per l'endpoint cosmos DB. Poiché Cosmos DB è un archivio dati con iperscalabilità, tutti i dati/documenti scritti in esso devono contenere un campo che rappresenta una partizione logica. Ogni partizione logica ha una dimensione massima di 20 GB. È possibile specificare il nome della proprietà della chiave di partizione in Nome chiave di partizione. Il nome della proprietà della chiave di partizione viene definito a livello di contenitore e non può essere modificato dopo l'impostazione.
È possibile configurare il valore della chiave di partizione sintetica specificando un modello nel modello chiave di partizione in base al volume di dati stimato. Negli scenari di produzione, ad esempio, è possibile che la partizione logica si avvicini al limite massimo di 20 GB entro un mese. In tal caso, è possibile definire una chiave di partizione sintetica come combinazione dell'ID dispositivo e del mese. Il valore della chiave di partizione generato viene aggiunto automaticamente alla proprietà della chiave di partizione per ogni nuovo record Cosmos DB, assicurando che le partizioni logiche vengano create ogni mese per ogni dispositivo.
Attenzione
Se si usa l'identità gestita assegnata dal sistema per l'autenticazione in Cosmos DB, è necessario usare l'interfaccia della riga di comando di Azure o Azure PowerShell per assegnare la definizione del ruolo predefinito collaboratore ai dati di Cosmos DB all'identità. L'assegnazione di ruolo per Cosmos DB non è attualmente supportata dal portale di Azure. Per altre informazioni sui vari ruoli, vedere Configurare l'accesso basato sui ruoli per Azure Cosmos DB. Per informazioni sull'assegnazione dei ruoli tramite l'interfaccia della riga di comando, vedere Gestire le risorse del ruolo SQL di Azure Cosmos DB.
Integrità endpoint
È possibile usare l'API REST Get Endpoint Health (Ottieni integrità endpoint) per ottenere lo stato di integrità degli endpoint. È consigliabile usare le metriche di routing hub IoT correlate alla latenza dei messaggi di routing per identificare ed eseguire il debug degli errori quando l'integrità dell'endpoint è inattiva o non integra, come si prevede che la latenza sia superiore quando l'endpoint si trova in uno di questi stati. Per altre informazioni sull'uso delle metriche di hub IoT, vedere Monitorare hub IoT.
| Stato integrità | Descrizione |
|---|---|
| healthy | L'endpoint accetta i messaggi come previsto. |
| non integro | L'endpoint non accetta messaggi e hub IoT sta ritentando di inviare messaggi a questo endpoint. |
| Sconosciuto | hub IoT non ha tentato di recapitare messaggi a questo endpoint. |
| degradato | L'endpoint accetta messaggi più lenti del previsto o viene ripristinato da uno stato non integro. |
| morto | hub IoT non recapita più messaggi a questo endpoint. Tentativi di invio di messaggi a questo endpoint non riuscito. |
Passaggi successivi
Altre informazioni su questi argomenti: