Risoluzione dei problemi in Azure IoT Central

Articolo
02/07/2024

Questo articolo include indicazioni sulla risoluzione dei problemi di connettività dei dispositivi e problemi di configurazione dell'esportazione dei dati nelle applicazioni IoT Central.

Problemi di connettività del dispositivo

Questa sezione consente di determinare se i dati raggiungono IoT Central.

Se non è già stato fatto, installare lo strumento e azure-iot l'estensioneaz cli.

Per informazioni su come installare az cli, vedere Installare l'interfaccia della riga di comando di Azure.

Per installare l'estensione azure-iot , eseguire il comando seguente:

az extension add --name azure-iot

Nota

Potrebbe essere richiesto di installare la libreria la uamqp prima volta che si esegue un comando di estensione.

Dopo aver installato l'estensione, avviare il azure-iot dispositivo per verificare se i messaggi inviati stanno facendo il loro modo a IoT Central.

Usare i comandi seguenti per accedere alla sottoscrizione in cui si dispone dell'applicazione IoT Central:

az login
az account set --subscription <your-subscription-id>

Per monitorare i dati di telemetria inviati dal dispositivo, usare il comando seguente:

az iot central diagnostics monitor-events --app-id <iot-central-app-id> --device-id <device-name>

Se il dispositivo è connesso correttamente a IoT Central, viene visualizzato un output simile all'esempio seguente:

Monitoring telemetry.
Filtering on device: device-001
{
    "event": {
        "origin": "device-001",
        "module": "",
        "interface": "",
        "component": "",
        "payload": {
            "temp": 65.57910343679293,
            "humid": 36.16224660107426
        }
    }
}

Per monitorare gli aggiornamenti delle proprietà che il dispositivo sta scambiando con IoT Central, usare il comando di anteprima seguente:

az iot central diagnostics monitor-properties --app-id <iot-central-app-id> --device-id <device-name>

Se il dispositivo invia correttamente gli aggiornamenti delle proprietà, viene visualizzato un output simile all'esempio seguente:

Changes in reported properties:
version : 32
{'state': 'true', 'name': {'value': {'value': 'Contoso'}, 'status': 'completed', 'desiredVersion': 7, 'ad': 'completed', 'av': 7, 'ac
': 200}, 'brightness': {'value': {'value': 2}, 'status': 'completed', 'desiredVersion': 7, 'ad': 'completed', 'av': 7, 'ac': 200}, 'p
rocessorArchitecture': 'ARM', 'swVersion': '1.0.0'}

Se vengono visualizzati dati nel terminale, i dati vengono visualizzati fino all'applicazione IoT Central.

Se non vengono visualizzati dati dopo alcuni minuti, provare a premere il Enter tasto o return sulla tastiera, nel caso in cui l'output sia bloccato.

Se non vengono ancora visualizzati dati nel terminale, è probabile che il dispositivo presenti problemi di connettività di rete o che non invii correttamente i dati a IoT Central.

Controllare lo stato del provisioning del dispositivo

Se i dati non vengono visualizzati nel monitoraggio dell'interfaccia della riga di comando, controllare lo stato del provisioning del dispositivo eseguendo il comando seguente:

az iot central device registration-info --app-id <iot-central-app-id> --device-id <device-name>

L'output seguente mostra un esempio di dispositivo bloccato per la connessione:

{
  "@device_id": "v22upeoqx6",
  "device_registration_info": {
    "device_status": "blocked",
    "display_name": "Environmental Sensor - v22upeoqx6",
    "id": "v22upeoqx6",
    "instance_of": "urn:krhsi_k0u:modelDefinition:w53jukkazs",
    "simulated": false
  },
  "dps_state": {
    "error": "Device is blocked from connecting to IoT Central application. Unblock the device in IoT Central and retry. Learn more:
https://aka.ms/iotcentral-docs-dps-SAS",
    "status": null
  }
}

Stato del provisioning del dispositivo	Descrizione	Possibile mitigazione
Sottoposto a provisioning	Nessun problema immediatamente riconoscibile.	N/D
Registrato	Il dispositivo non è ancora connesso a IoT Central.	Controllare i log dei dispositivi per verificare la presenza di problemi di connettività.
Bloccati	Il dispositivo non è connesso a IoT Central.	Il dispositivo è bloccato dalla connessione all'applicazione IoT Central. Sbloccare il dispositivo in IoT Central e riprovare. Per altre informazioni, vedere Valori di stato del dispositivo.
Non approvato	Il dispositivo non è approvato.	Il dispositivo non è approvato per la connessione all'applicazione IoT Central. Approvare il dispositivo in IoT Central e riprovare. Per altre informazioni, vedere Valori di stato del dispositivo
Non assegnate	Il dispositivo non è assegnato a un modello di dispositivo.	Assegnare il dispositivo a un modello di dispositivo in modo che IoT Central sappia come analizzare i dati.

Altre informazioni sui valori di stato del dispositivo nei valori di stato dell'interfaccia utente e del dispositivo nell'API REST.

Codici errore

Se non riesci ancora a diagnosticare il motivo per cui i dati non vengono visualizzati in monitor-events, il passaggio successivo consiste nel cercare i codici di errore segnalati dal dispositivo.

Avviare una sessione di debug nel dispositivo o raccogliere i log dal dispositivo. Verificare la presenza di eventuali codici di errore segnalati dal dispositivo.

Le tabelle seguenti illustrano i codici di errore comuni e le possibili azioni da attenuare.

Se vengono visualizzati problemi relativi al flusso di autenticazione:

Codice di errore	Descrizione	Possibile mitigazione
400	Il corpo della richiesta non è valido. Ad esempio, non può essere analizzato o l'oggetto non può essere convalidato.	Assicurarsi di inviare il corpo della richiesta corretto come parte del flusso di attestazione o di usare un SDK per dispositivi.
401	Il token di autorizzazione non può essere convalidato. Ad esempio, è scaduto o non si applica all'URI della richiesta. Questo codice di errore viene restituito anche ai dispositivi come parte del flusso di attestazione TPM.	Assicurarsi che il dispositivo disponga delle credenziali corrette.
404	L'istanza del servizio Device Provisioning o una risorsa, ad esempio una registrazione, non esiste.	Inviare un ticket con il supporto tecnico clienti.
412	L'oggetto `ETag` nella richiesta non corrisponde all'oggetto `ETag` della risorsa esistente, in base RFC7232.	Inviare un ticket con il supporto tecnico clienti.
429	Il servizio è operazioni di limitazione. Per limiti specifici del servizio, vedere hub IoT limiti del servizio Device Provisioning.	Ridurre la frequenza dei messaggi, suddividere le responsabilità tra più dispositivi.
500	Si è verificato un errore interno.	Inviare un ticket con il supporto tecnico per verificare se possono aiutarti ulteriormente.

Codici di errore di autorizzazione dettagliati

Error	Codice di errore secondario	Note
401 - Non autorizzato	401002	Il dispositivo usa credenziali non valide o scadute. Dps segnala questo errore.
401 - Non autorizzato	400209	Il dispositivo è in attesa dell'approvazione da parte di un operatore o l'operatore l'ha bloccata.
401 IoTHubUnauthorized		Il dispositivo usa un token di sicurezza scaduto. hub IoT segnala questo errore.
401 IoTHubUnauthorized	DEVICE_DISABLED	Il dispositivo è disabilitato in questo hub IoT ed è stato spostato in un altro hub IoT. Eseguire di nuovo il provisioning del dispositivo.
401 IoTHubUnauthorized	DEVICE_BLOCKED	Un operatore ha bloccato questo dispositivo.

Codici di errore di caricamento file

Di seguito è riportato un elenco di codici di errore comuni visualizzati quando un dispositivo tenta di caricare un file nel cloud. Tenere presente che prima che il dispositivo possa caricare un file, è necessario configurare i caricamenti di file del dispositivo nell'applicazione.

Codice di errore	Descrizione	Possibile mitigazione
403006	È stato superato il numero di operazioni di caricamento di file simultanee. Ogni client del dispositivo è limitato a 10 caricamenti simultanei di file.	Assicurarsi che il dispositivo notifica tempestivamente a IoT Central che l'operazione di caricamento del file è stata completata. In caso contrario, provare a ridurre il timeout della richiesta.

Problemi relativi ai dati non modellati

Dopo aver stabilito che il dispositivo invia dati a IoT Central, il passaggio successivo consiste nell'assicurarsi che il dispositivo invii dati in un formato valido.

Per rilevare le categorie in cui si trova il problema, eseguire il comando dell'interfaccia della riga di comando di Azure più appropriato per lo scenario:

Per convalidare i dati di telemetria, usare il comando di anteprima:

az iot central diagnostics validate-messages --app-id <iot-central-app-id> --device-id <device-name>

Per convalidare gli aggiornamenti delle proprietà, usare il comando di anteprima:

az iot central diagnostics validate-properties --app-id <iot-central-app-id> --device-id <device-name>

Potrebbe essere richiesto di installare la uamqp libreria la prima volta che si esegue un validate comando.

I tre tipi comuni di problema che causano la mancata visualizzazione dei dati del dispositivo in IoT Central sono:

Modello di dispositivo per la mancata corrispondenza dei dati del dispositivo.
I dati non sono JSON validi.
Le versioni precedenti di IoT Edge causano la visualizzazione non corretta dei dati di telemetria dai componenti come dati non modellati.

Mancata corrispondenza tra il modello di dispositivo e i dati del dispositivo

Un dispositivo deve usare lo stesso nome e la stessa combinazione di maiuscole e minuscole usate nel modello di dispositivo per qualsiasi nome di campo di telemetria nel payload inviato. L'output seguente mostra un messaggio di avviso di esempio in cui il dispositivo invia un valore di telemetria denominato Temperature, quando deve essere temperature:

Validating telemetry.
Filtering on device: sample-device-01.
Exiting after 300 second(s), or 10 message(s) have been parsed (whichever happens first).
[WARNING] [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg] Device is sending data that has not been defined in the device template. Following capabilities have NOT been defined in the device template '['Temperature']'. Following capabilities have been defined in the device template (grouped by components) '{'thermostat1': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport'], 'thermostat2': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport'], 'deviceInformation': ['manufacturer', 'model', 'swVersion', 'osName', 'processorArchitecture', 'processorManufacturer', 'totalStorage', 'totalMemory']}'.

Un dispositivo deve usare lo stesso nome e la stessa combinazione di maiuscole e minuscole usate nel modello di dispositivo per qualsiasi nome di proprietà nel payload inviato. L'output seguente mostra un messaggio di avviso di esempio in cui la proprietà osVersion non è definita nel modello di dispositivo:

Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus
[WARNING]  [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg] Device is sending data that has not been defined in the device template. Following capabilities have NOT been defined in the device template '['osVersion']'. Following capabilities have been defined in the device template (grouped by components) '{'thermostat1': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport', 'rundiagnostics'], 'thermostat2': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport', 'rundiagnostics'], 'deviceInformation': ['manufacturer', 'model', 'swVersion', 'osName', 'processorArchitecture', 'processorManufacturer', 'totalStorage', 'totalMemory']}'.

Un dispositivo deve usare i tipi di dati definiti nel modello di dispositivo per i valori di telemetria o proprietà. Ad esempio, viene visualizzata una mancata corrispondenza dello schema se il tipo definito nel modello di dispositivo è booleano, ma il dispositivo invia una stringa. L'output seguente mostra un messaggio di errore di esempio in cui il dispositivo usa un valore stringa per una proprietà definita come double:

Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus
Validating telemetry.
Filtering on device: sample-device-01.
Exiting after 300 second(s), or 10 message(s) have been parsed (whichever happens first).
[ERROR] [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg]  Datatype of telemetry field 'temperature' does not match the datatype double. Data sent by the device : curr_temp. For more information, see: https://aka.ms/iotcentral-payloads

I comandi di convalida segnalano anche un errore se lo stesso nome di telemetria è definito in più interfacce, ma il dispositivo non è Plug and Play IoT conforme.

Se si preferisce usare un'interfaccia utente grafica, usare la visualizzazione dati non elaborati di IoT Central per verificare se qualcosa non è modellato.

Dopo aver rilevato il problema, potrebbe essere necessario aggiornare il firmware del dispositivo o creare un nuovo modello di dispositivo che modella dati precedentemente non modellati.

Se si sceglie di creare un nuovo modello che modella correttamente i dati, eseguire la migrazione dei dispositivi dal modello precedente al nuovo modello. Per altre informazioni, vedere Gestire i dispositivi nell'applicazione Azure IoT Central.

JSON non valido

Se non sono stati segnalati errori, ma non viene visualizzato un valore, è probabilmente json in formato non valido nel payload inviato dal dispositivo. Per altre informazioni, vedere Telemetria, proprietà e payload dei comandi.

Non è possibile usare i comandi di convalida o la visualizzazione Dati non elaborati nell'interfaccia utente per rilevare se il dispositivo invia codice JSON in formato non valido.

Versione IoT Edge

Per visualizzare correttamente i dati di telemetria dai componenti ospitati nei moduli IoT Edge, usare IoT Edge versione 1.2.4 o successiva. Se si usa una versione precedente, i dati di telemetria dai componenti nei moduli IoT Edge vengono visualizzati come _unmodeleddata.

Problemi di identità gestita di esportazione dei dati

Si usa un'identità gestita per autorizzare la connessione a una destinazione di esportazione. I dati non arrivano alla destinazione di esportazione.

Prima di configurare o abilitare la destinazione di esportazione, assicurarsi di completare i passaggi seguenti:

Abilitare l'identità gestita per l'applicazione IoT Central. Per verificare che l'identità gestita sia abilitata, passare alla pagina Identità dell'applicazione nel portale di Azure o usare il comando dell'interfaccia della riga di comando seguente:
```
az iot central app identity show --name {your app name} --resource-group {your resource group name}
```

Configurare le autorizzazioni per l'identità gestita. Per visualizzare le autorizzazioni assegnate, selezionare Assegnazioni di ruolo di Azure nella pagina Identità per l'app nel portale di Azure o usare il comando dell'interfaccia della az role assignment list riga di comando. Le autorizzazioni necessarie sono:

Destinazione	Autorizzazione
Archiviazione BLOB di Azure	Collaboratore dati BLOB di archiviazione
Bus di servizio di Azure	Mittente dei dati del bus di servizio di Azure
Hub eventi di Azure	Mittente dei dati di Hub eventi di Azure
Esplora dati di Azure	Amministratore

Se le autorizzazioni non sono state impostate correttamente prima di creare la destinazione nell'applicazione IoT Central, provare a rimuovere la destinazione e quindi aggiungerla di nuovo.

Configurare tutte le reti virtuali, gli endpoint privati e i criteri firewall.

Nota

Se si usa un'identità gestita per autorizzare la connessione a una destinazione di esportazione, IoT Central non esporta i dati da dispositivi simulati.

Per altre informazioni, vedere Esportare i dati.

Problemi di connessione alla destinazione di esportazione dati

La pagina di definizione dell'esportazione mostra informazioni sulle connessioni non riuscite alla destinazione di esportazione:

Screenshot that shows an example export error.

Passaggi successivi

Per altre informazioni, è possibile contattare gli esperti di Azure nei forum di Microsoft Q&A e Stack Overflow.If you need more help, you can contact the Azure experts on the Microsoft Q&A and Stack Overflow forums. In alternativa, è possibile inviare un ticket di supporto tecnico di Azure.

Per altre informazioni, vedere Opzioni di supporto e guida di Azure IoT.