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 Nutzerintentionen ein Fehler auftritt, wird dieser Fehler in der Google Home Analytics-Pipeline in Ihren Messwerten erfasst und ein Fehlerlog in den Projektlogs veröffentlicht.
So gehen Sie bei der Fehlerbehebung vor:
- Mit Smart-Home-Messwerten können Sie den Status Ihrer Projekte im Blick behalten.
- Untersuchen Sie Probleme, indem Sie sich die detaillierten Fehlerbeschreibungen in den Fehlerlogs ansehen.
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 im Blick zu behalten, um Unregelmäßigkeiten zu erkennen.
- 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 mit den Anfragen nicht mithalten 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.
Häufige Plattformfehlercodes
Hier sind einige häufige Fehlercodes, die in den 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 kann Maßnahmen ergreifen |
|---|---|---|
AGENT_ISSUE |
Es ist ein allgemeines Problem mit dem Cloud-Agent des Partners aufgetreten.
Prüfe deine Fulfillment-Logs auf nicht abgefangene Ausnahmen oder Abstürze. |
Ja |
AGENT_UNAVAILABLE_ERROR |
Google konnte die Fulfillment-URL des Partners nicht erreichen.
Prüfen Sie, ob Ihr Server online ist, die Firewall Google nicht blockiert und die URL korrekt ist. |
Ja |
BACKEND_FAILURE_URL_TIMEOUT |
Bei dem Versuch, Ihren Dienst zu erreichen, ist es zu einer Zeitüberschreitung bei der Anfrage von Google gekommen.
Prüfen Sie, ob Ihr Dienst online ist, Verbindungen akzeptiert und nicht überlastet 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-Fehlercode 5xx erhalten.
Verwende requestId in Google Cloud Logging, um die Logs deines Smart-Home-Dienstes zu prüfen. Untersuchen Sie Serverabstürze, Zeitüberschreitungen oder 502-/503-Gateway-Fehler.
|
|
COMMAND_FAILED |
Bei der Ausführung eines Befehls ist ein allgemeiner Fehler aufgetreten.
Prüfe deine Fulfillment-Logs auf den spezifischen requestId, um die Ursache zu finden.
|
Ja |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google hat von Ihrem Fulfillment einen HTTP-4xx-Fehler (außer 401) erhalten.
Prüfen Sie die Webserverprotokolle auf die Antworten 403, 404 oder 400. |
Ja |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
Die Fulfillment-URL wird durch robots.txt oder Sicherheitsfilter blockiert.
Achten Sie darauf, dass Ihr Fulfillment-Endpunkt für die Crawler und Dienste von Google zugänglich ist. |
Ja |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google hat von Ihrem Fulfillment-Dienst einen HTTP 5xx-Fehler erhalten.
Prüfen Sie, ob die Endpunkt-URL stabil, korrekt und öffentlich erreichbar ist und der Dienst ausgeführt wird. Fügen Sie Systemdiagnosen und die Verarbeitung von Wiederholungsversuchen hinzu. Serverabstürze, Zeitüberschreitungen oder 502-/503-Gateway-Fehler untersuchen. |
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 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 OAuth angeforderten Bereiche und sorge dafür, dass sie den erforderlichen Attributen entsprechen. |
Ja |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
Die Partner-Cloud gibt an, dass der Nutzer die Verknüpfung seines Kontos aufgehoben hat.
Achte darauf, dass deine agentUserId-Zuordnung stabil ist und nicht entfernt wurde.
|
Ja |
EXECUTION_GAL_NOT_FOUND |
Die in Google gespeicherten Zugriffs- und Aktualisierungstokens des Nutzers sind ungültig oder können nicht aktualisiert werden. Daher ist keine Authentifizierung und kein Zugriff auf den Partnerdienst möglich.
Sorgen Sie dafür, dass Tokens gültig und synchronisiert bleiben, gehen Sie angemessen mit Änderungen des Kontostatus um und fordern Sie Nutzer auf, das Konto neu zu verknüpfen, wenn Tokens widerrufen wurden. |
Ja |
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 ansehen“ befindet. |
Ja |
EXECUTION_GAL_UNLINKED_BY_3P |
Die Verknüpfung mit dem Konto wurde vom Drittanbieterdienst proaktiv aufgehoben.
Untersuche, warum die Verbindung des Nutzers getrennt wurde (z. B. Sicherheitsreset). Der OAuth-Server des Partners muss korrekt auf die refresh_token-Anfragen von Google reagieren, um nahtlos neue Zugriffstokens auszugeben.
|
Ja |
EXECUTION_INVALID_JSON |
Die JSON-Antwortnutzlast konnte von Google nicht geparst werden.
Prüfe deine 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. Mit dem requestId in Google Cloud Logging kannst du die Logs deines Smart-Home-Dienstes 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 für die Serialisierung von Antworten eine Standard-JSON-Bibliothek verwendet wird. |
Ja |
NOT_IMPLEMENTED |
Der angeforderte Intent oder die angeforderte Eigenschaft wurde vom Partner nicht implementiert.
Nimm in deine SYNC-Antwort nur Merkmale auf, 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 Ihrem Dienst den HTTP-Fehlercode 401 erhalten.
Wenn dieser Code häufiger auftritt, prüfen Sie, ob auch Fehler im Zusammenhang mit Smart-Home-Intents oder Aktualisierungstokenanfragen häufiger auftreten. |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
Der zurückgegebene String errorCode ist nicht in der von Google unterstützten Liste 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.
Prüfen Sie die Stammstruktur Ihrer Antwort zur Ausführung. |
Ja |
PARTNER_RESPONSE_INVALID_STATUS |
Die Antwort status war nicht SUCCESS, ERROR oder OFFLINE.
Achten Sie darauf, dass jedes Geräteergebnis in Ihrer Antwort einen gültigen Statusstring enthält. |
Ja |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
Die Antwort enthielt nicht für alle angeforderten Befehle/Geräte Ergebnisse.
Überprüfe die Struktur deiner Antwort anhand der Google Home-Entwicklerdokumentation. Achten Sie darauf, dass die Antwort nicht aufgrund eines internen Serverfehlers abgeschnitten wird oder einen leeren Textkörper zurückgibt. Jeder Artikel im commands-Array der Anfrage muss einen entsprechenden Antworteneintrag haben.
|
Ja |
PARTNER_RESPONSE_MISSING_DEVICE |
Ein bestimmtes von Google angefordertes Gerät wurde in der Antwort nicht berücksichtigt.
Achten Sie darauf, dass Ihre Antwort alle ID enthält, die in der Anfrage-Payload angegeben sind.
|
Ja |
PARTNER_RESPONSE_MISSING_PAYLOAD |
In der Antwort fehlt das Pflichtfeld „payload“.
Achten Sie darauf, dass Ihr JSON-Objekt der obersten 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 den HTTP-Antworttext auf nachgestellte Zeichen oder Inhalte, die nicht im JSON-Format sind. Achten Sie darauf, dass payload.commands[] ein gültiges JSON-Objekt mit IDs, Status und optionalen Statusangaben 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 Merkmal) 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.
Backend-Latenz optimieren: Prüfen Sie, ob langsame Datenbankabfragen oder regionale Netzwerkverzögerungen vorliegen. |
Ja |
RESPONSE_UNAVAILABLE |
Von der Partner-Fulfillment-URL wurde keine Antwort empfangen.
Prüfen Sie, ob Ihr Dienst ausgeführt wird und der Endpunkt nicht abstürzt. |
Ja |
TIMEOUT |
Beim Verarbeiten des Intents ist eine allgemeine Zeitüberschreitung aufgetreten.
Prüfe die Logs auf interne Dienstzeitüberschreitungen zwischen deiner Cloud und den Geräte-Hubs. |
Ja |
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.
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 Logs zu finden. Abfragen können auf einem Zeitbereich, einer Ressource, dem Schweregrad von Logs oder benutzerdefinierten Einträgen basieren.
Mithilfe der Schaltflächen für Abfragen können Sie benutzerdefinierte Filter erstellen.
Klicken Sie auf die Schaltfläche zur Auswahl des Zeitbereichs und wählen Sie eine der verfügbaren Optionen aus, um einen Zeitbereich festzulegen. Dadurch werden die Logs gefiltert und nur 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 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"
Weitere Beispiele für das effektive Abfragen von Logs finden Sie in der Abfragebibliothek.
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 haben eine Anleitung zur Verwendung von Test Suite erstellt, in der Sie erfahren, wie Sie Ihre Änderungen effektiv testen können.
Lernmaterialien
In diesem Dokument wird beschrieben, wie du Fehler in deiner Smart Home-Aktion beheben kannst. Weitere Informationen zum Debugging finden Sie in unseren Codelabs:
- Codelab zur Fehlerbehebung bei Smart Home: Kurzanleitung zur Fehlerbehebung bei der Cloud-Integration für Smart Home.
- Codelab zur Fehlerbehebung bei Local Home: Kurzanleitung zur Fehlerbehebung bei der lokalen Smart-Home-Integration.