Matter-Integrationsfehler beheben

refresh_date: 2023-01-06

Google Cloud bietet Ihnen die Tools, mit denen Sie die Zuverlässigkeit Ihrer Projekte überwachen können mit Google Cloud Monitoring und Probleme mit Google Cloud Logging Fehlerlogs beheben können. Wenn beim Ausführen von Nutzerabsichten ein Fehler auftritt, wird dieser von der Google Home Analytics-Pipeline in Ihren Messwerten erfasst und ein Fehlerlog in den Projektlogs veröffentlicht.

Es gibt zwei Schritte zur Fehlerbehebung:

  1. Überwachen Sie den Status Ihrer Projekte mit Smart-Home-Messwerten.
  2. Untersuchen Sie Probleme, indem Sie die detaillierten Fehlerbeschreibungen in den Fehlerlogs prüfen.

Fehler überwachen

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

  • Das Diagramm Erfolgsrate ist das erste, das Sie bei der Überwachung der Zuverlässigkeit Ihrer Projekte verwenden sollten. Ein Rückgang in diesem Diagramm kann auf einen Ausfall für einen Teil oder alle Ihrer Nutzer hinweisen. Wir empfehlen, dieses Diagramm nach jeder Änderung oder Aktualisierung Ihres Projekts genau zu beobachten.
  • Die Diagramme Fehleraufschlüsselung sind am nützlichsten, wenn es um die Behebung von Problemen bei Ihren Integrationen geht. Für jeden Fehler, der im Diagramm zur Erfolgsrate hervorgehoben wird, wird in der Fehleraufschlüsselung ein Fehlercode angezeigt. In der folgenden Tabelle sehen Sie die von der Google Home platform gemeldeten Fehler und wie Sie sie beheben können.

Häufige Fehlercodes der Plattform

Hier sind einige häufige Fehlercodes, die in Ihren Projektlogs angezeigt werden können, um Probleme zu identifizieren, die von der Google Home platformerkannt wurden. Informationen zur Fehlerbehebung finden Sie in der folgenden Tabelle. Eine vollständige Liste der Fehlercodes finden Sie unter Fehler und Ausnahmen .

Fehlercode Beschreibung Partnermaßnahme
AGENT_ISSUE Es ist ein allgemeines Problem mit dem Cloud-Agent des Partners aufgetreten.

Prüfen Sie Ihre Fulfillment-Logs auf nicht behandelte 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 Google-Anfrage gekommen.

Prüfen Sie, ob Ihr Dienst online ist, Verbindungen akzeptiert, und nicht überlastet ist. Prüfen Sie außerdem, ob das Ziel Gerät eingeschaltet, online und synchronisiert ist.
BACKEND_FAILURE_URL_UNREACHABLE Google hat von Ihrem Dienst einen HTTP-Fehlercode 5xx erhalten.

Verwenden Sie die requestId in Google Cloud Logging, um die Logs Ihres 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.

Suchen Sie in Ihren Fulfillment-Logs nach der spezifischen requestId , um die Ursache zu finden. 		Ja
EXECUTION_BACKEND_FAILURE_URL_ERROR Google hat von Ihrem Fulfillment einen HTTP-Fehler 4xx (außer 401) erhalten.

Prüfen Sie Ihre Webserver-Logs auf 403-, 404- oder 400-Antworten. 		Ja
EXECUTION_BACKEND_FAILURE_URL_ROBOTED Die Fulfillment-URL wird durch robots.txt oder Sicherheitsfilter blockiert.

Achten Sie darauf, dass der Fulfillment-Endpunkt für die Crawler/Dienste von Google zugänglich ist. 		Ja
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE Google hat von Ihrem Fulfillment-Dienst einen HTTP-Fehler 5xx erhalten.

Achten Sie darauf, dass der Endpunkt-URL-Dienst stabil, korrekt und öffentlich erreichbar ist und der Dienst ausgeführt wird. Fügen Sie Systemdiagnosen und die 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 den Intent-Schemas entspricht. 		Ja
EXECUTION_GAL_BAD_3P_RESPONSE Die Kontoverknüpfung ist aufgrund eines ungültigen Formats in der Token-Antwort 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üfen Sie die während OAuth angeforderten Bereiche und achten Sie darauf, dass sie den erforderlichen Merkmalen entsprechen. 		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 Zuordnung von agentUserId stabil ist und nicht gelöscht wurde. 		Ja
EXECUTION_GAL_NOT_FOUND Die in Google gespeicherten Zugriffs- und Aktualisierungstokens des Nutzers sind ungültig oder können nicht aktualisiert werden. Dadurch wird die Authentifizierung und der Zugriff auf den Partnerdienst verhindert.

Achten Sie darauf, dass die Tokens gültig und synchronisiert bleiben, behandeln Sie Änderungen des Kontostatus entsprechend und fordern Sie Nutzer auf, die Kontoverknüpfung wiederherzustellen, wenn die 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 Kontoverknüpfung wurde proaktiv durch den Drittanbieterdienst aufgehoben.

Untersuchen Sie, warum die Verbindung des Nutzers getrennt wurde (z. B. Sicherheit Reset). Achten Sie darauf, dass der OAuth-Server des Partners korrekt auf die refresh_token Anfragen von Google antwortet, um nahtlos neue Zugriffstokens auszugeben. 		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 einen HTTP-Fehlercode 401 erhalten.

Das Zugriffstoken ist nicht abgelaufen, wurde aber von Ihrem Dienst für ungültig erklärt. Verwenden Sie die requestId in Google Cloud Logging, um die Logs Ihres Smart-Home-Dienstes zu prüfen.
INVALID_JSON Die Antwortstruktur ist ungültig (z. B. fehlen Pflichtfelder ).

Validieren Sie Ihre Antwort anhand der JSON-Schemas für Intents. 		Ja
MALFORMED_JSON Die JSON-Struktur ist fehlerhaft (z. B. nicht geschlossene Strings oder Objekte).

Achten Sie darauf, dass Ihr Fulfillment eine Standard-JSON-Bibliothek verwendet, um Antworten zu serialisieren. 		Ja
NOT_IMPLEMENTED Der angeforderte Intent oder das angeforderte Merkmal wurde vom Partner nicht implementiert.

Fügen Sie Ihrer SYNC Antwort nur Merkmale hinzu, die Sie vollständig implementiert haben. 		Ja
OPEN_AUTH_FAILURE Das Zugriffstoken des Nutzers ist abgelaufen und Google kann es nicht aktualisieren, oder Google hat von Ihrem Dienst einen HTTP-Fehlercode 401 erhalten.

Wenn Sie eine erhöhte Rate dieses Codes feststellen, prüfen Sie, ob auch die Rate der Fehler im Zusammenhang mit Smart-Home-Intents oder Anfragen zur Aktualisierung von Tokens gestiegen ist.
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 Root-Struktur Ihrer Fulfillment-Antwort. 		Ja
PARTNER_RESPONSE_INVALID_STATUS Der status der Antwort war nicht SUCCESS, ERROR oder OFFLINE.

Achten Sie darauf, dass jedes Geräteresultat in Ihrer Antwort einen gültigen Status string enthält. 		Ja
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES Die Antwort enthielt keine Ergebnisse für alle angeforderten Befehle/Geräte.

Validieren Sie Ihre Antwortstruktur anhand der Google Home-Entwickler dokumentation. Achten Sie darauf, dass die Antwort aufgrund eines internen Serverfehlers nicht abgeschnitten wird oder einen leeren Textkörper zurückgibt. Jedes Element im `commands`-Array der Anfrage muss einen entsprechenden Antworteintrag haben.commands 		Ja
PARTNER_RESPONSE_MISSING_DEVICE Ein bestimmtes von Google angefordertes Gerät wurde aus der Antwort ausgelassen.

Achten Sie darauf, dass Ihre Antwort jede ID enthält, die in der Anfrage-Nutzlast angegeben ist. 		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 Textkörper Ihrer HTTP Antwort auf nachfolgende Zeichen oder Nicht-JSON-Inhalte. Achten Sie darauf, dass payload.commands[] ein korrektes 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.

Normalerweise ein interner Plattformfehler. Beobachten Sie, ob es zu Spitzen kommt, 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.

Optimieren Sie die Back-End-Latenz. Prüfen Sie, ob langsame Datenbankabfragen oder regionale Netzwerkverzögerungen vorliegen. 		Ja
RESPONSE_UNAVAILABLE Von der Fulfillment-URL 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üfen Sie die Logs auf interne Dienstzeitüberschreitungen zwischen Ihren Cloud- und Gerätehubs. 		Ja

Suchprotokolle

Sobald Sie sich mit der Überwachung Ihrer Integrationen mithilfe von Messwerten vertraut gemacht haben, können Sie mit Cloud Logging bestimmte Fehler beheben.Cloud Logging 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 ständig 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, Ressource, dem Schweregrad des Logs oder benutzerdefinierten Einträgen basieren.

Cloud-Logs abfragen

Mit den Abfrageschaltflächen können Sie benutzerdefinierte Filter erstellen.

Cloud-Log-Abfragen erstellen

Wenn Sie einen Zeitraum angeben 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 nur die Logs angezeigt, die im ausgewählten Zeitraum erstellt wurden.

Wenn Sie eine Ressource angeben möchten, klicken Sie auf das Ressource-Drop-down-Menü, 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 der Logs Explorer verwenden, um benutzerdefinierte Einträge einzugeben. Die von diesem Feld verwendete Abfrage-Engine unterstützt sowohl einfache Abfragen wie String-Abgleich als auch erweiterte Abfragetypen, einschließlich Vergleichsoperatoren (<, >=, !=) und boolescher Operatoren (AND, OR, NOT).

Mit dem folgenden benutzerdefinierten Eintrag werden beispielsweise Fehler zurückgegeben, die von einem Gerät des Typs LIGHT stammen:

resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"

Besuchen Sie die Abfragebibliothek um weitere Beispiele für das effektive Abfragen von Logs zu finden.

Korrekturen testen

Nachdem Sie Fehler identifiziert und Updates zur Behebung angewendet haben, empfehlen wir, Ihre Korrekturen mit der Google Home Test Suite gründlich zu testen.Google Home Test Suite Wir bieten eine Bedienungsanleitung zur Verwendung von Test Suite, in der Sie erfahren, wie Sie Ihre Änderungen effektiv testen.

Lernmaterialien

In diesem Dokument werden die Schritte zur Fehlerbehebung in Ihrer Smart-Home-Aktion beschrieben. Weitere Informationen zur Fehlerbehebung finden Sie in unseren Codelabs:

Zurück
Cloud Logging für Matter