Integrationsfehler beheben

Google Cloud bietet Ihnen Tools, mit denen Sie die Zuverlässigkeit Ihrer Projekte mit Google Cloud Monitoring überwachen und Probleme mit Google Cloud Logging-Fehlerlogs beheben können. Immer 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 Fehlerbehebung sind zwei Schritte erforderlich:

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

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

Monitoringfehler

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 die Fehlerbehebung besonders nützlich sind:

  • Das Diagramm Erfolgsquote ist das erste Diagramm, ab dem Sie die Zuverlässigkeit Ihrer Projekte überwachen. Ein Rückgang in diesem Diagramm kann 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 überwachen.
  • Das Diagramm zur Latenz des 95. Perzentils ist ein wichtiger Indikator für die Leistung Ihrer Smart-Home-Aktion für Ihre Nutzer. Plötzliche Schwankungen in diesem Diagramm können darauf hindeuten, dass Ihre Systeme die Anfragen möglicherweise nicht mehr verarbeiten können. Wir empfehlen Ihnen, dieses Diagramm regelmäßig auf unerwartetes Verhalten zu prüfen.
  • Die Diagramme zur Fehleraufschlüsselung sind am nützlichsten für die Fehlerbehebung in Ihren Integrationen. Für jeden im Erfolgsprozentsatz hervorgehobenen Fehler wird in der Fehleraufschlüsselung ein Fehlercode angezeigt. In der Tabelle unten sehen Sie, welche Fehler von Google Home platform gemeldet wurden und wie Sie sie beheben können.

Plattform-Fehlercodes

Im Folgenden sind einige häufige Fehlercodes aufgeführt, die in Ihren Projektlogs angezeigt werden können, um Probleme zu identifizieren, die vom 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.

Verwenden Sie requestId in GCP Logging, um die Logs Ihrer Smart-Home-Dienste zu 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üfen Sie 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 die Logs Ihrer Smart-Home-Dienste zu 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 Ihres Kontoverknüpfungsdienstes aufgrund ungültiger Formate oder Werte 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, wenden Sie sich bitte an 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, wenden Sie sich bitte an uns, um weitere Informationen zu erhalten.
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 wieder verknüpfen, um den Dienst weiterhin zu verwenden.

Wenn Sie eine erhöhte Fehlerrate in GCP Logging feststellen, wenden Sie sich bitte an uns, um weitere Informationen zu erhalten.
GAL_PERMISSION_DENIED Als die Tokenfreigabe nicht autorisiert ist, ist ein interner Google-Fehler aufgetreten.

Wenn Sie eine erhöhte Fehlerrate in GCP Logging feststellen, wenden Sie sich bitte an uns, um weitere Informationen zu erhalten.
GAL_REFRESH_IN_PROGRESS Das Zugriffstoken des Nutzers ist abgelaufen und ein weiterer gleichzeitiger Aktualisierungsversuch läuft bereits.

Das ist kein Problem und es sind keine Maßnahmen erforderlich.
INVALID_AUTH_TOKEN Google hat von Ihrem Dienst den HTTP-Fehlercode 401 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 von Ihrem Dienst einen HTTP 401-Fehlercode erhalten.

Wenn Sie eine höhere Rate dieses Codes feststellen, prüfen Sie, ob auch eine erhöhte Fehlerrate im Zusammenhang mit Smart-Home-Intents oder Aktualisierungstokenanfragen zu sehen ist.
PARTNER_RESPONSE_INVALID_ERROR_CODE Die Antwort gibt einen unbekannten Fehlercode an.

Wenn Ihre Anfrageantwort auf einen Fehler hinweist, achten Sie darauf, einen aus unseren unterstützten Fehlercodes zu verwenden.
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 als Status entweder SUCCESS, OFFLINE, ERROR, EXCEPTIONS angeben. Weitere Informationen finden Sie unter Behandlung von Fehlern und Ausnahmen.
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES Mindestens ein in der Anfrage vorhandener Intent in der Antwort fehlt.

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

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

Ihre Anfrageantwort muss ein Nutzlastfeld enthalten. Weitere Informationen zum richtigen Erstellen einer Ausführungsantwort finden Sie hier.
PARTNER_RESPONSE_NOT_OBJECT Die Antwort kann nicht als JSON-Objekt geparst werden.

Prüfen Sie alle Felder in Ihrer Anfrageantwort auf unbeabsichtigte 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 bei der Verarbeitung der Anfrage.

Verwenden Sie requestId in Google Cloud Logging, um die Logs Ihrer Smart-Home-Dienste zu prüfen.
RESPONSE_TIMEOUT Bei der Anfrage ist eine Zeitüberschreitung aufgetreten, 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 sein und den Status angeben.
TRANSIENT_ERROR Ein vorübergehender Fehler ist ein Fehler, der von selbst behoben wird.

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

Suchprotokolle

Wenn Sie sich mit dem Monitoring Ihrer Integrationen mithilfe von Messwerten vertraut gemacht haben, können Sie im nächsten Schritt bestimmte Fehler mit Cloud Logging 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.

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

Cloud-Logs abfragen

Sie können die Abfrageschaltflächen verwenden, um Ihre benutzerdefinierten Filter zu erstellen.

Cloud-Logabfragen erstellen

Zum Festlegen eines Zeitraums klicken Sie auf die Schaltfläche zur Auswahl des Zeitraums und wählen eine der verfügbaren Optionen aus. Dadurch werden die Logs gefiltert und die Logs 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 dann Google Assistant Action Project aus. Dadurch wird der Abfrage ein Filter hinzugefügt, um Logs aus Ihrem Projekt anzuzeigen.

Verwenden Sie die Schaltfläche Schweregrad, um nach Notfall, Info, Fehlerbehebung und anderen Schweregrad-Logebenen 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, 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"

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

Korrekturen testen

Sobald Sie Fehler gefunden haben und Updates anwenden, um sie zu beheben, empfehlen wir, Ihre Korrekturen gründlich mit Google Home Test Suite zu testen. Wir stellen ein Nutzerhandbuch zur Verwendung von Test Suite bereit, das Sie durch das effektive Testen Ihrer Änderungen führt.

Lernmaterialien

In diesem Dokument wird beschrieben, wie du Fehler bei deiner Smart-Home-Aktion beheben kannst. Weitere Informationen zur Fehlerbehebung finden Sie in unseren Codelabs: