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 in den Haushalte. Zum Erstellen einer Smart-Home-Aktion müssen Sie einen Cloud-Webhook-Endpunkt bereitstellen, der Smart-Home-Intents verarbeiten kann. Sagt ein Nutzer beispielsweise „Hey Google, schalte das Licht an“. sendet Assistant den Befehl an Ihre Cloud-Ausführung, um den Gerätestatus zu aktualisieren.

Das Local Home SDK verbessert die Smart-Home-Integration, indem es einen lokalen Pfad hinzufügt, um Smart-Home-Intents direkt an ein Google Home-Gerät weiterzuleiten. Dies erhöht die Zuverlässigkeit und verringert die Latenz bei der Verarbeitung der . Damit können Sie eine lokale App für die Auftragsausführung in TypeScript oder JavaScript schreiben und bereitstellen, die Geräte identifiziert und Befehle auf allen intelligenten Google Home-Lautsprechern oder Google Nest-Smart-Displays ausführt. Ihre App kommuniziert dann direkt mit der vorhandene Smart-Home-Geräte über das Local Area Network, indem vorhandene Standardprotokolle zur Ausführung von Befehlen verwendet werden.

Das Debuggen von Smart-Home-Aktionen ist ein wichtiger Schritt, um deine Aktionen mit Produktionsqualität zu erstellen. Ohne informative, nutzerfreundliche Tools zur Fehlerbehebung und Tests ist es jedoch schwierig und zeitaufwendig. Um das Debugging in Smart-Home-Aktionen zu erleichtern, stehen Ihnen Messwerte und Logging der Google Cloud Platform (GCP) sowie die Test-Suite für Smart Homes zur Verfügung, um Probleme mit Ihren Aktionen zu erkennen und zu beheben.

Vorbereitung

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

Aufgaben

In diesem Codelab konzipierst du eine lokale Ausführung für Smart-Home-Aktionen und verbindest sie mit Assistant. Dann behebst du Fehler in der Local Home App über die Testsuite für Smart Home und Messwerte und Logging der Google Cloud Platform (GCP)

Lerninhalte

GCP-Messwerte und Logging zum Erkennen und Beheben von Produktionsproblemen verwenden
Test-Suite verwenden, um Funktions- und API-Probleme zu identifizieren.
Hier erfahren Sie, wie Sie die Chrome-Entwicklertools bei der Entwicklung Ihrer Local Home App verwenden.

Voraussetzungen

Die aktuelle Version von Google Chrome
Ein iOS- oder Android-Gerät mit der Google Home App
Einen intelligenten Lautsprecher von Google Home oder ein Smart Display von Google Nest
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 Lokale Ausführung für Smart-Home-Aktionen aktivieren. Aber statt app-start haben wir hier app-faulty. Wir beginnen mit einer lokalen Start-App, die funktioniert, aber nicht so gut.

Mit Firebase verbinden

Wir verwenden dasselbe Projekt, das Sie im Codelab Lokale Auftragsausführung 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 Ihrem Actions-Projekt ein, das im Codelab Lokale Ausführung für Smart-Home-Aktionen aktivieren erstellt wurde:

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

In Firebase bereitstellen

Wechseln Sie zum Ordner app-faulty/functions und installieren Sie alle erforderlichen Abhängigkeiten mit npm:

$ cd functions
$ npm install

Hinweis:Wenn die Meldung unten angezeigt wird, können Sie diese ignorieren und fortfahren. Diese Warnung geht auf einige ältere Abhängigkeiten zurück. Weitere Informationen finden Sie hier.

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

Gehen 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 (TypeScript)-Quelle kompiliert und der folgende Inhalt im Verzeichnis app-faulty/public/local-home/ abgelegt:

bundle.js: Kompilierte JavaScript-Ausgabe mit der lokalen App und den Abhängigkeiten.
index.html: Lokale Hostseite, über die die App zum Testen auf dem Gerät bereitgestellt wird

Nachdem Sie nun die Abhängigkeiten installiert und das Projekt konfiguriert haben, können Sie die Anwendung 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 wird eine Webanwendung zusammen mit mehreren 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 Weboberfläche auf die Schaltfläche Aktualisieren , um HomeGraph über Synchronisierung anfordern mit den neuesten Gerätemetadaten aus der defekten Waschmaschine-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. Denken Sie daran, das Gerät einem Raum zuzuweisen, in dem sich ein Nest-Gerät befindet.

3. Intelligente 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 dabei 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äteskript mit den erwarteten Parametern ausgeführt wird:

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

4. Local 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 lokal.“

„Hey Google, stoppe die Waschmaschine.“

Google Assistant antwortet mit „Tut mir leid, anscheinend ist die fehlerhafte Waschmaschine im Moment nicht verfügbar“. wenn Sie versuchen, die Waschmaschine nach „Force local“ zu steuern.

Das bedeutet, dass das Gerät nicht über einen lokalen Pfad erreichbar ist. Es hat funktioniert, bevor „Hey Google, lokal erzwingen“ ausgegeben wurde da wir auf den Cloud-Pfad zurückgreifen, wenn das Gerät nicht über einen lokalen Pfad erreichbar ist. Nach „Lokalisierung erzwingen“ ist die Option, auf den Cloud-Pfad zurückzugreifen, jedoch deaktiviert.

Um herauszufinden, worin das Problem besteht, nutzen wir unsere Tools: Google Cloud Platform (GCP) Metrics und Logging sowie Chrome-Entwicklertools.

5. Fehler in der Local Home App beheben

Im folgenden Abschnitt verwenden Sie die von Google bereitgestellten Tools, um herauszufinden, 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 Konsolenprotokolle aufrufen und Fehler in der Local Home App beheben. Sie können auch benutzerdefinierte Protokolle an Cloud Logging senden, um die häufigsten Fehler zu sehen, die Nutzer in Ihrer Local Home App feststellen.

Chrome-Entwicklertools verbinden

So verbinden Sie den Debugger mit Ihrer lokalen App für die Auftragsausführung:

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, um die URL Ihres HTML-Codes sowie die Scankonfiguration abzurufen, 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 das Prüftool 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 starten. Wählen Sie den Tab Console aus und prüfen Sie, ob Sie den Inhalt des Intents IDENTIFY sehen können, der von Ihrer TypeScript-App ausgegeben wird.

Das bedeutet, dass der IDENTIFY-Handler erfolgreich ausgelöst wurde, der in IdentifyResponse zurückgegebene verificationId aber mit keinem der Geräte in deiner HomeGraph-Grafik übereinstimmt. Fügen wir nun einige benutzerdefinierte Logs hinzu, um den Grund dafür herauszufinden.

Benutzerdefinierte Logs hinzufügen

Obwohl vom Local Home SDK der Fehler DEVICE_VERIFICATION_FAILED ausgegeben wird, hilft er bei der Suche nach der Ursache nicht weiter. 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);
}

Ändere außerdem 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 Logs hinzugefügt haben, müssen Sie die App noch einmal kompilieren und in Firebase bereitstellen.

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

Starten Sie jetzt Ihr Google Home neu, damit die aktualisierte lokale Home App geladen werden kann. Anhand der Console-Protokolle in den Chrome-Entwicklertools können Sie feststellen, ob auf dem Google Home-Gerät die erwartete Version verwendet wird.

Auf Cloud Logging zugreifen

Sehen wir uns an, wie Sie Cloud Logging zum Auffinden Ihrer Fehler verwenden. 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 aus. Log-Explorer:

Der Zugriff auf Logging-Daten wird über Identity and Access Management (IAM) für Nutzer Ihres Actions-Projekts 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 im Intent IDENTIFY Fehler auftreten, da der lokale Pfad nicht funktioniert, weil das lokale Gerät nicht identifiziert werden kann. Da wir aber genau wissen möchten, worin das Problem besteht, filtern wir zuerst die Fehler heraus, die im IDENTIFY-Handler auftreten.

Klicken Sie auf die Ein/Aus-Schaltfläche Abfrage anzeigen. Daraufhin sollte sich das Feld Query Builder befinden. Geben Sie jsonPayload.intent="IDENTIFY" in das Feld Query Builder ein und klicken Sie auf die Schaltfläche Abfrage ausführen.

Als Ergebnis erhalten Sie alle Fehlerlogs, die im IDENTIFY-Handler ausgegeben werden. Maximieren Sie als Nächstes den letzten Fehler. Du findest die errorCode und debugString, die du gerade bei der Ablehnung des Versprechens im IDENTIFY-Handler festgelegt hast.

Anhand der debugString können wir erkennen, dass die lokale Geräte-ID nicht das erwartete Format hat. Die Local Home App erwartet die lokale Geräte-ID als String, der mit deviceid beginnt, gefolgt von drei Ziffern. 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 hexadezimaler String empfangen. Übergeben Sie deshalb beim Aufrufen von Buffer.from() hex als Zeichencodierung.

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);
}

Ändere außerdem 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

Fehlerbehebung testen

Starten Sie Ihr Google Home-Gerät nach der Bereitstellung neu, damit die aktualisierte lokale Home App geladen werden kann. Vergewissern Sie sich, dass die Version der lokalen Startseiten-App 1.0.2 ist. Dieses Mal sollten in der Entwicklertools von Chrome keine Fehler angezeigt werden.

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

„Hey Google, lokale Daten erzwingen.“

„Hey Google, stoppe die Waschmaschine.“

„Hey Google, schalte meine Waschmaschine ein.“

…

„Hey Google, Standard erzwingen.“

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

Nachdem du dein Gerät über die Touchbedienung in der Google Home App oder per Sprachbefehl bestätigt hast, kannst du die automatisierte Test Suite für Smart Home verwenden, um Anwendungsfälle auf Grundlage der Gerätetypen und Eigenschaften, die deiner Aktion zugeordnet sind, zu validieren. Die Test-Suite führt eine Reihe von Tests aus, um Probleme in deiner Aktion zu erkennen, und zeigt bei fehlgeschlagenen Testfällen informative Meldungen an, um die Fehlerbehebung zu beschleunigen, bevor du die Ereignisprotokolle aufrufst.

Test-Suite für Smart Home ausführen

So kannst du die Action by Test Suite für dein Smart Home testen:

Öffnen Sie in Ihrem Webbrowser die Test Suite für Smart Home.
Melden Sie sich über die Schaltfläche oben rechts in Google an. Dadurch kann die Test-Suite die Befehle direkt an Google Assistant senden.
Gib im Feld Projekt-ID die Projekt-ID deiner 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 (Synchronisierung der Testanfrage), da die Beispiel-Wasch-App keine Benutzeroberfläche zum Hinzufügen, Entfernen oder Umbenennen der Waschmaschine hat. In einem Produktionssystem müssen Sie jedes Mal die Option 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 Cloud-Pfade testen werden.
Klicken Sie auf Weiter: Testumgebung, um den Test zu starten.

Wenn die Tests abgeschlossen sind, werden Sie feststellen, dass die Tests zum Pausieren/Fortsetzen im lokalen Pfad fehlschlagen, während die Tests zum Pausieren/Fortsetzen im Cloud-Pfad übergeben werden.

Fehlermeldung analysieren

Sieh dir die Fehlermeldungen in den fehlgeschlagenen Testfällen genauer an. Sie geben Auskunft über den erwarteten Zustand für den Test und wie der tatsächliche Zustand war. In diesem Fall ist für „Waschmaschine anhalten“ der erwartete Status isPaused: true. Für den tatsächlichen Status ist isPaused: false. Ähnlich lautet der erwartete Status für „Waschmaschine anhalten“ isPaused: true. Für den tatsächlichen Zustand lautet der Wert isPaused: false.

Den Fehlermeldungen entnehmen wir, dass wir den isPaused-Status im lokalen Pfad umgekehrt festlegen.

Fehler ermitteln und beheben

Suchen Sie den Quellcode, über den die Local Home App den Ausführungsbefehl an das Gerät sendet. getDataCommand() ist die Funktion, die von executeHandler() aufgerufen wird, um die 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. Also beheben wir das.

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 sie noch einmal 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 neu, damit die aktualisierte lokale Home App geladen werden kann. Die lokale Start-App muss Version 1.0.3.

Fehlerbehebung testen

Wenn du die Testsuite für das Smart Home jetzt noch einmal mit denselben Konfigurationen ausführst, wirst du feststellen, dass alle Testläufe bestanden wurden.

7. Glückwunsch

Glückwunsch! Jetzt wissen Sie, wie Sie mithilfe der Test-Suite für Smart Homes und Cloud Logging:

Weitere Informationen

Außerdem können Sie Folgendes ausprobieren:

Füge deinem Gerät weitere unterstützte Traits hinzu und teste sie mit der Test-Suite.
Fügen Sie jedem Intent-Handler weitere benutzerdefinierte Logs hinzu und sehen Sie sich diese in Cloud Logging an.
Erstellen Sie Dashboards, richten Sie Warnungen ein und greifen Sie programmatisch auf Messwertdaten zu, um nützliche Nutzungsmesswerte zu Ihrer Aktion zu erhalten.

Weitere Informationen zum Testen und Einreichen einer Aktion zur Überprüfung, einschließlich des Zertifizierungsverfahrens für die Veröffentlichung deiner Aktion für Nutzer, findest du hier.