Integrationsfehler beheben

Cloud-to-Cloud    Matter

Google Cloud bietet Ihnen die Werkzeuge, um die Zuverlässigkeit Ihrer Projekte mit Google Cloud Monitoring zu überwachen und Probleme mit Google Cloud Logging Fehlerprotokollen zu beheben. Wenn bei der Erfüllung von Nutzerabsichten ein Fehler auftritt, protokolliert die Google Home Analytics-Pipeline diesen Fehler in Ihren Metriken und veröffentlicht einen Fehlerbericht in Ihren Projektprotokollen.

Die Fehlerbehebung erfolgt in zwei Schritten:

  1. Überwachen Sie den Status Ihrer Projekte mit Smart-Home-Kennzahlen.
  2. Untersuchen Sie Probleme, indem Sie die detaillierten Fehlerbeschreibungen in den Fehlerprotokollen überprüfen.

Das Verfahren ist für die lokale Integration unter Verwendung von Local Home SDK ähnlich. Sobald Sie den Ablauf zur Fehlerbehebung beherrschen, können Sie ganz einfach zwischen Messwerten und Logs hin- und herwechseln, um sich ein Bild von den Fehlern zu machen.

Optional können Sie Ihre Aktion testen, indem Sie sie für andere Nutzer freigeben. Achten Sie darauf, Fehler und Ausnahmen angemessen zu behandeln.

Fehler beim Monitoring

Sie können Google Cloud Monitoring dashboards verwenden, um auf Ihre Projektmesswerte zuzugreifen. Es gibt einige wichtige Diagramme, die besonders nützlich sind, um die Qualität zu überwachen und Fehler zu beheben:

  • Das Diagramm Erfolgsrate ist das erste Diagramm, das Sie sich ansehen sollten, wenn Sie die Zuverlässigkeit Ihrer Projekte im Blick behalten möchten. Ein Rückgang in diesem Diagramm kann auf einen Ausfall für einen Teil oder alle Nutzer hinweisen. Wir empfehlen, dieses Diagramm nach jeder Änderung oder Aktualisierung Ihres Projekts genau auf Unregelmäßigkeiten zu beobachten.
  • Das Diagramm Latenz im 95. Perzentil ist ein wichtiger Indikator dafür, wie die Cloud-to-cloud-Integration für Ihre Nutzer funktioniert. Plötzliche Schwankungen in diesem Diagramm können darauf hindeuten, dass Ihre Systeme die Anfragen möglicherweise nicht bewältigen können. Es empfiehlt sich, dieses Diagramm regelmäßig zu prüfen, um unerwartetes Verhalten zu erkennen.
  • Die Diagramme unter Fehleraufschlüsselung sind am nützlichsten, wenn Sie Probleme mit Ihren Integrationen beheben möchten. Für jeden Fehler, der im Diagramm mit dem Prozentsatz für erfolgreiche Anfragen hervorgehoben wird, wird in der Fehleraufschlüsselung ein Fehlercode angezeigt. In der Tabelle unten finden Sie die von Google Home platform gemeldeten Fehler und Informationen zur Fehlerbehebung.

Plattformfehlercodes

Hier sind einige häufige Fehlercodes, die in den Projektlogs angezeigt werden können, um Probleme zu identifizieren, die von der Google Home platform erkannt wurden. Informationen zur Fehlerbehebung finden Sie in der folgenden Tabelle.

Fehlercode Beschreibung
BACKEND_FAILURE_URL_ERROR Google hat von Ihrem Dienst einen HTTP-4xx-Fehlercode mit Ausnahme von 401 erhalten.

Verwenden Sie requestId in GCP Logging, um Ihre Smart-Home-Dienstprotokolle zu überprüfen.
BACKEND_FAILURE_URL_TIMEOUT Bei der Anfrage von Google ist eine Zeitüberschreitung aufgetreten, als versucht wurde, Ihren Dienst zu erreichen.

Prüfen Sie, ob Ihr Dienst online ist, Verbindungen akzeptiert und nicht überlastet ist. Prüfe außerdem, ob das Zielgerät eingeschaltet, online und synchronisiert ist.
BACKEND_FAILURE_URL_UNREACHABLE Google hat von Ihrem Dienst einen HTTP-5xx-Fehlercode erhalten.

Verwenden Sie requestId in GCP Logging, um Ihre Smart-Home-Dienstprotokolle zu überprüfen.
DEVICE_NOT_FOUND Das Gerät ist beim Partnerdienst nicht vorhanden.

Dies deutet normalerweise auf einen Fehler bei der Datensynchronisation oder eine Race Condition hin.
GAL_BAD_3P_RESPONSE Google kann die Antwort Ihres Dienstes zur Kontoverknüpfung aufgrund eines ungültigen Formats oder ungültiger Werte in der Nutzlast nicht parsen.

Verwende requestId in GCP Logging, um Fehlerlogs in deinem Konto-Verknüpfungsdienst zu prüfen.
GAL_INTERNAL Beim Versuch, ein Zugriffstoken abzurufen, ist ein interner Google-Fehler aufgetreten.

Wenn dieser Fehler in GCP Logging häufiger auftritt, wenden Sie sich an uns.
GAL_INVALID_ARGUMENT Beim Abrufen eines Zugriffstokens ist ein interner Fehler bei Google aufgetreten.

Sollten Sie in den GCP-Protokollen eine erhöhte Anzahl dieses Fehlers feststellen, kontaktieren Sie uns bitte für weitere Informationen.
GAL_NOT_FOUND Die in Google gespeicherten Zugriffstokens und Aktualisierungstokens des Nutzers werden ungültig und können nicht mehr aktualisiert werden. Der Nutzer muss sein Konto neu verknüpfen, um Ihren Dienst weiterhin nutzen zu können.

Wenn dieser Fehler in GCP Logging häufiger auftritt, wenden Sie sich an uns.
GAL_PERMISSION_DENIED Ein interner Google-Fehler ist aufgetreten, weil die Weitergabe von Tokens nicht autorisiert ist.

Sollten Sie in den GCP-Protokollen eine erhöhte Anzahl dieses Fehlers feststellen, kontaktieren Sie uns bitte für weitere Informationen.
GAL_REFRESH_IN_PROGRESS Das Zugriffstoken des Nutzers ist abgelaufen und es wird bereits versucht, es zu aktualisieren.

Dies ist kein Problem und es ist keine Aktion erforderlich.
INVALID_AUTH_TOKEN Google hat von Ihrem Dienst den HTTP-Fehlercode 401 erhalten.

Das Zugriffstoken ist nicht abgelaufen, wurde aber von Ihrem Dienst ungültig gemacht. Mit requestId in GCP Logging kannst du die Logs deines Smart-Home-Dienstes aufrufen.
INVALID_JSON Die JSON-Antwort kann nicht analysiert oder verstanden werden.

Prüfen Sie die Struktur Ihrer JSON-Antwort auf ungültige Syntax, z. B. nicht übereinstimmende Klammern, fehlende Kommas oder ungültige Zeichen.
OPEN_AUTH_FAILURE Der Zugriffstoken des Nutzers ist abgelaufen und Google kann ihn nicht aktualisieren, oder Google hat von Ihrem Dienst den HTTP-Fehlercode 401 erhalten.

Sollten Sie eine erhöhte Anzahl dieser Codes feststellen, prüfen Sie, ob auch die Anzahl der Fehler im Zusammenhang mit Smart-Home-Intents oder Refresh-Token-Anfragen zunimmt.
PARTNER_RESPONSE_INVALID_ERROR_CODE Die Antwort enthält einen unbekannten Fehlercode.

Falls Ihre Antwort einen Fehler anzeigt, verwenden Sie bitte einen der von uns bereitgestellten unterstützten Fehlercodes.
PARTNER_RESPONSE_INVALID_PAYLOAD Das Feld „Antwort“ payload kann nicht als JSON-Objekt geparst werden.

Prüfen Sie, ob das Feld „payload“ in Ihrer Anfrageantwort übereinstimmende Klammern hat und als JSON-Feld korrekt strukturiert ist.
PARTNER_RESPONSE_INVALID_STATUS In der Antwort wird kein Status oder ein falscher Status angegeben.

Antworten auf Anfragen zur Intent-Ausführung sollten einen Status mit SUCCESS, OFFLINE, ERROR, EXCEPTIONS angeben. Weitere Informationen finden Sie unter Fehler und Ausnahmen behandeln.
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES In der Antwort fehlt mindestens eine Absicht, die in der Anfrage enthalten ist.

Prüfe, ob deine Ausführungsantwort korrekt strukturiert ist und die Ergebnisse für alle Intents aus der Anfrage in deiner Antwort enthalten sind.
PARTNER_RESPONSE_MISSING_DEVICE In der Antwort fehlt mindestens ein Gerät, das in der Anfrage aufgeführt ist.

Prüfe, ob deine Ausführungsantwort korrekt strukturiert ist und alle Geräte-IDs aus der Anfrage in deiner Antwort enthalten sind.
PARTNER_RESPONSE_MISSING_PAYLOAD Die Antwort enthält kein Feld payload.

Achten Sie darauf, dass Ihre Anfrageantwort ein Nutzlastfeld enthält. Weitere Informationen zum korrekten Erstellen einer Ausführungsantwort
PARTNER_RESPONSE_NOT_OBJECT Die Antwort kann nicht als JSON-Objekt geparst werden.

Prüfen Sie alle Felder in Ihrer Antwort auf die Anfrage auf unerwünschte Zeichen, nicht übereinstimmende Klammern oder Formatierungsfehler. Einige Unicode-Zeichen werden möglicherweise nicht unterstützt. Achten Sie außerdem darauf, dass Ihre Antwort korrekt als JSON-Objekt strukturiert ist.
PROTOCOL_ERROR Fehler beim Verarbeiten der Anfrage.

Verwende requestId in Google Cloud Logging, um die Logs deines Smart-Home-Dienstes zu prüfen.
RELINK_REQUIRED Die Antwort deutete auf einen relinkRequired-Fehler hin, der den Benutzer auffordert, seine Google- und Partnerkonten erneut zu verknüpfen.

Weitere Informationen finden Sie unter Unterstützte Fehlercodes.
RESPONSE_TIMEOUT Zeitüberschreitung bei der Anfrage beim Warten auf die Antwort.

Das Zeitlimit für das Senden einer Antwort beträgt 9 Sekunden ab dem Zeitpunkt, an dem die Anfrage gesendet wird. Bitte senden Sie innerhalb dieses Zeitraums eine Antwort.
RESPONSE_UNAVAILABLE Es wird keine Antwort empfangen oder die Antwort enthält keinen Status.

Antworten auf Anfragen zur Intenterfüllung sollten gemäß der Smart-Home-Dokumentation strukturiert sein und den Status angeben.
TRANSIENT_ERROR Ein vorübergehender Fehler ist ein Fehler, der sich von selbst behebt.

Diese Fehler äußern sich meistens dadurch, dass die Verbindung zu einem Gerät oder Dienst unterbrochen wird. Auch wenn keine neuen Verbindungen zu einem Server geöffnet werden können.

Suchprotokolle

Wenn Sie sich mit der Überwachung Ihrer Integrationen mithilfe von Messwerten vertraut gemacht haben, können Sie als Nächstes bestimmte Fehler mit Cloud Logging beheben. Ein Fehlerlog ist ein JSON-ähnlicher Eintrag mit Feldern, die nützliche Informationen wie Zeit, Fehlercode und Details zur ursprünglichen Smart-Home-Intention enthalten.

Innerhalb von Google Cloud gibt es mehrere Systeme, die ständig Protokolle an Ihr Projekt senden. Sie müssen Abfragen schreiben, um Ihre Logs zu filtern und die benötigten Logs zu finden. Abfragen können auf einem Zeitbereich, einer Ressource, dem Schweregrad von Logs oder benutzerdefinierten Einträgen basieren.

Cloud-Logs abfragen

Mithilfe der Abfrageschaltflächen können Sie Ihre benutzerdefinierten Filter erstellen.

Cloud-Protokollabfragen erstellen

Um einen Zeitbereich festzulegen, klicken Sie auf die Schaltfläche zur Auswahl des Zeitbereichs und wählen Sie eine der bereitgestellten Optionen aus. Dadurch werden die Protokolle gefiltert und diejenigen angezeigt, die aus dem ausgewählten Zeitraum stammen.

Wenn Sie eine Ressource angeben möchten, klicken Sie auf das Drop-down-Menü Ressource und wählen Sie Google Assistant-Aktionsprojekt aus. Dadurch wird Ihrer Abfrage ein Filter hinzugefügt, um Logs anzuzeigen, die aus Ihrem Projekt stammen.

Mit der Schaltfläche Schweregrad können Sie nach Notfall, Info, Debug und anderen Schweregraden filtern.

Sie können auch das Feld „Abfrage“ in Logs Explorer verwenden, um benutzerdefinierte Einträge einzugeben. Die von diesem Feld verwendete Abfrage-Engine unterstützt sowohl einfache Abfragen wie den Stringabgleich als auch komplexere Abfragetypen, einschließlich Vergleichsoperatoren (<, >=, !=) und booleschen Operatoren (AND, OR, NOT).

Der folgende benutzerdefinierte Eintrag würde beispielsweise Fehler zurückgeben, die von einem LIGHT-Gerätetyp stammen:

resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"

Besuchen Sie die Query Library, um weitere Beispiele für die effektive Abfrage von Protokolldateien zu finden.

Korrekturen testen

Nachdem Sie Fehler identifiziert und Updates zur Behebung angewendet haben, empfehlen wir, die Korrekturen mit Google Home Test Suite gründlich zu testen. Wir stellen eine Bedienungsanleitung zur Verfügung.Test Suite, das Sie Schritt für Schritt durch das effektive Testen Ihrer Änderungen führt.

Lernmaterialien

Dieses Dokument beschreibt die Schritte zur Fehlerbehebung in Ihrer Smart Home Action. In unseren Codelabs erfahren Sie außerdem mehr über das Debuggen:

Zurück
Cloud Logging