Matter-Integrationsfehler beheben

refresh_date: 2023-01-06

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-Fehlerprotokollen beheben können. Wenn bei der Ausführung von Nutzerabsichten ein Fehler auftritt, wird dieser in der Google Home Analytics-Pipeline in Ihren Messwerten erfasst und ein Fehlerprotokoll in Ihren Projektprotokollen veröffentlicht.

Es gibt zwei Schritte zur Fehlerbehebung:

  1. Behalte den Status deiner Projekte mit Smart-Home-Messwerten im Blick.
  2. Untersuchen Sie Probleme, indem Sie sich die detaillierten Fehlerbeschreibungen in den Fehlerlogs ansehen.

Monitoringfehler

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

  • Das Diagramm Success Rate (Erfolgsquote) ist das erste Diagramm, ab dem Sie die Zuverlässigkeit Ihrer Projekte überwachen. 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 überwachen.
  • Die Diagramme zur Fehleraufschlüsselung sind am nützlichsten, wenn es darum geht, Probleme mit Ihren Integrationen zu beheben. 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 mit dem Symbol Google Home platform gekennzeichneten Fehler und Informationen zur Fehlerbehebung.

Plattformfehlercodes

Im Folgenden finden Sie einige häufige Fehlercodes, die in Ihren Projektprotokollen angezeigt werden können, um Probleme zu identifizieren, die von der Google Home platform erkannt wurden. Weitere Informationen zur Fehlerbehebung finden Sie in der folgenden Tabelle.

Fehlercode Beschreibung
BACKEND_FAILURE_URL_ERROR Google hat von Ihrem Dienst einen anderen HTTP-Fehlercode 4xx als 401 erhalten.

Über das requestId in GCP Logging können Sie die Protokolle Ihres Smart-Home-Dienstes prüfen.
BACKEND_FAILURE_URL_TIMEOUT Bei der Anfrage von Google kam es zu einer Zeitüberschreitung, als Sie versucht haben, 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.

Über das requestId in GCP Logging können Sie die Protokolle Ihres Smart-Home-Dienstes prüfen.
DEVICE_NOT_FOUND Das Gerät ist auf der Seite des Partnerdienstes 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 eines ungültigen Formats oder ungültiger Werte in der Nutzlast nicht parsen.

Verwenden Sie die requestId in GCP Logging, um Fehlerprotokolle in Ihrem Kontoverknüpfungsservice zu prüfen.
GAL_INTERNAL Beim Abrufen eines Zugriffstokens ist ein interner Fehler aufgetreten.

Wenn dieser Fehler in den GCP-Logs häufiger auftritt, wenden Sie sich bitte an uns.
GAL_INVALID_ARGUMENT Beim Abrufen eines Zugriffstokens ist ein interner Fehler aufgetreten.

Wenn dieser Fehler in den GCP-Logs häufiger auftritt, wenden Sie sich bitte an uns.
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 neu verknüpfen, um Ihren Dienst weiterhin nutzen zu können.

Wenn dieser Fehler in den GCP-Logs häufiger auftritt, wenden Sie sich bitte an uns.
GAL_PERMISSION_DENIED Ein interner Google-Fehler ist aufgetreten, weil die Tokenfreigabe nicht autorisiert ist.

Wenn Sie eine erhöhte Fehlerrate in GCP Logging feststellen, kontaktieren Sie uns für weitere Informationen.
GAL_REFRESH_IN_PROGRESS Das Zugriffstoken des Nutzers ist abgelaufen und ein weiterer gleichzeitiger Aktualisierungsversuch ist bereits im Gange.

Dies ist kein Problem und Sie müssen nichts unternehmen.
INVALID_AUTH_TOKEN Google hat von Ihrem Dienst den HTTP-Fehlercode 401 erhalten.

Das Zugriffstoken ist nicht abgelaufen, wurde aber von deinem Dienst ungültig gemacht. Über das Dreistrich-Menü requestId in GCP Logging können Sie die Protokolle Ihres Smart-Home-Dienstes prüfen.
INVALID_JSON Die JSON-Antwort kann nicht geparst oder verstanden 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 Google kann es nicht aktualisieren oder Google hat von Ihrem Dienst einen HTTP-401-Fehlercode erhalten.

Wenn dieser Code häufiger auftritt, prüfen Sie, ob auch die Anzahl der Fehler im Zusammenhang mit Smart-Home-Intents oder Aktualisierungstokenanfragen zugenommen hat.
PARTNER_RESPONSE_INVALID_ERROR_CODE Die Antwort enthält einen unbekannten Fehlercode.

Wenn die Antwort auf deine Anfrage einen Fehler anzeigt, verwende einen der unterstützten Fehlercodes.
PARTNER_RESPONSE_INVALID_PAYLOAD Das Feld „payload“ in der Antwort kann nicht als JSON-Objekt geparst werden.

Prüfen Sie, ob das Nutzlastfeld in Ihrer Antwort auf die Anfrage über übereinstimmende Klammern verfügt 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-Ausführung sollten einen Status mit SUCCESS, OFFLINE, ERROR, EXCEPTIONS angeben. Weitere Informationen zum Umgang mit Fehlern und Ausnahmen finden Sie hier.
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES Mindestens ein in der Anfrage vorhandener Intent fehlt in der Antwort.

Prüfen Sie, ob Ihre Ausführungsantwort korrekt strukturiert ist und ob die Ergebnisse für alle Intents aus der Anfrage in Ihrer Antwort enthalten sind.
PARTNER_RESPONSE_MISSING_DEVICE Ein oder mehrere in der Anfrage vorhandene Geräte fehlen in der Antwort.

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

Die Antwort auf die Anfrage muss ein Nutzlastfeld enthalten. Hier finden Sie weitere Informationen zum Erstellen einer korrekten Ausführungsantwort.
PARTNER_RESPONSE_NOT_OBJECT Die Antwort kann nicht als JSON-Objekt geparst werden.

Prüfe alle Felder in der Antwort auf unerwünschte Zeichen, nicht übereinstimmende Klammern oder Formatierungsfehler. Einige Unicode-Zeichen werden möglicherweise nicht unterstützt. Achte außerdem darauf, dass deine Antwort korrekt als JSON-Objekt strukturiert ist.
PROTOCOL_ERROR Fehler bei der Verarbeitung der Anfrage.

Mit der requestId in Google Cloud Logging können Sie die Protokolle Ihres Smart-Home-Dienstes prüfen.
RESPONSE_TIMEOUT Zeitüberschreitung beim Warten auf die Antwort.

Das Zeitlimit für das Senden einer Antwort beträgt 9 Sekunden ab dem Zeitpunkt, an dem die Anfrage gesendet wird. Sie müssen innerhalb dieses Zeitraums antworten.
RESPONSE_UNAVAILABLE Es wird keine Antwort empfangen oder die Antwort enthält keinen Status.

Antworten auf Anfragen zur Intent-Erfüllung sollten gemäß den Smart-Home-Dokumenten strukturiert sein und den Status angeben.
TRANSIENT_ERROR Ein vorübergehender Fehler ist ein Fehler, der sich von selbst behebt.

In den meisten Fällen entstehen diese Fehler durch eine Verbindung zu einem unterbrochenen Gerät oder Dienst. Auch wenn neue Verbindungen zu einem Server nicht geöffnet werden können.

Suchprotokolle

Sobald Sie mit dem Überwachen Ihrer Integrationen anhand von Messwerten vertraut sind, können Sie mithilfe von Cloud Logging bestimmte Fehler beheben. Ein Fehlerprotokoll ist ein JSON-ähnlicher Eintrag mit Feldern, die nützliche Informationen wie Uhrzeit, Fehlercode und Details zur ursprünglichen Smart-Home-Intent enthalten.

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

Cloud-Logs abfragen

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

Cloud-Logabfragen erstellen

Wenn Sie einen Zeitraum festlegen möchten, klicken Sie auf die Schaltfläche zur Zeitraumauswahl und wählen Sie eine der verfügbaren Optionen aus. Dadurch werden die Logs gefiltert und nur die Logs angezeigt, die aus dem ausgewählten Zeitraum stammen.

Klicken Sie zum Angeben einer Ressource auf das Drop-down-Menü Ressource und wählen Sie Google Assistant Action Project aus. Dadurch wird der Abfrage ein Filter hinzugefügt, mit dem Logs angezeigt werden, die aus Ihrem Projekt stammen.

Über die Schaltfläche Schweregrad können Sie nach Notfall, Info, Fehlerbehebung und anderen Schweregrad-Logebenen filtern.

Sie können auch das Abfragefeld in der Logs Explorer verwenden, um benutzerdefinierte Einträge einzugeben. Die von diesem Feld verwendete Abfragemaschine unterstützt sowohl grundlegende Abfragen wie den Stringabgleich als auch erweiterte 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 Abfragen von Protokollen.

Korrekturen testen

Nachdem Sie Fehler gefunden und Updates zur Behebung angewendet haben, empfehlen wir Ihnen, die Fehlerbehebungen gründlich mit Google Home Test Suite zu testen. In unserer Anleitung zur Verwendung von Test Suite erfahren Sie, wie Sie Ihre Änderungen effektiv testen.

Lernmaterialien

In diesem Dokument finden Sie Schritte zur Fehlerbehebung bei Smart-Home-Aktionen. Weitere Informationen zum Debuggen finden Sie in unseren Codelabs:

Zurück
Cloud Logging für Matter