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, wird dieser von der Google Home Analytics-Pipeline in deinen Messwerten erfasst und ein Fehlerprotokoll in deinen Projektprotokollen veröffentlicht.
Die Fehlerbehebung erfolgt in zwei Schritten:
- Behalte den Status deiner Projekte mit Smart-Home-Messwerten im Blick.
- Untersuchen Sie Probleme, indem Sie die detaillierten Fehlerbeschreibungen in den Fehlerlogs prüfen.
Optional können Sie Ihre Aktion testen, indem Sie sie für andere Nutzer freigeben. Achten Sie darauf, Fehler und Ausnahmen angemessen zu behandeln.
Monitoring-Fehler
Sie können Google Cloud Monitoring dashboards verwenden, um auf Ihre Projektmesswerte zuzugreifen. Es gibt einige wichtige Diagramme, die besonders für das Monitoring der Qualität und das Debugging nützlich sind:
- Das Diagramm Erfolgsquote ist das erste Diagramm, mit dem Sie die Zuverlässigkeit Ihrer Projekte überwachen können. Einbrüche in diesem Diagramm können 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 prüfen.
- Das Diagramm 95. Perzentil der Latenz ist ein wichtiger Indikator für die Leistung Ihrer Cloud-to-cloud-Integration für Ihre Nutzer. Plötzliche Schwankungen in diesem Diagramm können darauf hindeuten, dass Ihre Systeme möglicherweise nicht mit den Anfragen Schritt halten können. Es empfiehlt sich, dieses Diagramm regelmäßig auf unerwartetes Verhalten zu prüfen.
- Die Diagramme zur Fehleraufschlüsselung sind besonders nützlich, wenn Sie Probleme mit Ihren Integrationen beheben möchten. Für jeden Fehler, der im Diagramm mit dem Erfolgsprozentsatz hervorgehoben ist, wird in der Fehleraufschlüsselung ein Fehlercode angezeigt. In der folgenden Tabelle finden Sie die von Google Home platform gemeldeten Fehler und Informationen zur Fehlerbehebung.
Häufige Plattform-Fehlercodes
Im Folgenden finden Sie einige häufige Fehlercodes, 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. Eine vollständige Liste der Fehlercodes finden Sie unter Fehler und Ausnahmen.
| Fehlercode | Beschreibung | Partner Actionable |
|---|---|---|
AGENT_ISSUE |
Es ist ein allgemeines Problem mit dem Cloud-Agenten des Partners aufgetreten.
Prüfe deine Ausführungslogs auf nicht behandelte Ausnahmen oder Abstürze. |
Ja |
AGENT_UNAVAILABLE_ERROR |
Google konnte die Auftragsausführungs-URL des Partners nicht erreichen.
Prüfen Sie, ob Ihr Server online ist, die Firewall Google nicht blockiert und die URL korrekt ist. |
Ja |
COMMAND_FAILED |
Bei der Ausführung eines Befehls ist ein allgemeiner Fehler aufgetreten.
Prüfe deine Auftragsausführungslogs auf die spezifische requestId, um die Ursache zu finden.
|
Ja |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google hat von deiner Auftragsausführung einen HTTP-4xx-Fehler (außer 401) erhalten.
Prüfen Sie die Server-Logs Ihres Webservers auf 403-, 404- oder 400-Antworten. |
Ja |
EXECUTION_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 die Kapazität nicht überschritten ist. Prüfen Sie außerdem, ob das Zielgerät eingeschaltet, online und synchronisiert ist. |
Ja |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
Die Auftragsausführungs-URL wird durch die robots.txt-Datei oder Sicherheitsfilter blockiert.
Achte darauf, dass dein Auftragsausführungsendpunkt für die Crawler/Dienste von Google zugänglich ist. |
Ja |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google hat von Ihrem Auftragsausführungsdienst einen HTTP 5xx-Fehler erhalten.
Achten Sie darauf, dass der Endpunkt-URL-Dienst stabil, korrekt und öffentlich erreichbar ist und dass der Dienst ausgeführt wird. Verwende requestId in Google Cloud Logging, um die Logs deines Smart-Home-Dienstes zu prüfen.
Fügen Sie Systemdiagnosen und eine Wiederholungsbehandlung hinzu.
Untersuchen Sie Serverabstürze, Zeitüberschreitungen oder 502/503-Gateway-Fehler.
|
Ja |
EXECUTION_BAILOUT_INVALID_RESPONSE |
Die JSON-Antwort war so fehlerhaft, dass die Verarbeitung abgebrochen wurde.
Verwenden Sie einen JSON-Validator, um sicherzustellen, dass Ihre Antwort genau den Intent-Schemas entspricht. |
Ja |
EXECUTION_GAL_BAD_3P_RESPONSE |
Die Kontoverknüpfung ist aufgrund eines ungültigen Formats in der Tokenantwort fehlgeschlagen.
Prüfen Sie, ob das Antwortformat Ihres OAuth-Servers den Anforderungen von Google entspricht. |
Ja |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
Das Konto des Nutzers hat nicht die erforderlichen Berechtigungen für diese Aktion.
Prüfe die während der OAuth-Anfrage angeforderten Bereiche und stelle sicher, dass sie mit den erforderlichen Eigenschaften übereinstimmen. |
Ja |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
Die Partner-Cloud gibt an, dass der Nutzer die Verknüpfung seines Kontos aufgehoben hat.
Achten Sie darauf, dass die agentUserId-Zuordnung stabil ist und nicht gelöscht wurde.
|
Ja |
EXECUTION_GAL_NOT_FOUND |
Die bei Google gespeicherten Zugriffs- und Aktualisierungstokens des Nutzers sind ungültig oder können nicht aktualisiert werden, was die Authentifizierung und den Zugriff auf den Partnerdienst verhindert.
Achte darauf, dass die Tokens gültig und synchronisiert bleiben, gehe angemessen mit Änderungen des Kontostatus um und fordere Nutzer auf, das Konto neu zu verknüpfen, wenn die Tokens widerrufen wurden. |
|
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
Die Integration befindet sich auf Partnerseite im Lesemodus.
Prüfen Sie, ob das Konto des Nutzers gesperrt ist oder sich im Wartungsmodus „Nur Ansicht“ befindet. |
Ja |
EXECUTION_GAL_UNLINKED_BY_3P |
Die Verknüpfung mit dem Konto wurde vom Drittanbieterdienst proaktiv aufgehoben.
Untersuchen Sie, warum die Verbindung des Nutzers getrennt wurde (z. B. Sicherheitszurücksetzung). Achte darauf, dass der OAuth-Server des Partners korrekt auf die refresh_token-Anfragen von Google reagiert, um neue Zugriffstokens nahtlos auszustellen.
|
Ja |
EXECUTION_INVALID_JSON |
Die JSON-Antwortnutzlast konnte von Google nicht geparst werden.
Prüfen Sie Ihre Antwort auf Syntaxfehler, fehlende Klammern oder ungültige Zeichen. |
Ja |
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. Verwende requestId in Google Cloud Logging, um die Logs deines Smart-Home-Dienstes zu prüfen.
|
|
INVALID_JSON |
Die Antwortstruktur ist ungültig (z. B. fehlen Pflichtfelder).
Validieren Sie Ihre Antwort anhand der Intent-JSON-Schemas. |
Ja |
MALFORMED_JSON |
Die JSON-Struktur ist fehlerhaft (z. B. nicht geschlossene Strings oder Objekte).
Achten Sie darauf, dass Ihre Auftragsausführung eine Standard-JSON-Bibliothek zum Serialisieren von Antworten verwendet. |
Ja |
NOT_IMPLEMENTED |
Der angeforderte Intent oder das angeforderte Attribut wurde vom Partner nicht implementiert.
Füge in deine SYNC-Antwort nur Attribute ein, die du vollständig implementiert hast.
|
Ja |
OPEN_AUTH_FAILURE |
Das Zugriffstoken des Nutzers ist abgelaufen und Google kann es nicht aktualisieren oder Google hat von deinem Dienst den HTTP-Fehlercode 401 erhalten.
Wenn dieser Code häufiger auftritt, prüfe, ob auch Fehler im Zusammenhang mit Smart-Home-Intents oder Aktualisierungstoken-Anfragen häufiger auftreten. |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
Der zurückgegebene String errorCode ist nicht in der Liste der von Google unterstützten Strings enthalten.
Ordnen Sie Ihre internen Fehler der offiziellen Fehlerliste zu. |
Ja |
PARTNER_RESPONSE_INVALID_PAYLOAD |
Das Feld payload in der Antwort ist kein gültiges JSON-Objekt.
Überprüfe die Stammstruktur deiner Antwort auf die Ausführungsanfrage. |
Ja |
PARTNER_RESPONSE_INVALID_STATUS |
Die Antwort status war nicht SUCCESS, ERROR oder OFFLINE.
Achte darauf, dass jedes Geräteergebnis in deiner Antwort einen gültigen Statusstring enthält. |
Ja |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
Die Antwort enthielt keine Ergebnisse für alle angeforderten Befehle/Geräte.
Prüfe die Antwortstruktur anhand der Google Home-Entwicklerdokumentation. Achten Sie darauf, dass die Antwort nicht abgeschnitten wird oder aufgrund eines internen Serverfehlers ein leerer Text zurückgegeben wird. Für jedes Element im commands-Array der Anfrage muss ein entsprechender Antwort-Eintrag vorhanden sein.
|
Ja |
PARTNER_RESPONSE_MISSING_DEVICE |
Ein von Google angefordertes Gerät wurde in der Antwort weggelassen.
Achten Sie darauf, dass Ihre Antwort alle ID enthält, die in der Nutzlast der Anfrage angegeben sind.
|
Ja |
PARTNER_RESPONSE_MISSING_PAYLOAD |
In der Antwort fehlt das Pflichtfeld „payload“.
Achten Sie darauf, dass Ihr JSON-Objekt auf oberster Ebene einen payload-Schlüssel enthält.
|
Ja |
PARTNER_RESPONSE_NOT_OBJECT |
Die gesamte Antwort konnte nicht als JSON-Objekt geparst werden.
Prüfen Sie, ob der HTTP-Antworttext nachgestellte Zeichen oder Nicht-JSON-Inhalte enthält. Achten Sie darauf, dass payload.commands[] ein gültiges JSON-Objekt mit IDs, Status und optionalen Zuständen ist.
|
Ja |
REQUEST_ID_NOT_FOUND |
Google konnte die interne Tracking-ID für die Anfrage nicht finden.
In der Regel ein interner Plattformfehler. Achten Sie auf Spitzen und wenden Sie sich an den Support. |
Ja |
RESOURCE_UNAVAILABLE |
Die angeforderte Ressource (Gerät oder Attribut) ist nicht verfügbar.
Prüfen Sie, ob das Gerät „Beschäftigt“ ist oder vorübergehend deaktiviert wurde. |
Ja |
RESPONSE_TIMEOUT |
Der Fulfillment-Dienst hat nicht innerhalb von 9 Sekunden geantwortet.
Optimieren Sie die Backend-Latenz. Suchen Sie nach langsamen Datenbankabfragen oder regionalen Netzwerkverzögerungen. |
Ja |
RESPONSE_UNAVAILABLE |
Von der URL für die Auftragsausführung des Partners wurde keine Antwort empfangen.
Prüfen Sie, ob Ihr Dienst ausgeführt wird und der Endpunkt nicht abstürzt. |
Ja |
TIMEOUT |
Bei der Verarbeitung des Intents ist eine allgemeine Zeitüberschreitung aufgetreten.
Prüfe die Logs auf interne Dienstzeitüberschreitungen zwischen deinen Cloud- und Geräte-Hubs. |
Ja |
Suchprotokolle
Sobald 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 Fehlerprotokoll 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 gewünschten Logs zu finden. Abfragen können auf einem Zeitraum, einer Ressource, dem Schweregrad des Logs oder benutzerdefinierten Einträgen basieren.
Sie können die Abfrageschaltflächen verwenden, um benutzerdefinierte Filter zu erstellen.
Wenn Sie einen Zeitraum angeben möchten, klicken Sie auf den Button zur Zeitraumauswahl und wählen Sie eine der verfügbaren Optionen aus. Dadurch werden die Logs gefiltert und nur die Logs angezeigt, die im ausgewählten Zeitraum erstellt wurden.
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, Debug und anderen Schweregraden zu 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"
In der Abfragebibliothek finden Sie weitere Beispiele für effektive Logabfragen.
Fehlerbehebungen testen
Nachdem Sie Fehler identifiziert und Updates zur Behebung angewendet haben, empfehlen wir, die Korrekturen gründlich mit Google Home Test Suite zu testen. Wir stellen ein Nutzerhandbuch zur Verwendung von Test Suite bereit, in dem Sie Schritt für Schritt erfahren, wie Sie Ihre Änderungen effektiv testen.
Lernmaterialien
In diesem Dokument werden die Schritte zur Fehlerbehebung bei Fehlern in deiner Smart-Home-Aktion beschrieben. Weitere Informationen zum Debugging finden Sie in unseren Codelabs:
- Codelab zum Debuggen von Smart-Home-Geräten: Kurzanleitung zum Debuggen der Cloud-Integration von Smart-Home-Geräten.
- Codelab zum Debuggen von Local Home: Kurzanleitung zum Debuggen der lokalen Integration von Smart-Home-Geräten.