Willkommen beim Google Home Developer Center, der neuen Anlaufstelle für Informationen über Smart-Home-Aktionen. Hinweis:Die Aktionen in der Actions Console werden weiterhin erstellt.

Diese Seite wurde von der Cloud Translation API übersetzt.

Fehlerbehebung beim lokalen Zuhause

1. Hinweis

Mit Smart-Home-Integrationen kann Google Assistant verbundene Geräte im Zuhause der Nutzer steuern. Wenn Sie eine Smart-Home-Aktion erstellen möchten, müssen Sie einen Cloud-Webhook-Endpunkt angeben, der Smart-Home-Intents verarbeiten kann. Wenn ein Nutzer beispielsweise „Hey Google, schalte die Lampen ein“ sagt, sendet Assistant den Befehl an Ihre Cloud-Ausführung, um den Status des Geräts zu aktualisieren.

Das Local Home SDK verbessert Ihre Smart-Home-Integration, indem ein lokaler Pfad hinzugefügt wird, über den Smart-Home-Intents direkt an ein Google Home-Gerät weitergeleitet werden. Dadurch wird die Zuverlässigkeit erhöht und die Latenz bei der Verarbeitung von Nutzerbefehlen verringert. Sie können damit eine lokale Fulfillment-App in TypeScript oder JavaScript schreiben und bereitstellen, die Geräte erkennt und Befehle auf jedem Google Home- oder Google Nest-Smart-Display ausführt. Ihre App kommuniziert dann direkt über das lokale Netzwerk mit den vorhandenen Smart-Home-Geräten der Nutzer und verwendet vorhandene Standardprotokolle, um Befehle auszuführen.

Das Entfernen von Fehlern bei Smart-Home-Actions ist ein wichtiger Schritt, um Ihre Actions in Produktionsqualität zu erstellen. Ohne informative, nutzerfreundliche Tools zur Fehlerbehebung und zum Testen ist dies jedoch schwierig und zeitaufwendig. Zur Fehlerbehebung bei Smart-Home-Aktionen stehen Ihnen die Messwerte und das Logging der Google Cloud Platform (GCP) sowie die Test-Suite für Smart Home zur Verfügung. So können Sie Probleme mit Ihren Aktionen leichter erkennen und beheben.

Vorbereitung

Entwicklerleitfaden zum Erstellen einer Smart-Home-Aktion
Codelab Lokale Ausführung für Smart-Home-Aktionen aktivieren ausführen

Aufgaben

In diesem Codelab erstellen Sie eine lokale Ausführung für Smart-Home-Aktionen und verbinden sie mit Assistant. Anschließend beheben Sie Fehler in der Local Home App mithilfe der Testsuite für Smart Home und der Google Cloud Platform (GCP)-Messwerte und ‑Protokolle.

Lerninhalte

So verwenden Sie GCP-Messwerte und ‑Protokolle, um Produktionsprobleme zu identifizieren und zu beheben.
Test-Suite verwenden, um Funktions- und API-Probleme zu identifizieren.
So verwenden Sie die Chrome-Entwicklertools bei der Entwicklung Ihrer Local Home App.

Voraussetzungen

Die neueste Version von Google Chrome
Ein iOS- oder Android-Gerät mit der Google Home App
Einen Google Home- oder Google Nest-Smart-Lautsprecher
Node.js-Version 10.16 oder höher
Ein Google-Konto
Ein Google Cloud-Rechnungskonto

2. Waschmaschinen-App ausführen

Quellcode abrufen

Klicken Sie auf den folgenden Link, um das Beispiel für dieses Codelab auf Ihren Entwicklungscomputer herunterzuladen:

Oder Sie klonen das GitHub-Repository über die Befehlszeile:

$ git clone https://github.com/google-home/smarthome-debug-local.git

Über das Projekt

Die Starter-App enthält ähnliche Unterverzeichnisse und Cloud-Funktionen wie das Codelab Lokales Ausführen für Smart-Home-Aktionen aktivieren. Anstelle von app-start sehen wir hier aber app-faulty. Wir beginnen mit einer lokalen Start-App, die zwar funktioniert, aber nicht so gut.

Mit Firebase verbinden

Wir verwenden dasselbe Projekt, das Sie im Codelab Lokale Auslieferung für Smart-Home-Aktionen aktivieren erstellt haben, aber wir stellen die in diesem Codelab heruntergeladenen Dateien bereit.

Rufen Sie das Verzeichnis app-faulty auf und richten Sie die Firebase CLI mit dem Actions-Projekt ein, das Sie im Codelab Lokale Auslieferung für Smart-Home-Actions aktivieren erstellt haben:

$ cd app-faulty
$ firebase use <project-id>

In Firebase bereitstellen

Rufen Sie den Ordner app-faulty/functions auf und installieren Sie alle erforderlichen Abhängigkeiten mit npm:

$ cd functions
$ npm install

Hinweis: Wenn Sie die folgende Meldung sehen, können Sie sie ignorieren und fortfahren. Die Warnung ist auf einige ältere Abhängigkeiten zurückzuführen. Weitere Informationen

found 5 high severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

Wechseln Sie zum Verzeichnis app-faulty/local/ und führen Sie die folgenden Befehle aus, um den TypeScript-Compiler herunterzuladen und die App zu kompilieren:

$ cd ../local
$ npm install
$ npm run build

Dadurch wird die index.ts-Quelldatei (TypeScript) kompiliert und der folgende Inhalt wird in das Verzeichnis app-faulty/public/local-home/ kopiert:

bundle.js: Kompilierte JavaScript-Ausgabe mit der lokalen App und den Abhängigkeiten.
index.html: Lokale Hostingseite, über die die App für On-Device-Tests bereitgestellt wird.

Nachdem Sie die Abhängigkeiten installiert und Ihr Projekt konfiguriert haben, können Sie die App zum ersten Mal ausführen.

$ firebase deploy

Die Ausgabe der Konsole sollte so aussehen:

...

✔ Deploy complete!

Project Console: https://console.firebase.google.com/project/<project-id>/overview
Hosting URL: https://<projectcd -id>.web.app

Mit diesem Befehl werden eine Webanwendung und mehrere Cloud Functions for Firebase bereitgestellt.

HomeGraph aktualisieren

Öffnen Sie die Hosting-URL in Ihrem Browser (https://<project-id>.web.app), um die Web-App aufzurufen. Klicken Sie in der Web-UI auf die Schaltfläche Aktualisieren, um HomeGraph über Synchronisierung anfordern mit den neuesten Gerätemetadaten aus der fehlerhaften Waschmaschinen-App zu aktualisieren:

Öffnen Sie die Google Home App und prüfen Sie, ob Sie Ihre Waschmaschine mit dem neuen Namen „Fehlerhafte Waschmaschine“ sehen können. Achten Sie darauf, das Gerät einem Raum zuzuweisen, in dem sich ein Nest-Gerät befindet.

3. Smarte Waschmaschine starten

Wenn Sie das Codelab Lokale Ausführung für Smart-Home-Aktionen aktivieren ausgeführt haben, sollten Sie die virtuelle intelligente Waschmaschine bereits gestartet haben. Wenn er gestoppt wird, denken Sie daran, das virtuelle Gerät neu zu starten.

Gerät starten

Rufen Sie das Verzeichnis virtual-device/ auf und führen Sie das Geräteskript aus. Übergeben Sie die Konfigurationsparameter als Argumente:

$ cd ../../virtual-device
$ npm install
$ npm start -- \
  --deviceId=deviceid123 --projectId=<project-id> \
  --discoveryPortOut=3311 --discoveryPacket=HelloLocalHomeSDK

Prüfen Sie, ob das Gerätescript mit den erwarteten Parametern ausgeführt wird:

(...): UDP Server listening on 3311
(...): Device listening on port 3388
(...): Report State successful

4. Lokale Home App testen

Senden Sie Befehle an Ihr Google Home-Gerät, z. B.:

„Hey Google, schalte meine Waschmaschine ein.“

„Hey Google, starte meine Waschmaschine.“

„Hey Google, erzwinge lokale Ergebnisse.“

„Hey Google, schalte meine Waschmaschine aus.“

Sie werden feststellen, dass Google Assistant mit „Tut mir leid, die fehlerhafte Waschmaschine ist im Moment nicht verfügbar“ antwortet, wenn Sie versuchen, die Waschmaschine nach „Lokalisierung erzwingen“ zu steuern.

Das bedeutet, dass das Gerät nicht über einen lokalen Pfad erreichbar ist. Es funktionierte, bevor „Hey Google, force local“ (Hey Google, lokal erzwingen) verwendet wurde, da wir auf den Cloud-Pfad zurückgreifen, wenn das Gerät nicht über einen lokalen Pfad erreichbar ist. Nach „force local“ ist die Option zum Rückfall auf den Cloud-Pfad jedoch deaktiviert.

Um das Problem zu finden, nutzen wir die Tools, die wir haben: Messwerte und Protokollierung der Google Cloud Platform (GCP) sowie die Chrome-Entwicklertools.

5. Lokale Home App debuggen

Im folgenden Abschnitt ermitteln Sie mit den von Google bereitgestellten Tools, warum das Gerät nicht über den lokalen Pfad erreichbar ist. Mit den Google Chrome-Entwicklertools können Sie eine Verbindung mit dem Google Home-Gerät herstellen, die Protokolle der Konsole aufrufen und Fehler in der Local Home App beheben. Sie können auch benutzerdefinierte Protokolle an Cloud Logging senden, damit Sie die häufigsten Fehler sehen, die Nutzer in Ihrer Local Home App feststellen.

Chrome-Entwicklertools verbinden

So stellen Sie eine Verbindung zwischen dem Debugger und Ihrer lokalen Fulfillment-App her:

Prüfen Sie, ob Sie Ihr Google Home-Gerät mit einem Nutzer verknüpft haben, der auf das Actions Console-Projekt zugreifen darf.
Starten Sie Ihr Google Home-Gerät neu. Dadurch kann es die URL Ihrer HTML-Datei sowie die Scankonfiguration abrufen, die Sie in der Actions Console festgelegt haben.
Starten Sie Chrome auf Ihrem Entwicklungscomputer.
Öffnen Sie einen neuen Chrome-Tab und geben Sie chrome://inspect in das Adressfeld ein, um den Inspector zu starten.

Auf der Seite sollten Sie eine Liste mit Geräten sehen und die App-URL sollte unter dem Namen Ihres Google Home-Geräts angezeigt werden.

Inspector starten

Klicken Sie unter der App-URL auf Prüfen, um die Chrome-Entwicklertools zu öffnen. Wählen Sie den Tab Console aus und prüfen Sie, ob Sie den Inhalt der IDENTIFY-Intent-Nachricht sehen, die von Ihrer TypeScript-App ausgegeben wurde.

Diese Ausgabe bedeutet, dass der IDENTIFY-Handler erfolgreich ausgelöst wurde, die in IdentifyResponse zurückgegebene verificationId jedoch keinem der Geräte in Ihrem HomeGraph entspricht. Fügen wir einige benutzerdefinierte Protokolle hinzu, um das herauszufinden.

Benutzerdefinierte Protokolle hinzufügen

Das Local Home SDK gibt zwar einen DEVICE_VERIFICATION_FAILED-Fehler aus, der aber nicht viel zur Behebung des Problems beiträgt. Fügen Sie nun einige benutzerdefinierte Logs hinzu, um sicherzustellen, dass die Scandaten korrekt gelesen und verarbeitet werden. Wenn wir das Promise mit einem Fehler ablehnen, wird die Fehlermeldung auch an Cloud Logging gesendet.

local/index.ts

identifyHandler(request: IntentFlow.IdentifyRequest):
    Promise<IntentFlow.IdentifyResponse> {
  console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));

  const scanData = request.inputs[0].payload.device.udpScanData;
  if (!scanData) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_request', 'Invalid scan data');
    return Promise.reject(err);
  }

  // In this codelab, the scan data contains only local device id.
  // Is there something wrong here?
  const localDeviceId = Buffer.from(scanData.data);
  console.log(`IDENTIFY handler: received local device id
      ${localDeviceId}`);

  // Add custom logs
  if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_device', 'Invalid device id from scan data ' +
        localDeviceId);
    return Promise.reject(err);
  }

  const response: IntentFlow.IdentifyResponse = {
    intent: Intents.IDENTIFY,
    requestId: request.requestId,
    payload: {
      device: {
        id: 'washer',
        verificationId: localDeviceId.toString(),
      }
    }
  };
  console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));

  return Promise.resolve(response);
}

Ändern Sie auch die Version der lokalen Home App, damit wir feststellen können, ob wir die richtige Version verwenden.

local/index.ts

const localHomeSdk = new App('1.0.1');

Nachdem Sie die benutzerdefinierten Protokolle hinzugefügt haben, müssen Sie die App noch einmal kompilieren und in Firebase neu bereitstellen.

$ cd ../app-faulty/local
$ npm run build
$ firebase deploy --only hosting

Starten Sie jetzt Ihr Google Home-Gerät neu, damit die aktualisierte lokale Home App geladen werden kann. Sie können in den Console-Logs in den Chrome-Entwicklertools nachsehen, ob das Google Home-Gerät die erwartete Version verwendet.

Auf Cloud Logging zugreifen

Sehen wir uns an, wie Sie mit Cloud Logging Fehler finden. So greifen Sie auf Cloud Logging für Ihr Projekt zu:

Rufen Sie in der Cloud Platform Console die Seite Projekte auf.
Wählen Sie Ihr Smart-Home-Projekt aus.
Wählen Sie unter Vorgänge die Option Logging > Log-Explorer aus.

Der Zugriff auf Logging-Daten wird für Nutzer Ihres Actions-Projekts über Identity and Access Management (IAM) verwaltet. Weitere Informationen zu Rollen und Berechtigungen für das Logging von Daten finden Sie unter Zugriffssteuerung in Cloud Logging.

Erweiterte Filter verwenden

Wir wissen, dass bei der IDENTIFY-Intent-Aktion Fehler auftreten, da der lokale Pfad nicht funktioniert, weil das lokale Gerät nicht erkannt wird. Wir möchten jedoch genau wissen, was das Problem ist. Filtern wir zuerst die Fehler heraus, die im IDENTIFY-Handler auftreten.

Klicken Sie auf den Umschalter Abfrage anzeigen. Daraufhin sollte das Feld Query Builder angezeigt werden. Geben Sie jsonPayload.intent="IDENTIFY" in das Feld Query Builder ein und klicken Sie auf die Schaltfläche Abfrage ausführen.

Dadurch werden alle Fehlerprotokolle ausgegeben, die im IDENTIFY-Handler geworfen werden. Maximieren Sie als Nächstes den letzten Fehler. Die errorCode und debugString, die Sie gerade beim Ablehnen des Versprechens festgelegt haben, finden Sie im IDENTIFY-Handler.

Anhand der debugString können wir erkennen, dass die lokale Geräte-ID nicht das erwartete Format hat. Die lokale Home App erwartet die lokale Geräte-ID als String, der mit deviceid beginnt und von drei Ziffern gefolgt wird. Die lokale Geräte-ID hier ist jedoch ein Hexadezimalstring.

Fehler beheben

Wenn wir zum Quellcode zurückkehren, in dem wir die lokale Geräte-ID aus den Scandaten parsen, stellen wir fest, dass wir beim Konvertieren des Strings in Byte keine Codierung bereitgestellt haben. Die Scandaten werden als Hexadezimalstring empfangen. Geben Sie daher hex als Zeichencodierung an, wenn Sie Buffer.from() aufrufen.

local/index.ts

identifyHandler(request: IntentFlow.IdentifyRequest):
    Promise<IntentFlow.IdentifyResponse> {
  console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));

  const scanData = request.inputs[0].payload.device.udpScanData;
  if (!scanData) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_request', 'Invalid scan data');
    return Promise.reject(err);
  }

  // In this codelab, the scan data contains only local device id.
  const localDeviceId = Buffer.from(scanData.data, 'hex');
  console.log(`IDENTIFY handler: received local device id
      ${localDeviceId}`);

  if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
    const err = new IntentFlow.HandlerError(request.requestId,
      'invalid_device', 'Invalid device id from scan data ' +
      localDeviceId);
    return Promise.reject(err);
  }

  const response: IntentFlow.IdentifyResponse = {
    intent: Intents.IDENTIFY,
    requestId: request.requestId,
    payload: {
      device: {
        id: 'washer',
        verificationId: localDeviceId.toString(),
      }
    }
  };
  console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));

  return Promise.resolve(response);
}

Ändern Sie auch die Version der lokalen Home App, damit wir feststellen können, ob wir die richtige Version verwenden.

local/index.ts

const localHomeSdk = new App('1.0.2');

Nachdem Sie den Fehler behoben haben, kompilieren Sie die App und stellen Sie sie noch einmal in Firebase bereit. Führen Sie in app-faulty/local Folgendes aus:

$ npm run build
$ firebase deploy --only hosting

Korrektur testen

Starten Sie Ihr Google Home-Gerät nach der Bereitstellung neu, damit die aktualisierte lokale Home App geladen werden kann. Achten Sie darauf, dass die Version der lokalen Home App 1.0.2 ist. Diesmal sollten keine Fehler in der Chrome DevTools-Konsole angezeigt werden.

Sie können jetzt noch einmal versuchen, Befehle an Ihr Gerät zu senden.

„Hey Google, erzwinge lokale Suche.“

„Hey Google, stopp die Waschmaschine.“

„Hey Google, schalte meine Waschmaschine ein.“

…

„Hey Google, Standardeinstellung erzwingen.“

6. Test-Suite für Smart Home ausführen

Nachdem Sie Ihr Gerät über die Touchbedienung in der Google Home App oder per Sprachbefehl bestätigt haben, können Sie mit der automatisierten Test-Suite für Smart Home Anwendungsfälle basierend auf den Gerätetypen und -merkmalen validieren, die mit Ihrer Aktion verknüpft sind. Die Testsuite führt eine Reihe von Tests durch, um Probleme in Ihrer Aktion zu erkennen. Bei fehlgeschlagenen Testfällen werden informative Meldungen angezeigt, um das Beheben von Fehlern zu beschleunigen, bevor Sie sich mit den Ereignisprotokollen befassen.

Test-Suite für Smart Home ausführen

So testen Sie Ihre Smart-Home-Aktion mit der Test-Suite:

Öffnen Sie in Ihrem Webbrowser die Testsuite für Smart Home.
Melden Sie sich über die Schaltfläche rechts oben bei Google an. Dadurch kann die Test-Suite die Befehle direkt an Google Assistant senden.
Geben Sie im Feld Project ID (Projekt-ID) die Projekt-ID Ihrer Smart-Home-Aktion ein. Klicken Sie dann auf WEITER, um fortzufahren.
Im Schritt Testeinstellungen sollte die fehlerhafte Waschmaschine im Bereich Geräte und Werkzeuge angezeigt werden.
Deaktivieren Sie die Option Test Request Sync (Testsynchronisierung von Anfragen), da die Beispiel-Waschmaschinen-App keine Benutzeroberfläche zum Hinzufügen, Entfernen oder Umbenennen der Waschmaschine hat. In einem Produktionssystem müssen Sie Synchronisierung anfordern auslösen, wenn der Nutzer Geräte hinzufügt, entfernt oder umbenennt.
Lassen Sie die Option Local Home SDK aktiviert, da wir sowohl lokale als auch Cloudpfade testen werden.
Klicken Sie auf Weiter: Testumgebung, um den Test auszuführen.

Nach Abschluss der Tests sehen Sie, dass die Tests zum Pausieren/Fortsetzen im lokalen Pfad fehlschlagen, während die Tests zum Pausieren/Fortsetzen im Cloud-Pfad erfolgreich sind.

Fehlermeldung analysieren

Sehen Sie sich die Fehlermeldungen in den fehlgeschlagenen Testfällen genauer an. Sie geben an, was der erwartete Status für diesen Test ist und was der tatsächliche Status war. In diesem Fall ist für „Waschmaschine pausieren“ der erwartete Status isPaused: true, der tatsächliche Status ist jedoch isPaused: false. Ähnlich ist der erwartete Status für „Waschmaschine pausieren“ isPaused: true, der tatsächliche Status ist jedoch isPaused: false.

Anhand der Fehlermeldungen sieht es so aus, als würden wir im lokalen Pfad den Status von isPaused umgekehrt festlegen.

Fehler identifizieren und beheben

Suchen wir den Quellcode, in dem die Local Home App den Ausführungsbefehl an das Gerät sendet. getDataCommand() ist die Funktion, die von executeHandler() aufgerufen wird, um payload im Ausführungsbefehl festzulegen, der an das Gerät gesendet wird.

local/index.ts

getDataForCommand(command: string, params: IWasherParams): unknown {
    switch (command) {
        case 'action.devices.commands.OnOff':
            return {
                on: params.on ? true : false
            };
        case 'action.devices.commands.StartStop':
            return {
                isRunning: params.start ? true : false
            };
        case 'action.devices.commands.PauseUnpause':
            return {
                // Is there something wrong here?
                isPaused: params.pause ? false : true
            };
        default:
            console.error('Unknown command', command);
            return {};
    }
}

Wir setzen das isPause-Objekt in die umgekehrte Richtung. Es sollte auf true gesetzt werden, wenn params.pause gleich true ist, ansonsten false. Lass uns das beheben.

local/index.ts

getDataForCommand(command: string, params: IWasherParams): unknown {
    switch (command) {
        case 'action.devices.commands.OnOff':
            return {
                on: params.on ? true : false
            };
        case 'action.devices.commands.StartStop':
            return {
                isRunning: params.start ? true : false
            };
        case 'action.devices.commands.PauseUnpause':
            return {
                isPaused: params.pause ? true : false
            };
        default:
            console.error('Unknown command', command);
            return {};
    }
}

Ändere die Version der lokalen Home App, damit wir feststellen können, ob wir die richtige Version verwenden.

local/index.ts

const localHomeSdk = new App('1.0.3');

Denken Sie daran, die App noch einmal zu kompilieren und in Firebase bereitzustellen. Führen Sie in app-faulty/local Folgendes aus:

$ npm run build
$ firebase deploy --only hosting

Starten Sie jetzt Ihr Google Home-Gerät neu, damit die aktualisierte lokale Home App geladen werden kann. Prüfen Sie, ob die Version 1.0.3 der lokalen Home App installiert ist.

Korrektur testen

Führen Sie die Testsuite für Smart Home jetzt noch einmal mit denselben Konfigurationen aus. Sie werden feststellen, dass alle Testfälle bestanden haben.

7. Glückwunsch

Glückwunsch! Sie haben gelernt, wie Sie über die Test Suite für Smart Home und Cloud Logging Fehler bei einer lokalen Home App beheben.

Weitere Informationen

Du kannst Folgendes ausprobieren:

Fügen Sie Ihrem Gerät weitere unterstützte Merkmale hinzu und testen Sie es mit der Test-Suite.
Fügen Sie jedem Intent-Handler weitere benutzerdefinierte Protokolle hinzu und rufen Sie sie in Cloud Logging auf.
Erstellen Sie Dashboards, richten Sie Benachrichtigungen ein und greifen Sie programmatisch auf Messwertdaten zu, um hilfreiche Nutzungsmesswerte zu Ihrer Aktion zu erhalten.

Außerdem finden Sie hier weitere Informationen zum Testen und Einreichen einer Aktion zur Überprüfung, einschließlich des Zertifizierungsverfahrens, mit dem Ihre Aktion für Nutzer veröffentlicht wird.