Integrationsfehler beheben

Cloud-zu-Cloud    Matter

Google Cloud bietet Ihnen die Tools, mit denen Sie die Zuverlässigkeit Ihrer Projekte mit Google Cloud Monitoring überwachen und Probleme mit Google Cloud Logging-Fehlerlogs beheben können. Wenn bei der Erfüllung von Nutzerabsichten ein Fehler auftritt, zeichnet die Google Home Analytics-Pipeline diesen Fehler in Ihren Messwerten auf und veröffentlicht ein Fehlerprotokoll in Ihren Projektlogs.

Zur Behebung von Fehlern sind zwei Schritte erforderlich:

  1. Behalte den Status deiner Projekte mit Smart-Home-Messwerten im Blick.
  2. Untersuchen Sie Probleme anhand der detaillierten Fehlerbeschreibungen in den Fehlerlogs.

Der Vorgang ist für die lokale Integration mit Local Home SDK ähnlich. Sobald Sie den Fehlerbehebungsablauf beherrschen, können Sie einfach zwischen Messwerten und Logs hin- und herwechseln, um Informationen zu Ihren Fehlern zu erhalten.

Fehler überwachen

Sie können Google Cloud Monitoring dashboards verwenden, um auf Ihre Projektmesswerte zuzugreifen. Es gibt einige wichtige Diagramme, die für die Überwachung der Qualität und für die Fehlerbehebung besonders nützlich sind:

  • Das Diagramm Erfolgsquote ist das erste Diagramm, ab dem Sie die Zuverlässigkeit Ihrer Projekte überwachen. Rückgänge in diesem Diagramm können auf einen Ausfall eines Teils oder der gesamten Nutzerbasis hinweisen. Wir empfehlen, dieses Diagramm nach jeder Änderung oder Aktualisierung Ihres Projekts genau auf Unregelmäßigkeiten zu prüfen.
  • Das Diagramm Latenz des 95. Perzentils ist ein wichtiger Indikator für die Leistung deiner Smart-Home-Aktion für deine Nutzer. Plötzliche Schwankungen in diesem Diagramm können ein Hinweis darauf sein, dass Ihre Systeme die Anfragen möglicherweise nicht mehr verarbeiten können. Es wird empfohlen, dieses Diagramm regelmäßig auf unerwartetes Verhalten zu prüfen.
  • Die Diagramme zur Fehleraufschlüsselung sind bei der Fehlerbehebung in Ihren Integrationen am nützlichsten. Für jeden im Diagramm für den Erfolg hervorgehobenen Fehler wird in der Fehleraufschlüsselung ein Fehlercode angezeigt. In der folgenden Tabelle sehen Sie die von Google Home platform gemeldeten Fehler und Informationen zur Fehlerbehebung.

Plattformfehlercodes

Im Folgenden sind einige häufige Fehlercodes aufgeführt, die in Ihren Projektlogs angezeigt werden können, um Probleme zu identifizieren, die von 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 anderen HTTP-4xx-Fehlercode als 401 erhalten.

Mit dem requestId in GCP Logging können Sie die Logs Ihrer Smart-Home-Dienste prüfen.
BACKEND_FAILURE_URL_TIMEOUT Bei der Anfrage von Google ist beim Versuch, Ihren Dienst zu erreichen, eine Zeitüberschreitung aufgetreten.

Prüfen Sie, ob Ihr Dienst online ist, Verbindungen akzeptiert und die Kapazität nicht überschritten 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-Fehlercode 5xx erhalten.

Mit dem requestId in GCP Logging können Sie die Logs Ihrer Smart-Home-Dienste prüfen.
DEVICE_NOT_FOUND Das Gerät ist beim Partnerdienst nicht vorhanden.

Dies weist normalerweise auf einen Fehler bei der Datensynchronisierung oder eine Race-Bedingung hin.
GAL_BAD_3P_RESPONSE Google kann die Antwort des Kontoverknüpfungsdienstes aufgrund eines ungültigen Formats oder ungültigen Werten in der Nutzlast nicht parsen.

Verwenden Sie requestId in GCP Logging, um Fehlerlogs in Ihrem Kontoverknüpfungsdienst zu prüfen.
GAL_INTERNAL Beim Versuch, ein Zugriffstoken abzurufen, ist ein interner Google-Fehler aufgetreten.

Wenn Sie eine erhöhte Fehlerrate in GCP Logging feststellen, kontaktieren Sie uns, um weitere Informationen zu erhalten.
GAL_INVALID_ARGUMENT Beim Versuch, ein Zugriffstoken abzurufen, ist ein interner Google-Fehler aufgetreten.

Wenn Sie eine erhöhte Fehlerrate in GCP Logging feststellen, kontaktieren Sie uns, um weitere Informationen zu erhalten.
GAL_NOT_FOUND Die in Google gespeicherten Zugriffstokens und Aktualisierungstokens des Nutzers werden ungültig gemacht und können nicht mehr aktualisiert werden. Der Nutzer muss sein Konto wieder verknüpfen, um den Dienst weiterhin nutzen zu können.

Wenn Sie eine erhöhte Fehlerrate in GCP Logging feststellen, kontaktieren Sie uns, um weitere Informationen zu erhalten.
GAL_PERMISSION_DENIED Ein interner Google-Fehler ist aufgetreten, als die Tokenfreigabe nicht autorisiert wurde.

Wenn Sie eine erhöhte Fehlerrate in GCP Logging feststellen, kontaktieren Sie uns, um weitere Informationen zu erhalten.
GAL_REFRESH_IN_PROGRESS Das Zugriffstoken des Nutzers ist abgelaufen und ein weiterer gleichzeitiger Aktualisierungsversuch wird bereits durchgeführt.

Das ist kein Problem und es sind keine Maßnahmen erforderlich.
INVALID_AUTH_TOKEN Google hat von Ihrem Dienst einen HTTP-401-Fehlercode erhalten.

Das Zugriffstoken ist nicht abgelaufen, aber Ihr Dienst hat es ungültig gemacht. Prüfen Sie mit dem requestId in GCP Logging die Logs Ihrer Smart-Home-Dienste.
INVALID_JSON Die JSON-Antwort kann nicht geparst oder gelesen 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 Das Zugriffstoken des Nutzers ist abgelaufen und kann von Google nicht aktualisiert werden oder Google hat einen HTTP 401-Fehlercode von deinem Dienst erhalten.

Wenn du eine erhöhte Rate dieses Codes siehst, prüfe, ob auch eine erhöhte Fehlerrate im Zusammenhang mit Smart-Home-Intents oder Aktualisierungstoken-Anfragen zu sehen ist.
PARTNER_RESPONSE_INVALID_ERROR_CODE Die Antwort gibt einen unbekannten Fehlercode an.

Wenn Ihre Anfrageantwort auf einen Fehler hinweist, verwenden Sie einen unserer unterstützten Fehlercodes.
PARTNER_RESPONSE_INVALID_PAYLOAD Das Antwortfeld payload kann nicht als JSON-Objekt geparst werden.

Prüfen Sie, ob das Nutzlastfeld in Ihrer Anfrageantwort übereinstimmende Klammern hat und korrekt als JSON-Feld strukturiert ist.
PARTNER_RESPONSE_INVALID_STATUS Die Antwort gibt keinen oder einen falschen Status an.

Antworten auf Anfragen zur Intent-Auftragsausführung sollten einen Status mit SUCCESS, OFFLINE, ERROR, EXCEPTIONS angeben. Weitere Informationen finden Sie unter Fehler und Ausnahmen beheben.
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES Mindestens ein in der Anfrage vorhandener Intent in der Antwort fehlt.

Prüfen Sie, ob Ihre Ausführungsantwort korrekt strukturiert ist und ob die Ergebnisse für alle Intents aus der Anfrage in der Antwort vorhanden sind.
PARTNER_RESPONSE_MISSING_DEVICE In der Antwort fehlt mindestens ein Gerät, das in der Anfrage vorhanden ist.

Prüfen Sie, ob Ihre Ausführungsantwort richtig strukturiert ist und ob alle Geräte-IDs aus der Anfrage in der Antwort vorhanden sind.
PARTNER_RESPONSE_MISSING_PAYLOAD Die Antwort enthält kein Feld payload.

Fügen Sie in die Anfrageantwort unbedingt ein Payload-Feld ein. Weitere Informationen zum richtigen Erstellen einer Ausführungsantwort
PARTNER_RESPONSE_NOT_OBJECT Die Antwort kann nicht als JSON-Objekt geparst werden.

Prüfen Sie alle Felder in Ihrer Anfrageantwort auf nicht beabsichtigte 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 deiner Smart-Home-Dienste zu prüfen.
RESPONSE_TIMEOUT Das Zeitlimit für die Anfrage wurde überschritten, während auf die Antwort gewartet wurde.

Das Zeitlimit für das Senden einer Antwort beträgt 9 Sekunden nach dem Senden der Anfrage. Achten Sie darauf, innerhalb dieses Zeitraums eine Antwort zu senden.
RESPONSE_UNAVAILABLE Es wird keine Antwort empfangen oder die Antwort gibt keinen Status an.

Antworten auf Anfragen zur Intent-Auftragsausführung sollten gemäß der Smart-Home-Dokumentation strukturiert werden und den Status angeben.
TRANSIENT_ERROR Ein vorübergehender Fehler ist ein Fehler, der sich von selbst löst.

In den meisten Fällen treten diese Fehler auf, wenn die Verbindung zu einem Gerät oder Dienst unterbrochen wird. Auch wenn keine neuen Verbindungen zu einem Server hergestellt werden können.

Suchprotokolle

Sobald Sie mit dem Monitoring Ihrer Einbindungen mithilfe von Messwerten vertraut sind, können Sie mit Cloud Logging bestimmte Fehler beheben. Ein Fehlerlog ist ein JSON-ähnlicher Eintrag mit Feldern, die nützliche Informationen wie Zeit, Fehlercode und Details zum ursprünglichen Smart-Home-Intent enthalten.

In Google Cloud gibt es mehrere Systeme, die jederzeit Logs an Ihr Projekt senden. Sie müssen Abfragen schreiben, um Ihre Logs zu filtern und die benötigten Abfragen zu finden. Abfragen können auf einem Zeitraum, einer Ressource, einem Log-Schweregrad oder benutzerdefinierten Einträgen basieren.

Cloud-Logs abfragen

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

Cloud-Logabfragen erstellen

Wenn Sie einen Zeitraum festlegen möchten, klicken Sie auf die Schaltfläche zur Auswahl des Zeitraums und wählen Sie eine der verfügbaren Optionen aus. Dadurch werden die Logs gefiltert und die Logs angezeigt, die aus dem ausgewählten Zeitraum stammen.

Klicken Sie zum Angeben einer Ressource auf das Drop-down-Menü Ressource und wählen Sie dann Google Assistant-Aktionsprojekt aus. Dadurch wird Ihrer Abfrage ein Filter hinzugefügt, um Logs anzuzeigen, die aus Ihrem Projekt stammen.

Verwenden Sie die Schaltfläche Schweregrad, um nach Notfall, Info, Fehlerbehebung und anderen Schweregradlogebenen zu filtern.

Sie können auch das Abfragefeld 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 wie Vergleichsoperatoren (<, >=, !=) und boolesche 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"

In der Abfragebibliothek finden Sie weitere Beispiele für das effektive Abfragen von Logs.

Fehlerbehebungen

Wenn Sie Fehler ermittelt und die entsprechenden Updates installiert haben, sollten Sie Ihre Korrekturen gründlich mit Google Home Test Suite testen. In einem Nutzerhandbuch zur Verwendung von Test Suite finden Sie eine Anleitung, wie Sie Ihre Änderungen effektiv testen können.

Lernmaterialien

In diesem Dokument wird beschrieben, wie du Fehler in deiner Smart-Home-Aktion beheben kannst. In unseren Codelabs erfahren Sie mehr über das Debugging:

Zurück
Cloud Logging