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. Behalten Sie den Status Ihrer Projekte mit Smart-Home-Messwerten im Blick.
  2. Prüfen Sie die detaillierten Fehlerbeschreibungen in den Fehlerprotokollen, um Probleme zu untersuchen.

Monitoringfehler

Sie können Google Cloud Monitoring dashboards verwenden, um auf Ihre Projektmesswerte zuzugreifen. Es gibt einige wichtige Diagramme, die sich besonders für die Überwachung der Qualität und die Fehlerbehebung eignen:

  • Das Diagramm Erfolgsquote ist das erste Diagramm, mit dem Sie beginnen 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 Ihnen, dieses Diagramm nach jeder Änderung oder Aktualisierung Ihres Projekts genau auf Unregelmäßigkeiten zu prüfen.
  • 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 Prozentsatz der erfolgreichen Anzeigen hervorgehoben wird, 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-4xx-Fehlercode 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 dem Versuch, Ihren Dienst zu erreichen, ist bei der Anfrage von Google eine Zeitüberschreitung aufgetreten.

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 in der Regel auf einen Fehler bei der Datensynchronisierung oder einen Race-Condition 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 Zugriffs- 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 dieser Fehler in den GCP-Logs häufiger auftritt, wenden Sie sich bitte an uns.
GAL_REFRESH_IN_PROGRESS Das Zugriffstoken des Nutzers ist abgelaufen und ein weiterer gleichzeitiger Aktualisierungsversuch ist bereits in Bearbeitung.

Das 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 aufrufen.
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 Sie eine erhöhte Rate dieses Codes feststellen, 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 enthält keinen oder einen falschen Status.

Antworten auf Anfragen zur Intent-Ausführung sollten einen Status mit SUCCESS, OFFLINE, ERROR, EXCEPTIONS angeben. Weitere Informationen zur Fehler- und Ausnahmebehandlung finden Sie unter Fehler- und Ausnahmebehandlung.
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES In der Antwort fehlt mindestens eine der in der Anfrage vorhandenen Absichten.

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 In der Antwort fehlt mindestens ein Gerät, das in der Anfrage vorhanden ist.

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 richtig als JSON-Objekt strukturiert ist.
PROTOCOL_ERROR Fehler bei der Verarbeitung der Anfrage.

Mit dem 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 äußern sich diese Fehler in Form einer unterbrochenen Verbindung zu einem 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 angeben möchten, klicken Sie auf die Schaltfläche zum Auswählen des Zeitraums  und wählen Sie eine der verfügbaren Optionen aus. Dadurch werden die Protokolle gefiltert und nur die 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 Protokollebenen für den Schweregrad 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