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.
Die Fehlerbehebung erfolgt in zwei Schritten:
- 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 für die Qualitätsüberwachung und das Debugging sind:
- 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 (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 |
|---|---|---|
ACTION_NOT_AVAILABLE |
Der Befehl ist für den aktuellen Status des Geräts ungültig (z. B. „Stelle die Temperatur ein“, während das Gerät aus ist).
Prüfe die Geräteattribute und die Logik für den aktuellen Status in deiner Ausführung. |
Ja |
AGENT_ISSUE |
Es ist ein allgemeines Problem mit dem Cloud-Agent des Partners aufgetreten.
Prüfe deine Fulfillment-Logs auf unbehandelte 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 |
APP_LAUNCH_FAILED |
Die Drittanbieter-App konnte auf dem Zielgerät nicht gestartet werden.
Prüfe die App-ID und ob die App auf der Zielhardware unterstützt wird. |
Ja |
AUTH_EXPIRED |
Das OAuth-Zugriffstoken ist abgelaufen und kann nicht aktualisiert werden.
Prüfen Sie die Aktualisierungstokenrotation und stellen Sie sicher, dass der Nutzer den Zugriff nicht widerrufen hat. |
Ja |
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ü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.
|
|
CHANNEL_SWITCH_FAILED |
Das Gerät konnte nicht zum angeforderten Media-Kanal wechseln.
Prüfe die Kanalnamen/-nummern und den Abostatus des Nutzers. |
Ja |
CHARGER_ISSUE |
Das Gerät meldet ein Hardwareproblem mit dem Ladesystem.
Partner sollten die Telemetrie auf Hardwareebene und den Akkuzustand untersuchen. |
Ja |
CHECK_PARTNER_APP |
Der Nutzer muss die App des Partners öffnen, um den Fehler zu beheben.
Verwende diesen Code für Fehler, die eine komplexe UI-Interaktion erfordern (z. B. Firmware-Updates). |
Ja |
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 |
COMMAND_INSERT_FAILED |
Google konnte den Befehl für das Gerät nicht in die Warteschlange stellen oder verarbeiten.
Datenbank-Schreibleistung oder interne Logik für die Befehlswarteschlange untersuchen. |
Ja |
DEVICE_NOT_FOUND |
Die Geräte-ID in der Anfrage ist auf Partnerseite nicht vorhanden.
Achte darauf, dass in deiner Cloud ein requestSync ausgelöst wird, wenn ein Nutzer Geräte hinzufügt oder löscht.
|
Ja |
ERROR_STATUS |
Die Antwort enthielt einen unspezifischen „ERROR“-Status ohne Code.
Fügen Sie immer einen bestimmten errorCode-String ein, um die TTS-Ausgabe für Nutzer und die Dashboarddaten zu verbessern.
|
Ja |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google hat von Ihrem Fulfillment einen HTTP-Fehler 4xx (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.
Serverabstürze, Zeitüberschreitungen oder 502-/503-Gateway-Fehler untersuchen. |
Ja |
EXECUTION_BAILOUT_INVALID_RESPONSE |
Das JSON-Format der 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_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). |
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 |
FAULTY_BATTERY |
Die Gerätehardware meldet, dass der Akku defekt oder leer ist.
Weise den Nutzer per TTS oder App an, die physische Batterie zu ersetzen. |
Ja |
FUNCTION_NOT_SUPPORTED |
Der angeforderte Modus oder die angeforderte Funktion wird vom Gerät nicht unterstützt.
Achte darauf, dass die SYNC-Antwort die Funktionen des Geräts korrekt widerspiegelt.
|
Ja |
HARD_ERROR |
Ein nicht vorübergehender Fehler, der nicht ohne manuelles Eingreifen behoben werden kann.
Verwenden Sie diese Option bei dauerhaften Hardwarefehlern oder nicht wiederherstellbaren Kontostatus. |
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 |
LOCK_FAILURE |
Das Smart Lock konnte nicht in den angeforderten Status versetzt werden.
Untersuche, ob die Schloss-Hardware blockiert ist, die Stromversorgung schwach ist oder der Motor defekt ist. |
Ja |
MALFORMED_JSON |
Die JSON-Struktur ist fehlerhaft (z. B. nicht geschlossene Strings oder Objekte).
Achte darauf, dass für die Serialisierung von Antworten eine Standard-JSON-Bibliothek verwendet wird. |
Ja |
MISSING_STATE |
Die QUERY-Antwort enthielt nicht den angeforderten Gerätestatus.
Achten Sie darauf, dass alle in SYNC definierten Merkmale in jeder QUERY-Antwort berücksichtigt werden.
|
Ja |
NETWORK_PROFILE_NOT_RECOGNIZED |
Das angeforderte Netzwerkprofil ist dem Gerät nicht bekannt.
Prüfen Sie, ob der Profilnamensstring mit den unterstützten Profilen in der SYNC-Antwort übereinstimmt.
|
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 |
OAUTH_RECONNECT_CALL_TO_ACTION |
Löst eine Benachrichtigung für den Nutzer aus, damit er sein Konto neu verknüpft.
Verwenden Sie diese Option, wenn die Sitzung eines Nutzers ungültig ist und eine manuelle OAuth-Neuauthentifizierung erforderlich ist. |
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 errorCode-String 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 Erfüllungsantwort. |
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.
Jedes Element 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. |
Ja |
PROTOCOL_ERROR |
Im zugrunde liegenden Kommunikationsprotokoll ist ein Fehler aufgetreten.
Untersuchen Sie Probleme mit HTTP-Headern oder SSL/TLS-Handshake-Fehler. |
Ja |
RELINK_REQUIRED |
Der Nutzer muss sein Konto neu verknüpfen, um die Integration weiterhin nutzen zu können.
Achten Sie darauf, dass Ihr Server diesen Code zurückgibt, wenn ein Aktualisierungstoken dauerhaft ungültig 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 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 |
SCENE_CANNOT_BE_APPLIED |
Die angeforderte Szene konnte nicht aktiviert werden (z. B. weil Geräte fehlen).
Prüfe den internen Zustand der Szenen des Nutzers in der Partner-Cloud. |
Ja |
STREAM_UNPLAYABLE |
Der Kamerastream konnte nicht gestartet werden oder ist fehlgeschlagen.
Prüfen Sie die WebRTC-/HLS-Signalisierung und achten Sie darauf, dass die Stream-URL gültig ist. |
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 |
TRANSIENT_ERROR |
Ein vorübergehender Fehler ist ein Fehler, der sich von selbst behebt.
Diese Fehler äußern sich in der Regel 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. |
|
UNABLE_TO_LOCATE_DEVICE |
Das Gerät konnte mit dem Locator-Trait nicht gefunden werden (z. B. Ping fehlgeschlagen).
Prüfe die lokale Verbindung des Geräts (WLAN/Bluetooth). |
Ja |
UNABLE_TO_RING_DEVICE |
Das Gerät wurde erreicht, aber die Klingel-/Alarmfunktion konnte nicht ausgelöst werden.
Prüfe den Alarm-/Lautsprecherstatus und die Lautstärkepegel der Hardware. |
Ja |
UNABLE_TO_SILENCE_DEVICE |
Das Gerät konnte den aktiven Alert/das Klingeln nicht beenden.
Kommunikationsfehler zwischen der Cloud und dem physischen Gerät untersuchen. |
Ja |
UNEXPECTED_ERROR_CHECK_DEVICE_APP |
Es ist ein unvorhergesehener Fehler aufgetreten. Der Nutzer sollte die Partner-App prüfen.
Wird als Auffangbecken für Fehler ohne spezifisches, von Google unterstütztes Äquivalent verwendet. |
Ja |
UNKNOWN_ERROR |
Ein allgemeiner Fehler ohne zusätzliche Details.
Dieser Fehlercode sollte durch spezifischere Fehlercodes ersetzt werden, um die Fehlerbehebung zu verbessern. |
Ja |
UNLOCK_FAILURE |
Das Smart Lock konnte nicht entriegelt werden.
Untersuche Hardware-Blockierungen, niedrigen Akkustand oder ungültige PIN-Eingaben. |
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, mit dem Logs angezeigt werden, 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 für 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.