Debuggen von benutzerdefinierten Funktionen in Azure Digital Twins

  • Artikel

Wichtig

Eine neue Version des Azure Digital Twins-Diensts wurde veröffentlicht. Angesichts der erweiterten Funktionen des neuen Diensts wurde der ursprüngliche Azure Digital Twins-Dienst (in diesem Dokumentationssatz beschrieben) eingestellt.

Um die Dokumentation für den neuen Dienst anzuzeigen, besuchen Sie die aktive Azure Digital Twins-Dokumentation.

In diesem Artikel erfahren Sie, wie Sie benutzerdefinierte Funktionen in Azure Digital Twins diagnostizieren und debuggen. Danach werden einige der häufigsten Szenarien vorgestellt, die beim Debuggen dieser Funktionen anzutreffen sind.

Tipp

Lesen Sie Vorgehensweise: Konfigurieren von Überwachung und Protokollierung, um Informationen zum Einrichten der Debuggingtools in Azure Digital Twins mithilfe von Aktivitätsprotokollen, Diagnoseprotokollen und Azure Monitor zu erhalten.

Debuggen von Problemen

Wenn Sie wissen, wie Sie Probleme mit Azure Digital Twins diagnostizieren, können Sie effektiv Probleme analysieren, Problemursachen ermitteln und geeignete Maßnahmen ergreifen.

Hierzu stehen verschiedene Protokollierungs-, Analyse- und Diagnosetools zur Verfügung.

Aktivieren der Protokollierung für Ihre Instanz

Azure Digital Twins bietet eine zuverlässige Protokollierung, Überwachung und Analyse. Lösungsentwickler können Azure Monitor-Protokolle, Diagnoseprotokolle, Aktivitätsprotokolle und andere Dienste nutzen, um den komplexen Überwachungsanforderungen einer IoT-App gerecht zu werden. Protokollierungsoptionen können kombiniert werden, um Datensätze aus mehreren Diensten abzufragen oder anzuzeigen und eine maßgeschneiderte Protokollierung für eine Vielzahl von Diensten zur Verfügung zu stellen.

Nach Abschluss der Konfiguration können Sie alle Protokollkategorien sowie Metriken auswählen und beim Debuggen auf leistungsstarke Azure Monitor-Arbeitsbereiche für die Protokollanalyse zurückgreifen.

Nachverfolgen von Sensortelemetriedaten

Vergewissern Sie sich beim Verfolgen von Sensortelemetriedaten, dass die Diagnoseeinstellungen für Ihre Azure Digital Twins-Instanz aktiviert sind. Stellen Sie sicher, dass alle gewünschten Protokollkategorien ausgewählt sind. Bestätigen Sie abschließend, dass die gewünschten Protokolle an Azure Monitor-Protokolle gesendet werden.

Um eine Sensortelemetriemeldung den entsprechenden Protokollen zuzuordnen, können Sie eine Korrelations-ID für die Ereignisdaten angeben, die gesendet werden. Legen Sie dazu die x-ms-client-request-id-Eigenschaft auf eine GUID fest.

Öffnen Sie nach dem Senden von Telemetriedaten Azure Monitor Log Analytics, um Protokolle mithilfe der Korrelations-ID abzufragen:

AzureDiagnostics
| where CorrelationId == 'YOUR_CORRELATION_IDENTIFIER'
Abfragewert Ersetzen durch
YOUR_CORRELATION_IDENTIFIER Die Korrelations-ID, die für die Ereignisdaten angegeben wurde.

Zum Lesen aller aktuellen Telemetrieprotokolle fragen Sie Folgendes ab:

AzureDiagnostics
| order by CorrelationId desc

Wenn Sie die Protokollierung für Ihre benutzerdefinierte Funktion aktivieren, werden diese Protokolle in Ihrer Instanz der Protokollanalyse mit der Kategorie UserDefinedFunction angezeigt. Um sie abzurufen, geben Sie die folgende Abfragebedingung in der Protokollanalyse ein:

AzureDiagnostics
| where Category == 'UserDefinedFunction'

Weitere Informationen zu leistungsstarken Abfragevorgängen finden Sie unter "Erste Schritte mit Abfragen".

Identifizieren von häufig auftretenden Problemen

Für die Problembehandlung Ihrer Lösung spielen sowohl die Diagnostizierung als auch die Ermittlung von häufig auftretenden Problemen eine wichtige Rolle. Einige häufig auftretende Probleme beim Entwickeln von benutzerdefinierten Funktionen werden in den folgenden Unterabschnitten zusammengefasst.

In den folgenden Beispielen bezieht sich YOUR_MANAGEMENT_API_URL auf den URI der Digital Twins-APIs:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0
Name Ersetzen durch
YOUR_INSTANCE_NAME Den Namen Ihrer Azure Digital Twins-Instanz
YOUR_LOCATION Die Region, in der Ihre Instanz gehostet wird

Überprüfen, ob eine Rollenzuweisung erstellt wurde

Wenn keine Rollenzuweisung innerhalb der Verwaltungs-API erstellt wird, hat die benutzerdefinierte Funktion keinen Zugriff zum Ausführen von Aktionen wie dem Senden von Benachrichtigungen, Abrufen von Metadaten und Festlegen von berechneten Werten in der Topologie.

Überprüfen Sie, ob eine Rollenzuweisung für Ihre benutzerdefinierte Funktion über die Verwaltungs-API vorhanden ist:

GET YOUR_MANAGEMENT_API_URL/roleassignments?path=/&traverse=Down&objectId=YOUR_USER_DEFINED_FUNCTION_ID
Parameterwert Ersetzen durch
YOUR_USER_DEFINED_FUNCTION_ID Die ID der benutzerdefinierten Funktion, für die Rollenzuweisungen abgerufen werden sollen

Informationen, wenn keine Rollenzuweisungen vorhanden sind, finden Sie unter Gewusst wie: Verwenden von benutzerdefinierten Funktionen in Azure Digital Twins.

Überprüfen, ob der Matcher für die Telemetriedaten eines Sensors funktioniert

Mit dem folgenden Aufruf der Verwaltungs-API Ihrer Azure Digital Twins-Instanzen können Sie feststellen, ob ein bestimmter Matcher für den angegebenen Sensor gilt.

GET YOUR_MANAGEMENT_API_URL/matchers/YOUR_MATCHER_IDENTIFIER/evaluate/YOUR_SENSOR_IDENTIFIER?enableLogging=true
Parameter Ersetzen durch
YOUR_MATCHER_IDENTIFIER Die ID des Matchers, den Sie auswerten möchten
YOUR_SENSOR_IDENTIFIER Die ID des Sensors, den Sie auswerten möchten

Antwort:

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

Überprüfen, wodurch ein Sensor ausgelöst wird

Mit dem folgenden Aufruf der Verwaltungs-APIs von Azure Digital Twins können Sie die Bezeichner der benutzerdefinierten Funktionen ermitteln, die durch die eingehenden Telemetriedaten des angegebenen Sensors ausgelöst werden:

GET YOUR_MANAGEMENT_API_URL/sensors/YOUR_SENSOR_IDENTIFIER/matchers?includes=UserDefinedFunctions
Parameter Ersetzen durch
YOUR_SENSOR_IDENTIFIER Die ID des Sensors zum Senden von Telemetriedaten

Antwort:

[
    {
        "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
            }
        ]
    }
]

Problem mit dem Empfang von Benachrichtigungen

Wenn Sie keine Benachrichtigungen von der ausgelösten benutzerdefinierten Funktion erhalten, vergewissern Sie sich, dass der Objekttypparameter Ihrer Topologie dem Typ des verwendeten Bezeichners entspricht.

Falsche Beispiel:

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

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

Dieses Szenario tritt auf, weil der verwendete Bezeichner auf einen Sensor verweist, obwohl der angegebene Objekttyp der Topologie Space lautet.

Richtig Beispiel:

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

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

Die einfachste Möglichkeit, dieses Problem zu verhindern, besteht darin, die Notify-Methode für das Metadatenobjekt zu verwenden.

Beispiel:

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));
}

Allgemeine Diagnoseausnahmen

Wenn Sie Diagnoseeinstellungen aktivieren, können die folgenden allgemeinen Ausnahmen auftreten:

  1. Drosselung: Wenn Ihre benutzerdefinierte Funktion die Ausführungsratenlimits überschreitet, die im Artikel Dienstlimits der öffentlichen Vorschau genannt werden, wird sie gedrosselt. Es werden keine weiteren Vorgänge erfolgreich ausgeführt, bis die Drosselungslimits ablaufen.

  2. Daten nicht gefunden: Wenn Ihre benutzerdefinierte Funktion versucht, auf Metadaten zuzugreifen, die nicht vorhanden sind, tritt bei dem Vorgang ein Fehler auf.

  3. Nicht autorisiert: Wenn für Ihre benutzerdefinierte Funktion keine Rollenzuweisung festgelegt ist oder sie keine ausreichenden Berechtigungen für den Zugriff auf bestimmte Metadaten aus der Topologie besitzt, tritt bei dem Vorgang ein Fehler auf.

Nächste Schritte