1. Hinweis
Dieses Codelab richtet sich an Google Home-Partner und ‑Entwickler mit Cloud-Integrationen, die die Qualität des Ökosystems und die Nutzerfreundlichkeit verbessern möchten.
Lerninhalte
Das Google Home Vitals-Dashboard ist die zentrale Informationsquelle für Entwickler und Partner, um den Betriebsstatus ihrer Google Home-Integrationen zu überwachen. In einem Ökosystem, in dem die Nutzerfreundlichkeit durch Latenz und Zuverlässigkeit definiert wird, ist Google Home Vitals das Self-Service-Portal mit allen detaillierten Analysen, die für den Übergang von der reaktiven Fehlerbehebung zur proaktiven Qualitätssicherung erforderlich sind.
- So wird die Punktzahl für die Qualität der Integration berechnet
- Dashboard lesen und verwenden
- Probleme mit Messwerten von schlechter Qualität beheben
Voraussetzungen
- Google Home Cloud-Integration
Einrichtung
So rufen Sie das Google Home-Dashboard für Vitalparameter auf:
- Google Cloud Platform öffnen
- „Monitoring“ > Dashboard
- Klicken Sie auf das Dashboard „Google Home Vitals (Cloud)“.
2. Dashboard lesen
Berechnung des Qualitätsfaktors – Standard „Gut“ im Vergleich zu „Schlecht“
Im Dashboard wird die Aufschlüsselung für die Qualitätsbewertung erläutert. Qualitätsfaktoren werden auf Geräteebene zugewiesen. Damit eine Geräteintegration als GUT gilt, müssen vier gleichzeitige Kriterien erfüllt sein:
- Globale Erfolgsrate:Die globale Erfolgsrate für Partner-zu-Google-Anrufe muss mindestens 99,5 % betragen.
Hinweis:Wenn die globale Erfolgsrate (mindestens 99,5%) nicht erreicht wird, wird das gesamte Projekt automatisch mit SCHLECHT bewertet, unabhängig von der Leistung der einzelnen Geräte. - Befehlszuverlässigkeit:Die Erfolgsraten für QUERY und EXECUTE müssen für jeden Gerätetyp mindestens 99,5% betragen.
- Reaktionslatenz:Die Latenz im 90. Perzentil für QUERY und EXECUTE muss für jeden Gerätetyp ≤ 1.000 ms sein.
- Integrität des Status:Die Statusgenauigkeit muss mindestens 99,5 % betragen.
Warum diese Messwerte wichtig sind
- Globale Erfolgsrate:Anrufe von Partnern an Google auf Integrationsebene messen den Zustand von Anrufen von Ihrer Cloud an Google. Eine Erfolgsrate von mindestens 99,5% sorgt dafür, dass Google Home die richtigen Gerätestatus verwendet. Dazu gehört beispielsweise, dass Geräte hinzugefügt und entfernt werden, dass Automatisierungen ausgelöst werden und dass Verlaufsereignisse auf dem Tab „Aktivität“ der Google Home App angezeigt werden.
- Befehlszuverlässigkeit:Die Erfolgsraten für QUERY und EXECUTE werden auf Geräteebene gemessen.Eine Erfolgsrate von mindestens 99,5% sorgt dafür, dass die Befehle Ihrer Nutzer korrekt ausgeführt werden.So werden Assistant-Antworten wie „Ich kann das Gerät nicht erreichen“ oder die fälschliche Bestätigung eines Befehls, der nicht ausgeführt wurde, vermieden.
- Reaktionszeit:Die Latenzen für QUERY und EXECUTE werden auch auf Geräteebene gemessen. Eine Latenz von <=1000 ms pro Gerätetyp sorgt dafür, dass Nutzer nicht zu lange auf die gewünschte Aktion warten müssen (z. B. einige Sekunden, bis das Licht ausgeschaltet wird).
- Statusintegrität:Mit dieser Messung wird die Genauigkeit des in Google-Systemen gespeicherten Status gemessen, der zur Bearbeitung von Nutzeranfragen verwendet wird. Wenn diese Zahlen niedrig sind, sehen Nutzer möglicherweise falsche Ergebnisse für Ihre Geräte, wenn sie den Status Ihres Geräts aufrufen oder KI-Funktionen wie „Frag Home“ verwenden. Automatisierungen werden möglicherweise nicht ausgelöst und Verlaufsereignisse werden möglicherweise nicht rechtzeitig in „Aktivität“ angezeigt.
Dashboard lesen
Beginnen Sie mit dem Abschnitt „Messwerte für den Qualitätsfaktor“, der als primärer Indikator für die Integrität Ihrer Integration dient. Eine GUTE Bewertung auf Geräteebene ist davon abhängig, dass alle Messwerte in diesem Abschnitt die GRÜNEN Erfolgskriterien erfüllen. Ausführliche technische Anforderungen und Messwertdefinitionen finden Sie in der Dokumentation im Developer Center.
Im Abschnitt „Qualitätsmesswerte“ oben im Google Home Vitals-Dashboard sehen Sie die Messwerte, die zur Berechnung des Qualitätsfaktors Ihrer Integration verwendet werden.
Legende
- GRÜN (GUT): Der Messwert entspricht dem Qualitätsschwellenwert.
- ROT (SCHLECHT): Der Messwert erfüllt den Qualitätsschwellenwert nicht.
Beispiel
Im folgenden Beispiel sehen Sie, dass der Gerätetyp AC_UNIT die Qualitätskriterien im Abschnitt „QUERY- und EXECUTE-Erfolgsrate“ sowie im Abschnitt „QUERY-Latenz“ erfüllt, aber die EXECUTE-Latenz nicht (roter Balken). Das bedeutet, dass Befehle mit einer ausreichenden Rate ausgeführt werden, die EXECUTE-Latenz aber 36 ms zu langsam ist. Im Abschnitt „System Health“ wird eine Fehlerrate von 98,92% für aggregierte Methoden in der gesamten Integration angezeigt.Das bedeutet, dass es Verbesserungsmöglichkeiten gibt, um die Genauigkeit der Gerätestatus von Nutzern für Google Home zu verbessern. Das bedeutet, dass bei 1,08% der Anrufe (DeleteAgentUser, Query, ReportStateAndNotification, RequestSyncDevices oder Sync) Antwortcodes zurückgegeben werden, die nicht 2xx oder 5xx entsprechen (z.B. 404-Fehler). Der letzte Messwert, der zur Messung der Qualität von „Bestanden“/„Nicht bestanden“ für den Gerätetyp „AC_UNIT“ verwendet wird, ist die Statusgenauigkeit. In diesem Beispiel liegt die Erfolgsrate bei 77, 43 %. Das bedeutet, dass Nutzer wahrscheinlich ungenaue Ergebnisse für Geräte sehen. Anhand dieser drei Messwerte ergibt sich für AC_UNIT ein Gesamtwert von POOR, der unter dem Qualitätsschwellenwert liegt.
Jede dieser Qualitätsberechnungen entspricht einem der folgenden Debugging-Abschnitte. Maximieren Sie die minimierten Schritte, um die Fehlerbehebung fortzusetzen.
Informationen zum Debuggen von Erfolgsraten und Latenzen für QUERY/EXECUTE finden Sie unter „Schritt 1: Cloud-Aufrufe validieren“.
Informationen zum Debuggen von Erfolgsraten für Partner-zu-Google-Anrufe finden Sie unter „Schritt 2: Anrufe an Google validieren“.
Informationen zum Debuggen der Statusgenauigkeit für die einzelnen Gerätetypen findest du unter „Schritt 3: Statusgenauigkeit verbessern“.
3. Schritt 1 zur Fehlerbehebung: Cloud-Aufrufe validieren
Schritt 1: Übersicht
In diesem Abschnitt geht es um Cloud-Aufrufe, also die Messwerte, mit denen der Zustand der Kommunikation von Google zu Ihrem Cloud-Backend gemessen wird (auch als Google-zu-Partner-Messwerte bezeichnet). Dazu gehören Befehle wie Query (Abfrage) und Execute (Ausführen).
Wir erfassen Erfolgsraten und Latenzen für QUERY und EXECUTE, die in die Qualitätswerte für den Gerätetyp einfließen.
Die folgende Übersicht zeigt die aggregierten Erfolgsraten und Fehler für QUERY und EXECUTE auf Integrationsebene. In den Schritten 1a bis 1d wird die Aufschlüsselung dieser Messwerte auf Geräteebene/Eigenschaftsebene dargestellt. 
In Schritt 1a und 1b sehen Sie den Trend der Anzahl der Erfüllungsanfragen, die Anzahl der Fehler im Zeitverlauf und bestimmte Fehlerstatus.
Schritt 1a: Fehler bei Abfragen prüfen
Schritt 1b: Ausführungsfehler prüfen
In Schritt 1c und 1d sehen Sie die Aufschlüsselung des 90. und 50. Perzentils für diese Messwerte sowohl auf Integrationsebene als auch auf Geräteebene.
Schritt 1c: Abfragelatenz überprüfen
Schritt 1d: Ausführungslatenz überprüfen
4. Debugging – Schritt 2: Aufrufe an Google validieren
Schritt 2: Übersicht
Nachdem Sie Aufrufe von Google an den Partner debuggt haben, geht es in diesem zweiten Schritt darum, Aufrufe von der Partner-Cloud an Google zu debuggen. In diesem Abschnitt werden Messwerte auf Partnerintegrationsebene behandelt, nicht auf Geräteebene. Dazu gehören Antwortcodes wie 400 Bad Request, 404 Not Found und 429 Resource Exhausted.
Schritt 2a: Kontingentprobleme beheben
Google Home begrenzt die Ressourcenzuweisung und -nutzung und legt geeignete Kontingente pro Projekt fest. Google wendet das Standardlimit von 6.000 Anfragen pro 60 Sekunden auf die Gesamtheit Ihrer API-Aufrufe für Abfrage, Löschen, Statusbericht und asynchrone Anfragesynchronisierung an, und zwar pro Cloud-zu-Cloud-Integration.
Wenn Sie das Kontingent überschreiten, kann sich das negativ auf die Genauigkeit des Berichtsstatus auswirken, da ein nicht abgeschlossenes Statusupdate zu Abweichungen führen kann. Unten sehen Sie Diagramme mit Aufschlüsselungen, die speziell den Berichtsstatus und Synchronisierungsfehler bei Anfragen, die Aufschlüsselung der Anzahl und Fehler nach API-Methode sowie den Prozentsatz der Kontingentnutzung zeigen. Wenn in diesen Diagrammen ein unerwarteter Anstieg des Traffics zu sehen ist, überprüfen Sie Ihre Integration, um festzustellen, ob eine Änderung dazu führt, dass mehr Traffic an die Home Graph API gesendet wird.
In einigen Fällen, z. B. bei einem natürlichen Anstieg des Traffics im Laufe der Zeit (z. B. wenn der Anstieg mit einer Zunahme der Anzahl der Geräte, der Einführung eines neuen Gerätetyps oder einer anderen erwarteten Einführung übereinstimmt), kann es sinnvoll sein, das Kontingent für Ihre Integration zu erhöhen. Folgen Sie der Anleitung in unserer Entwicklerdokumentation, um eine Kontingenterhöhung zu beantragen.
5. Fehlerbehebung – Schritt 3: Genauigkeit des Status verbessern
Schritt 3: Übersicht
Nachdem Sie die Schritte 1 und 2 debuggt haben, geht es in Schritt 3 um die Richtigkeit von Report State (Berichtstatus). Das sind die in Google-Systemen gespeicherten Gerätestatus, die zur Bearbeitung von Nutzeranfragen verwendet werden. Aufschlüsselungen nach Merkmal und Gerätetyp finden Sie unten. In den Schritten 3a und 3b werden zwei häufige Fehler für „Report State“ behandelt: „Missing Field“-Fehler und „Inaccurate“-Fehler.
Schritt 3a: Fehler vom Typ „Missing Field“
„Fehlendes Feld“-Fehler treten auf, wenn sich die Nutzlastfelder zwischen einer QUERY-Antwort und einer gemeldeten Statusanfrage für ein bestimmtes Gerät unterscheiden. Die Felder in der Nutzlast jedes Geräts müssen identisch sein. Das kann passieren, wenn sich die Logik zur Berechnung der Nutzlast zwischen der QUERY- und der Antwort des Berichtsstatus unterscheidet. Anhand der folgenden Diagramme können Sie nachvollziehen, bei welchen Gerätetypen und Attributen die Antworten auf QUERY- und Berichtsstatusanfragen nicht übereinstimmen.
Schritt 3b: Fehler vom Typ „Ungenaue Angaben“
Ungenaue Fehler treten auf, wenn die Nutzlastfelder in einer QUERY-Antwort und einer gemeldeten Statusanfrage für ein bestimmtes Gerät identisch sind, die Statuswerte jedoch unterschiedlich sind. Das kann passieren, wenn ein Statusbericht fehlt oder sich die Logik zur Berechnung des Status zwischen QUERY und einem Statusbericht unterscheidet. Anhand der folgenden Diagramme können Sie nachvollziehen, bei welchen Gerätetypen und Attributen die Antworten auf QUERY- und Berichtsstatusanfragen nicht übereinstimmen.
6. Weitere Dokumentation und Ressourcen
- Wenn Sie Feedback zu diesem Dashboard geben oder Probleme melden möchten, erstellen Sie ein Problem in unserem öffentlichen Issue Tracker.
- Wenn Sie Einspruch einlegen möchten, reichen Sie ein Problem über unser Formular für Einsprüche gegen Qualitätsmesswerte ein.
- Um regelmäßig über die Qualität Ihrer Integration informiert zu werden, können Sie Google Cloud Platform-Benachrichtigungen konfigurieren, damit Sie benachrichtigt werden, wenn Ihre Messwerte unter einen akzeptablen Schwellenwert fallen. So werden Sie als Erster informiert, wenn ein Problem auftritt.
- Alle anderen Informationen finden Sie in der Entwicklerdokumentation unter https://developers.home.google.com/tools/analytics/home-vitals.