Condividi tramite

Come eseguire il debug di funzioni definite dall'utente in Gemelli digitali di Azure

Importante

È stata rilasciata una nuova versione del servizio Gemelli digitali di Azure. Alla luce delle funzionalità espanse del nuovo servizio, il servizio Gemelli digitali di Azure originale (descritto in questo set di documentazione) è stato ritirato.

Per visualizzare la documentazione per il nuovo servizio, visitare la documentazione attiva di Azure Digital Twins.

Questo articolo riepiloga come diagnosticare ed eseguire il debug di funzioni definite dall'utente in Gemelli digitali di Azure. Identifica quindi alcuni degli scenari più comuni rilevati durante il debug.

Suggerimento

Leggi Come configurare il monitoraggio e la registrazione per ulteriori informazioni sulla configurazione degli strumenti di debug in Azure Digital Twins utilizzando i Log Attività, i Log Diagnostica e Azure Monitor.

Problemi di debug

Sapere come diagnosticare i problemi all'interno di Gemelli digitali di Azure consente di analizzare in modo efficace i problemi, identificare le cause dei problemi e fornire soluzioni appropriate.

A tale scopo vengono forniti numerosi strumenti di registrazione, analisi e diagnostica.

Abilitare la registrazione per la vostra istanza

Gemelli digitali di Azure supporta funzionalità di registrazione, monitoraggio e analisi affidabili. Gli sviluppatori di soluzioni possono usare i log di Monitoraggio di Azure, i log di diagnostica, i log attività e altri servizi per supportare le complesse esigenze di monitoraggio di un'app IoT. Le opzioni di registrazione possono essere combinate per eseguire query o visualizzare record in diversi servizi e fornire una copertura granulare della registrazione per molti servizi.

Dopo la configurazione, sarà possibile selezionare tutte le categorie di log, le metriche e usare potenti aree di lavoro log analytics di Monitoraggio di Azure per supportare le attività di debug.

Telemetria del sensore di traccia

Per tracciare i dati di telemetria dei sensori, verificare che le impostazioni di diagnostica siano abilitate per l'istanza di Gemelli digitali di Azure. Assicurarsi quindi che siano selezionate tutte le categorie di log desiderate. Infine, verificare che i log desiderati vengano inviati ai log di Monitoraggio di Azure.

Per associare un messaggio di telemetria del sensore ai rispettivi log, è possibile specificare un ID di correlazione sui dati dell'evento inviati. A tale scopo, impostare la proprietà x-ms-client-request-id su un GUID.

Dopo aver inviato la telemetria, aprire Log Analytics di Azure Monitor per eseguire query sui log utilizzando l'ID di correlazione impostato.

AzureDiagnostics
| where CorrelationId == 'YOUR_CORRELATION_IDENTIFIER'
Valore della query Sostituire con
TUO_IDENTIFICATIVO_DI_CORRELAZIONE ID correlazione specificato nei dati dell'evento

Per leggere tutte le query di log di telemetria recenti:

AzureDiagnostics
| order by CorrelationId desc

Se si abilita la registrazione per la funzione definita dall'utente, questi log vengono visualizzati nell'istanza di Log Analytics con la categoria UserDefinedFunction. Per recuperarli, immettere la condizione di query seguente in Log Analytics:

AzureDiagnostics
| where Category == 'UserDefinedFunction'

Per altre informazioni sulle potenti operazioni di query, vedere Introduzione alle query.

Identificare i problemi comuni

Sia la diagnosi che l'identificazione dei problemi comuni sono importanti per la risoluzione dei problemi della soluzione. Diversi problemi comunemente riscontrati durante lo sviluppo di funzioni definite dall'utente vengono riepilogati nelle sottosezioni seguenti.

Negli esempi seguenti, YOUR_MANAGEMENT_API_URL fa riferimento all'URI delle API di Gemelli digitali:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0
Nome Sostituire con
NOME_DELLA_TUA_ISTANZA Nome della tua istanza di Azure Digital Twins
LA_TUA_POSIZIONE La regione in cui è ospitata la tua istanza

Controllare se è stata creata un'assegnazione di ruolo

Senza un'assegnazione di ruolo creata all'interno dell'API di gestione, la funzione definita dall'utente non ha accesso per eseguire azioni quali l'invio di notifiche, il recupero dei metadati e l'impostazione dei valori calcolati all'interno della topologia.

Controllare se esiste un'assegnazione di ruolo per la funzione definita dall'utente tramite l'API di gestione:

GET YOUR_MANAGEMENT_API_URL/roleassignments?path=/&traverse=Down&objectId=YOUR_USER_DEFINED_FUNCTION_ID
Valore del parametro Sostituire con
YOUR_USER_DEFINED_FUNCTION_ID ID della funzione definita dall'utente per recuperare le assegnazioni di ruolo per

Informazioni su come creare un'assegnazione di ruolo per la funzione definita dall'utente, se non esistono assegnazioni di ruolo.

Controllare se il matcher funziona per i dati di telemetria di un sensore

Con la seguente chiamata all'API di gestione delle istanze di Gemelli Digitali di Azure, è possibile determinare se un determinato matcher è applicabile al sensore specificato.

GET YOUR_MANAGEMENT_API_URL/matchers/YOUR_MATCHER_IDENTIFIER/evaluate/YOUR_SENSOR_IDENTIFIER?enableLogging=true
Parametro Sostituire con
YOUR_MATCHER_IDENTIFIER ID del matcher da valutare
YOUR_SENSOR_IDENTIFIER ID del sensore da valutare

Risposta:

{
    "success": true,
    "logs": [
        "$.dataType: \"Motion\" Equals \"Motion\" => True"
    ]
}

Controllare cosa attiva un sensore

Con la chiamata seguente alle API di gestione di Gemelli digitali di Azure, è possibile determinare gli identificatori delle funzioni definite dall'utente attivate dai dati di telemetria in ingresso del sensore specificato:

GET YOUR_MANAGEMENT_API_URL/sensors/YOUR_SENSOR_IDENTIFIER/matchers?includes=UserDefinedFunctions
Parametro Sostituire con
YOUR_SENSOR_IDENTIFIER ID del sensore da inviare i dati di telemetria

Risposta:

[
    {
        "id": "48a64768-797e-4832-86dd-de625f5f3fd9",
        "name": "MotionMatcher",
        "spaceId": "2117b3e1-b6ce-42c1-9b97-0158bef59eb7",
        "conditions": [
            {
                "id": "024a067a-414f-415b-8424-7df61392541e",
                "target": "Sensor",
                "path": "$.dataType",
                "value": "\"Motion\"",
                "comparison": "Equals"
            }
        ],
        "userDefinedFunctions": [
            {
                "id": "373d03c5-d567-4e24-a7dc-f993460120fc",
                "spaceId": "2117b3e1-b6ce-42c1-9b97-0158bef59eb7",
                "name": "Motion User-Defined Function",
                "disabled": false
            }
        ]
    }
]

Problema con la ricezione di notifiche

Quando non si ricevono notifiche dalla funzione attivata definita dall'utente, verificare che il parametro del tipo di oggetto topologia corrisponda al tipo di identificatore usato.

Errato Esempio:

var customNotification = {
    Message: 'Custom notification that will not work'
};

sendNotification(telemetry.SensorId, "Space", JSON.stringify(customNotification));

Questo scenario si verifica perché l'identificatore usato fa riferimento a un sensore mentre il tipo di oggetto topologia specificato è Space.

Corretto Esempio:

var customNotification = {
    Message: 'Custom notification that will work'
};

sendNotification(telemetry.SensorId, "Sensor", JSON.stringify(customNotification));

Il modo più semplice per evitare di imbattersi in questo problema consiste nell'usare il metodo Notify sull'oggetto metadati.

Esempio:

function process(telemetry, executionContext) {
    var sensorMetadata = getSensorMetadata(telemetry.SensorId);

    var customNotification = {
        Message: 'Custom notification'
    };

    // Short-hand for above methods where object type is known from metadata.
    sensorMetadata.Notify(JSON.stringify(customNotification));
}

Eccezioni di diagnostica comuni

Se si abilitano le impostazioni di diagnostica, è possibile che si verifichino queste eccezioni comuni:

  1. Limitazione: se la funzione definita dall'utente supera i limiti di velocità di esecuzione descritti nell'articolo Limiti del servizio , verrà limitata. Non vengono eseguite con successo altre operazioni fino alla scadenza dei limiti di controllo.

  2. Dati non trovati: se la funzione definita dall'utente tenta di accedere ai metadati che non esistono, l'operazione non riesce.

  3. Non autorizzato: se la funzione definita dall'utente non dispone di un set di assegnazioni di ruolo o non dispone di autorizzazioni sufficienti per accedere a determinati metadati dalla topologia, l'operazione non riesce.

Passaggi successivi

  • Last updated on