1. Hinweis
Bei Cloud-zu-Cloud-Integrationen werden Gerätetypen verwendet, um Google Assistant mitzuteilen, welche Grammatik für ein Gerät verwendet werden soll. Geräteeigenschaften definieren die Funktionen eines Gerätetyps. Ein Gerät übernimmt die Status aller Geräteeigenschaften, die einer Integration hinzugefügt wurden.
Sie können alle unterstützten Merkmale mit dem ausgewählten Gerätetyp verknüpfen, um die Funktionen der Geräte Ihrer Nutzer anzupassen. Wenn Sie in Ihren Aktionen benutzerdefinierte Eigenschaften implementieren möchten, die derzeit nicht im Geräteschema verfügbar sind, können Sie mit den Eigenschaften Modi und Schalter bestimmte Einstellungen mit einem benutzerdefinierten Namen steuern.
Neben den grundlegenden Steuerfunktionen, die durch Typen und Merkmale bereitgestellt werden, bietet die Smart Home API zusätzliche Funktionen, um die Nutzerfreundlichkeit zu verbessern. Fehlerantworten enthalten detailliertes Nutzerfeedback, wenn Absichten nicht erfolgreich sind. Die sekundäre Nutzerbestätigung erweitert diese Antworten und erhöht die Sicherheit des gewünschten Gerätemerkmals. Wenn Sie bestimmte Fehlerantworten an Challenge-Blöcke senden, die vom Assistant ausgestellt wurden, kann für Ihre Cloud-zu-Cloud-Integration eine zusätzliche Autorisierung erforderlich sein, um einen Befehl auszuführen.
Vorbereitung
- Entwicklerleitfaden zum Erstellen einer Cloud-zu-Cloud-Integration
- Codelab Smart Home Washer
- Entwicklerleitfaden zu Gerätetypen und -merkmalen
Aufgaben
In diesem Codelab stellen Sie eine vorkonfigurierte Smart-Home-Integration mit Firebase bereit und erfahren dann, wie Sie der Smart-Home-Waschmaschine für die Beladungsmenge und den Turbomodus nicht standardmäßige Eigenschaften hinzufügen. Außerdem implementieren Sie Fehler- und Ausnahmeberichte und erfahren, wie Sie eine mündliche Bestätigung zum Einschalten der Waschmaschine mithilfe der sekundären Nutzerbestätigung erzwingen.
Lerninhalte
- Deiner Integration die Merkmale „Modi“ und „Schalter“ hinzufügen
- Fehler und Ausnahmen melden
- Sekundäre Nutzerbestätigung anwenden
Voraussetzungen
- Einen Webbrowser wie Google Chrome
- Ein iOS- oder Android-Gerät mit der Google Home App
- Node.js-Version 10.16 oder höher
- Ein Google-Konto
- Ein Google Cloud-Rechnungskonto
2. Erste Schritte
Aktivitätseinstellungen aktivieren
Wenn Sie Google Assistant verwenden möchten, müssen Sie bestimmte Aktivitätsdaten mit Google teilen. Google Assistant benötigt diese Daten, um ordnungsgemäß zu funktionieren. Die Datenweitergabe ist jedoch nicht spezifisch für das SDK. Wenn Sie diese Daten freigeben möchten, erstellen Sie ein Google-Konto, falls Sie noch keines haben. Sie können jedes Google-Konto verwenden – es muss nicht Ihr Entwicklerkonto sein.
Öffnen Sie die Seite Aktivitätseinstellungen für das Google-Konto, das Sie mit Assistant verwenden möchten.
Die folgenden Ein/Aus-Schaltflächen müssen aktiviert sein:
- Web- und App-Aktivitäten: Setzen Sie außerdem ein Häkchen in das Kästchen Auch den Chrome-Verlauf sowie Aktivitäten auf Websites, in Apps und auf Geräten berücksichtigen, die Google-Dienste nutzen.
- Geräteinformationen
- Sprach- und Audioaktivitäten
Cloud-zu-Cloud-Integrationsprojekt erstellen
- Rufen Sie die Developer Console auf.
- Klicken Sie auf Projekt erstellen, geben Sie einen Namen für das Projekt ein und klicken Sie auf Projekt erstellen.
Cloud-zu-Cloud-Integration auswählen
Wählen Sie in der Developer Console auf der Projektstartseite unter Cloud-zu-Cloud die Option Cloud-zu-Cloud-Integration hinzufügen aus.
Firebase CLI installieren
Mit der Firebase-Befehlszeile (Firebase Command Line Interface, CLI) können Sie Ihre Webanwendungen lokal bereitstellen und in Firebase Hosting bereitstellen.
Führen Sie zum Installieren der Befehlszeile den folgenden npm-Befehl im Terminal aus:
npm install -g firebase-tools
Führen Sie folgenden Befehl aus, um zu prüfen, ob die Befehlszeile korrekt installiert wurde:
firebase --version
Autorisieren Sie die Firebase CLI mit Ihrem Google-Konto:
firebase login
Firebase-Projekt erstellen
- Rufen Sie Firebase auf.
- Klicken Sie auf Projekt erstellen und geben Sie den Projektnamen ein.
- Klicken Sie auf das Kästchen für die Zustimmung und dann auf Weiter. Wenn kein Kästchen für die Vereinbarung vorhanden ist, können Sie diesen Schritt überspringen.
- Suchen Sie nach der Projekt-ID Ihres Firebase-Projekts. Rufen Sie die Projektübersicht auf und klicken Sie auf das Symbol „Einstellungen“ > Projekteinstellungen.
- Ihr Projekt wird auf dem Tab Allgemein aufgeführt.
HomeGraph API aktivieren
Mit der HomeGraph API können Geräte und ihre Status im Home Graph eines Nutzers gespeichert und abgefragt werden. Wenn Sie diese API verwenden möchten, müssen Sie zuerst die Google Cloud Console öffnen und die HomeGraph API aktivieren.
Wählen Sie in der Google Cloud Console das Projekt aus, das Ihren Aktionen entspricht. <firebase-project-id>. Klicken Sie dann auf dem Bildschirm „API-Bibliothek“ für die HomeGraph API auf Aktivieren.
3. Start-App ausführen
Nachdem Sie Ihre Entwicklungsumgebung eingerichtet haben, können Sie das Starterprojekt bereitstellen, um zu prüfen, ob alles richtig konfiguriert ist.
Quellcode abrufen
Klicken Sie auf den folgenden Link, um das Beispiel für dieses Codelab auf Ihren Entwicklungscomputer herunterzuladen:
Sie können das GitHub-Repository auch über die Befehlszeile klonen:
git clone https://github.com/google-home/smarthome-traits.git
Entpacken Sie die heruntergeladene ZIP-Datei.
Informationen zum Projekt
Das Startprojekt enthält die folgenden Unterverzeichnisse:
public:Eine Benutzeroberfläche, mit der sich der Status der intelligenten Waschmaschine ganz einfach steuern und beobachten lässt.functions:Ein vollständig implementierter Cloud-Dienst, der die intelligente Waschmaschine mit Cloud Functions for Firebase und Firebase Realtime Database verwaltet.
Die bereitgestellte Cloud-Ausführung umfasst die folgenden Funktionen in index.js:
fakeauth: Autorisierungsendpunkt für die Kontoverknüpfungfaketoken: Token-Endpunkt für die Kontoverknüpfungsmarthome: Endpunkt für die Smart-Home-Intent-Erfüllungreportstate:Ruft die Home Graph API bei Gerätestatusänderungen aufrequestsync:Ermöglicht Updates von Nutzergeräten, ohne dass die Kontoverknüpfung neu hergestellt werden muss
Mit Firebase verbinden
Rufen Sie das Verzeichnis washer-start auf und richten Sie die Firebase CLI mit Ihrem Integrationsprojekt ein:
cd washer-start firebase use <firebase-project-id>
Firebase-Projekt konfigurieren
Initialisieren Sie ein Firebase-Projekt.
firebase init
Wählen Sie die CLI-Features Realtime Database, Functions und die Hosting-Funktion aus, die Firebase Hosting umfasst.
? Which Firebase CLI features do you want to set up for this directory? Press Space to select features, then Enter to confirm your choices. ❯◉ Realtime Database: Configure a security rules file for Realtime Database and (optionally) provision default instance ◯ Firestore: Configure security rules and indexes files for Firestore ◉ Functions: Configure a Cloud Functions directory and its files ◉ Hosting: Configure files for Firebase Hosting and (optionally) set up GitHub Action deploys ◯ Hosting: Set up GitHub Action deploys ◯ Storage: Configure a security rules file for Cloud Storage ◯ Emulators: Set up local emulators for Firebase products ◯ Remote Config: Configure a template file for Remote Config ◯ Extensions: Set up an empty Extensions manifest
Dadurch werden die erforderlichen APIs und Funktionen für Ihr Projekt initialisiert.
Initialisieren Sie die Echtzeitdatenbank, wenn Sie dazu aufgefordert werden. Sie können den Standardspeicherort für die Datenbankinstanz verwenden.
? It seems like you haven't initialized Realtime Database in your project yet. Do you want to set it up? Yes ? Please choose the location for your default Realtime Database instance: us-central1
Da Sie den Code des Starterprojekts verwenden, wählen Sie die Standarddatei für die Sicherheitsregeln aus und achten Sie darauf, die vorhandene Datenbankregelndatei nicht zu überschreiben.
? File database.rules.json already exists. Do you want to overwrite it with the Realtime Database Security Rules for <project-ID>-default-rtdb from the Firebase Console? No
Wenn Sie Ihr Projekt neu initialisieren, wählen Sie Überschreiben aus, wenn Sie gefragt werden, ob Sie eine Codebasis initialisieren oder überschreiben möchten.
? Would you like to initialize a new codebase, or overwrite an existing one? Overwrite
Verwenden Sie beim Konfigurieren Ihrer Funktionen die Standarddateien und achten Sie darauf, die vorhandenen Dateien index.js und package.json im Projektbeispiel nicht zu überschreiben.
? What language would you like to use to write Cloud Functions? JavaScript ? Do you want to use ESLint to catch probable bugs and enforce style? No ? File functions/package.json already exists. Overwrite? No ? File functions/index.js already exists. Overwrite? No
Wenn Sie Ihr Projekt neu initialisieren, wählen Sie Nein aus, wenn Sie gefragt werden, ob Sie „functions/.gitignore“ initialisieren oder überschreiben möchten.
? File functions/.gitignore already exists. Overwrite? No
? Do you want to install dependencies with npm now? Yes
Konfigurieren Sie abschließend Ihre Hosting-Einrichtung so, dass das Verzeichnis public im Projektcode verwendet wird, und verwenden Sie die vorhandene Datei index.html. Wählen Sie Nein aus, wenn Sie gefragt werden, ob Sie ESLint verwenden möchten.
? What do you want to use as your public directory? public ? Configure as a single-page app (rewrite all urls to /index.html)? Yes ? Set up automatic builds and deploys with GitHub? No ? File public/index.html already exists. Overwrite? No
Wenn ESLint versehentlich aktiviert wurde, gibt es zwei Möglichkeiten, es zu deaktivieren:
- Rufen Sie über die Benutzeroberfläche den Ordner
../functionsim Projekt auf, wählen Sie die ausgeblendete Datei.eslintrc.jsaus und löschen Sie sie. Nicht mit dem ähnlich benannten.eslintrc.jsonverwechseln. - Über die Befehlszeile:
cd functions rm .eslintrc.js
In Firebase bereitstellen
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/<firebase-project-id>/overview Hosting URL: https://<firebase-project-id>.web.app
Mit diesem Befehl werden eine Webanwendung und mehrere Cloud Functions for Firebase bereitgestellt.
Öffnen Sie die Hosting-URL in Ihrem Browser (https://<firebase-project-id>.web.app), um die Webanwendung aufzurufen. Daraufhin wird die folgende Benutzeroberfläche angezeigt:
Diese Web-UI ist eine Drittanbieterplattform, mit der sich Gerätestatus ansehen oder ändern lassen. Klicken Sie auf AKTUALISIEREN, um Ihre Datenbank mit Geräteinformationen zu füllen. Auf der Seite werden keine Änderungen angezeigt, aber der aktuelle Status Ihrer Waschmaschine wird in der Datenbank gespeichert.
Jetzt ist es an der Zeit, den von Ihnen bereitgestellten Cloud-Dienst über die Developer Console mit Google Assistant zu verbinden.
Developer Console-Projekt konfigurieren
Geben Sie auf dem Tab Entwickeln einen Anzeigenamen für die Interaktion ein. Dieser Name wird in der Google Home App angezeigt.
Laden Sie unter App-Branding eine png-Datei für das App-Symbol mit einer Größe von 144 × 144 Pixeln und dem Namen
So aktivieren Sie die Kontoverknüpfung:
Client-ID |
|
Clientschlüssel |
|
Autorisierungs-URL |
|
Token-URL |
|
Geben Sie unter Cloud-Ausführungs-URL die URL Ihrer Cloud-Funktion ein, die die Smart-Home-Intents ausführt.
https://us-central1-
Klicken Sie auf Speichern, um die Projektkonfiguration zu speichern, und dann auf Weiter: Test, um Tests für Ihr Projekt zu aktivieren.
Jetzt können Sie mit der Implementierung der Webhooks beginnen, die erforderlich sind, um den Gerätestatus mit Assistant zu verknüpfen.
Verknüpfung mit Google Assistant
Wenn Sie Ihre Cloud-zu-Cloud-Integration testen möchten, müssen Sie Ihr Projekt mit einem Google-Konto verknüpfen. So können Sie über Google Assistant-Oberflächen und die Google Home App testen, die im selben Konto angemeldet sind.
- Öffnen Sie auf Ihrem Smartphone die Google Assistant-Einstellungen. Sie müssen mit demselben Konto angemeldet sein wie in der Console.
- Gehen Sie zu Google Assistant > Einstellungen > Smart-Home-Steuerung (unter „Assistant“).
- Klicken Sie oben rechts auf das Suchsymbol.
- Suchen Sie mit dem Präfix [test] nach Ihrer Test-App.
- Wählen Sie diesen Artikel aus. Google Assistant authentifiziert sich dann bei Ihrem Dienst und sendet eine
SYNC-Anfrage, in der Ihr Dienst aufgefordert wird, eine Liste der Geräte für den Nutzer bereitzustellen.
Öffnen Sie die Google Home App und prüfen Sie, ob Ihre Waschmaschine angezeigt wird.
Prüfen Sie, ob Sie die Waschmaschine per Sprachbefehl in der Google Home App steuern können. Außerdem sollte sich der Gerätestatus in der Web-UI der Cloud-Ausführung ändern.
Nachdem Sie eine einfache Waschmaschine bereitgestellt haben, können Sie die auf Ihrem Gerät verfügbaren Modi anpassen.
4. Modi hinzufügen
Mit dem Attribut action.devices.traits.Modes kann ein Gerät eine beliebige Anzahl von Einstellungen für einen Modus haben, von denen jeweils nur eine festgelegt werden kann. Sie fügen der Waschmaschine einen Modus hinzu, um die Größe der Wäscheladung zu definieren: klein, mittel oder groß.
SYNC-Antwort aktualisieren
Sie müssen Ihrer SYNC-Antwort in functions/index.js Informationen zum neuen Merkmal hinzufügen. Diese Daten werden im traits-Array und attributes-Objekt angezeigt, wie im folgenden Code-Snippet dargestellt.
index.js
app.onSync(body => {
return {
requestId: 'ff36a3cc-ec34-11e6-b1a0-64510650abcf',
payload: {
agentUserId: USER_ID,
devices: [{
id: 'washer',
type: 'action.devices.types.WASHER',
traits: [
'action.devices.traits.OnOff',
'action.devices.traits.StartStop',
'action.devices.traits.RunCycle',
// Add Modes trait
'action.devices.traits.Modes',
],
name: { ... },
deviceInfo: { ... },
attributes: {
pausable: true,
//Add availableModes
availableModes: [{
name: 'load',
name_values: [{
name_synonym: ['load'],
lang: 'en',
}],
settings: [{
setting_name: 'small',
setting_values: [{
setting_synonym: ['small'],
lang: 'en',
}]
}, {
setting_name: 'medium',
setting_values: [{
setting_synonym: ['medium'],
lang: 'en',
}]
}, {
setting_name: 'large',
setting_values: [{
setting_synonym: ['large'],
lang: 'en',
}]
}],
ordered: true,
}],
},
}],
},
};
});
Neue EXECUTE-Intent-Befehle hinzufügen
Fügen Sie der EXECUTE-Intent den Befehl action.devices.commands.SetModes hinzu, wie im folgenden Code-Snippet gezeigt.
index.js
const updateDevice = async (execution,deviceId) => {
const {params,command} = execution;
let state, ref;
switch (command) {
case 'action.devices.commands.OnOff':
state = {on: params.on};
ref = firebaseRef.child(deviceId).child('OnOff');
break;
case 'action.devices.commands.StartStop':
state = {isRunning: params.start};
ref = firebaseRef.child(deviceId).child('StartStop');
break;
case 'action.devices.commands.PauseUnpause':
state = {isPaused: params.pause};
ref = firebaseRef.child(deviceId).child('StartStop');
Break;
// Add SetModes command
case 'action.devices.commands.SetModes':
state = {load: params.updateModeSettings.load};
ref = firebaseRef.child(deviceId).child('Modes');
break;
}
QUERY-Antwort aktualisieren
Aktualisieren Sie als Nächstes Ihre QUERY-Antwort, um den aktuellen Status der Waschmaschine zu melden.
Fügen Sie die aktualisierten Änderungen den Funktionen queryFirebase und queryDevice hinzu, um den in der Echtzeitdatenbank gespeicherten Status abzurufen.
index.js
const queryFirebase = async (deviceId) => {
const snapshot = await firebaseRef.child(deviceId).once('value');
const snapshotVal = snapshot.val();
return {
on: snapshotVal.OnOff.on,
isPaused: snapshotVal.StartStop.isPaused,
isRunning: snapshotVal.StartStop.isRunning,
// Add Modes snapshot
load: snapshotVal.Modes.load,
};
}
const queryDevice = async (deviceId) => {
const data = await queryFirebase(deviceId);
return {
on: data.on,
isPaused: data.isPaused,
isRunning: data.isRunning,
currentRunCycle: [{ ... }],
currentTotalRemainingTime: 1212,
currentCycleRemainingTime: 301,
// Add currentModeSettings
currentModeSettings: {
load: data.load,
},
};
};
Berichtsstatus aktualisieren
Aktualisieren Sie abschließend die reportstate-Funktion, damit die aktuelle Beladungseinstellung der Waschmaschine an den Home-Graph gesendet wird.
index.js
const requestBody = {
requestId: 'ff36a3cc', /* Any unique ID */
agentUserId: USER_ID,
payload: {
devices: {
states: {
/* Report the current state of your washer */
[context.params.deviceId]: {
on: snapshot.OnOff.on,
isPaused: snapshot.StartStop.isPaused,
isRunning: snapshot.StartStop.isRunning,
// Add currentModeSettings
currentModeSettings: {
load: snapshot.Modes.load,
},
},
},
},
},
};
In Firebase bereitstellen
Führen Sie den folgenden Befehl aus, um die aktualisierte Integration bereitzustellen:
firebase deploy --only functions
Rufen Sie nach Abschluss der Bereitstellung die Web-Benutzeroberfläche auf und klicken Sie in der Symbolleiste auf die Schaltfläche Aktualisieren 
. Dadurch wird eine Synchronisierung angefordert, damit Assistant die aktualisierten SYNC-Antwortdaten erhält.
Sie können jetzt einen Befehl geben, um den Modus der Waschmaschine festzulegen, z. B.:
„Hey Google, stelle die Waschmaschine auf eine große Ladung.“
Außerdem können Sie Fragen zu Ihrer Waschmaschine stellen, z. B.:
„Hey Google, wie viel Wäsche ist in der Waschmaschine?“
5. Ein-/Aus-Schaltflächen hinzufügen
Das Attribut action.devices.traits.Toggles steht für benannte Aspekte eines Geräts, die den Status „wahr“ oder „falsch“ haben, z. B. ob sich die Waschmaschine im Turbomodus befindet.
SYNC-Antwort aktualisieren
Fügen Sie in Ihrer SYNC-Antwort Informationen zur neuen Geräteeigenschaft hinzu. Sie wird im traits-Array und im attributes-Objekt angezeigt, wie im folgenden Code-Snippet dargestellt.
index.js
app.onSync(body => {
return {
requestId: 'ff36a3cc-ec34-11e6-b1a0-64510650abcf',
payload: {
agentUserId: USER_ID,
devices: [{
id: 'washer',
type: 'action.devices.types.WASHER',
traits: [
'action.devices.traits.OnOff',
'action.devices.traits.StartStop',
'action.devices.traits.RunCycle',
'action.devices.traits.Modes',
// Add Toggles trait
'action.devices.traits.Toggles',
],
name: { ... },
deviceInfo: { ... },
attributes: {
pausable: true,
availableModes: [{
name: 'load',
name_values: [{
name_synonym: ['load'],
lang: 'en'
}],
settings: [{ ... }],
ordered: true,
}],
//Add availableToggles
availableToggles: [{
name: 'Turbo',
name_values: [{
name_synonym: ['turbo'],
lang: 'en',
}],
}],
},
}],
},
};
});
Neue EXECUTE-Intent-Befehle hinzufügen
Fügen Sie der EXECUTE-Intent den Befehl action.devices.commands.SetToggles hinzu, wie im folgenden Code-Snippet gezeigt.
index.js
const updateDevice = async (execution,deviceId) => {
const {params,command} = execution;
let state, ref;
switch (command) {
case 'action.devices.commands.OnOff':
state = {on: params.on};
ref = firebaseRef.child(deviceId).child('OnOff');
break;
case 'action.devices.commands.StartStop':
state = {isRunning: params.start};
ref = firebaseRef.child(deviceId).child('StartStop');
break;
case 'action.devices.commands.PauseUnpause':
state = {isPaused: params.pause};
ref = firebaseRef.child(deviceId).child('StartStop');
break;
case 'action.devices.commands.SetModes':
state = {load: params.updateModeSettings.load};
ref = firebaseRef.child(deviceId).child('Modes');
break;
// Add SetToggles command
case 'action.devices.commands.SetToggles':
state = {Turbo: params.updateToggleSettings.Turbo};
ref = firebaseRef.child(deviceId).child('Toggles');
break;
}
QUERY-Antwort aktualisieren
Aktualisieren Sie abschließend Ihre QUERY-Antwort, um den Turbomodus der Waschmaschine anzugeben. Fügen Sie die aktualisierten Änderungen den Funktionen queryFirebase und queryDevice hinzu, um den in der Realtime Database gespeicherten Status des Schalters abzurufen.
index.js
const queryFirebase = async (deviceId) => {
const snapshot = await firebaseRef.child(deviceId).once('value');
const snapshotVal = snapshot.val();
return {
on: snapshotVal.OnOff.on,
isPaused: snapshotVal.StartStop.isPaused,
isRunning: snapshotVal.StartStop.isRunning,
load: snapshotVal.Modes.load,
// Add Toggles snapshot
Turbo: snapshotVal.Toggles.Turbo,
};
}
const queryDevice = async (deviceId) => {
const data = queryFirebase(deviceId);
return {
on: data.on,
isPaused: data.isPaused,
isRunning: data.isRunning,
currentRunCycle: [{ ... }],
currentTotalRemainingTime: 1212,
currentCycleRemainingTime: 301,
currentModeSettings: {
load: data.load,
},
// Add currentToggleSettings
currentToggleSettings: {
Turbo: data.Turbo,
},
};
};
Berichtsstatus aktualisieren
Aktualisieren Sie abschließend die Funktion reportstate, damit im Home-Graph angezeigt wird, ob die Waschmaschine auf „Turbo“ eingestellt ist.
index.js
const requestBody = {
requestId: 'ff36a3cc', /* Any unique ID */
agentUserId: USER_ID,
payload: {
devices: {
states: {
/* Report the current state of your washer */
[context.params.deviceId]: {
on: snapshot.OnOff.on,
isPaused: snapshot.StartStop.isPaused,
isRunning: snapshot.StartStop.isRunning,
currentModeSettings: {
load: snapshot.Modes.load,
},
// Add currentToggleSettings
currentToggleSettings: {
Turbo: snapshot.Toggles.Turbo,
},
},
},
},
},
};
In Firebase bereitstellen
Führen Sie den folgenden Befehl aus, um die aktualisierten Funktionen bereitzustellen:
firebase deploy --only functions
Klicken Sie in der Web-UI auf die Schaltfläche Aktualisieren , um nach Abschluss der Bereitstellung eine Synchronisierung anzufordern.
Sie können jetzt einen Befehl geben, um die Waschmaschine in den Turbomodus zu versetzen. Sagen Sie dazu Folgendes:
„Hey Google, aktiviere den Turbo für die Waschmaschine.“
Sie können auch fragen, ob sich Ihre Waschmaschine bereits im Turbomodus befindet:
„Hey Google, ist meine Waschmaschine im Turbomodus?“
6. Fehler und Ausnahmen melden
Mit der Fehlerbehandlung in Ihrer Cloud-zu-Cloud-Integration können Sie Nutzern mitteilen, wenn Probleme dazu führen, dass EXECUTE- und QUERY-Antworten fehlschlagen. Die Benachrichtigungen sorgen für eine positivere Nutzererfahrung, wenn Nutzer mit Ihrem Smart-Home-Gerät und der Integration interagieren.
Wenn eine EXECUTE- oder QUERY-Anfrage fehlschlägt, sollte deine Integration einen Fehlercode zurückgeben. Wenn Sie beispielsweise einen Fehler auslösen möchten, wenn ein Nutzer versucht, die Waschmaschine mit geöffnetem Deckel zu starten, würde Ihre EXECUTE-Antwort in etwa so aussehen:
{
"requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"payload": {
"commands": [
{
"ids": [
"456"
],
"status": "ERROR",
"errorCode": "deviceLidOpen"
}
]
}
}
Wenn ein Nutzer jetzt bittet, die Waschmaschine zu starten, antwortet Assistant:
„Der Deckel der Waschmaschine ist offen. Bitte schließe ihn und versuch es noch einmal.“
Ausnahmen ähneln Fehlern, geben aber an, wenn einem Befehl eine Benachrichtigung zugewiesen ist, die die erfolgreiche Ausführung blockieren kann oder nicht. Eine Ausnahme kann über das Attribut StatusReport zugehörige Informationen enthalten, z. B. den Akkustand oder die letzte Statusänderung. Nicht blockierende Ausnahmecodes werden mit dem Status SUCCESS zurückgegeben, blockierende Ausnahmecodes mit dem Status EXCEPTIONS.
Im folgenden Code-Snippet findest du ein Beispiel für eine Antwort mit einer Ausnahme:
{
"requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"payload": {
"commands": [{
"ids": ["123"],
"status": "SUCCESS",
"states": {
"online": true,
"isPaused": false,
"isRunning": false,
"exceptionCode": "runCycleFinished"
}
}]
}
}
Assistant antwortet:
„Die Waschmaschine ist fertig.“
Wenn Sie Fehlerberichte für Ihre Waschmaschine hinzufügen möchten, öffnen Sie functions/index.js und fügen Sie die Fehlerklassendefinition wie im folgenden Code-Snippet hinzu:
index.js
app.onQuery(async (body) => {...});
// Add SmartHome error handling
class SmartHomeError extends Error {
constructor(errorCode, message) {
super(message);
this.name = this.constructor.name;
this.errorCode = errorCode;
}
}
Aktualisieren Sie die Ausführungsantwort, um den Fehlercode und den Fehlerstatus zurückzugeben:
index.js
const executePromises = [];
const intent = body.inputs[0];
for (const command of intent.payload.commands) {
for (const device of command.devices) {
for (const execution of command.execution) {
executePromises.push(
updateDevice(execution, device.id)
.then((data) => {
...
})
//Add error response handling
.catch((error) => {
functions.logger.error('EXECUTE', device.id, error);
result.ids.push(device.id);
if (error instanceof SmartHomeError) {
result.status = 'ERROR';
result.errorCode = error.errorCode;
}
})
);
}
}
}
Assistant kann Ihren Nutzern jetzt jeden Fehlercode mitteilen, den Sie melden. Im nächsten Abschnitt sehen Sie ein konkretes Beispiel.
7. Sekundäre Nutzerbestätigung hinzufügen
Sie sollten die sekundäre Nutzerbestätigung in Ihre Integration einbinden, wenn Ihr Gerät Modi hat, die gesichert werden müssen oder auf eine bestimmte Gruppe autorisierter Nutzer beschränkt sein sollten, z. B. ein Softwareupdate oder die Entsperrung einer Sperre.
Sie können die sekundäre Nutzerbestätigung für alle Gerätetypen und -merkmale implementieren und festlegen, ob die Sicherheitsabfrage jedes Mal erfolgt oder bestimmte Kriterien erfüllt werden müssen.
Es gibt drei unterstützte Bestätigungstypen:
Nochallenge: Eine Anfrage und Antwort, für die keine Authentifizierungsanfrage verwendet wird (dies ist das Standardverhalten)ackNeeded– sekundäre Nutzerbestätigung, die eine ausdrückliche Bestätigung („Ja“ oder „Nein“) erfordertpinNeeded– sekundäre Nutzerbestätigung, für die eine persönliche Identifikationsnummer (PIN) erforderlich ist
Fügen Sie in diesem Codelab dem Befehl zum Einschalten der Waschmaschine eine ackNeeded-Herausforderung und die Funktionalität hinzu, um einen Fehler zurückzugeben, wenn die sekundäre Bestätigungsaufgabe fehlschlägt.
Öffnen Sie functions/index.js und fügen Sie eine Fehlerklassendefinition hinzu, die den Fehlercode und den Bestätigungstyp zurückgibt, wie im folgenden Code-Snippet dargestellt:
index.js
class SmartHomeError extends Error { ... }
// Add secondary user verification error handling
class ChallengeNeededError extends SmartHomeError {
/**
* Create a new ChallengeNeededError
* @param {string} suvType secondary user verification challenge type
*/
constructor(suvType) {
super('challengeNeeded', suvType);
this.suvType = suvType;
}
}
Außerdem müssen Sie die Ausführungsantwort aktualisieren, um den challengeNeeded-Fehler zurückzugeben. Gehen Sie dazu so vor:
index.js
const executePromises = [];
const intent = body.inputs[0];
for (const command of intent.payload.commands) {
for (const device of command.devices) {
for (const execution of command.execution) {
executePromises.push(
updateDevice(execution, device.id)
.then((data) => {
...
})
.catch((error) => {
functions.logger.error('EXECUTE', device.id, error);
result.ids.push(device.id);
if (error instanceof SmartHomeError) {
result.status = 'ERROR';
result.errorCode = error.errorCode;
//Add error response handling
if (error instanceof ChallengeNeededError) {
result.challengeNeeded = {
type: error.suvType
};
}
}
})
);
}
}
}
Ändern Sie abschließend updateDevice so, dass die Waschmaschine nur ein- oder ausgeschaltet werden kann, wenn Sie dies ausdrücklich bestätigen.
index.js
const updateDevice = async (execution,deviceId) => {
const {challenge,params,command} = execution; //Add secondary user challenge
let state, ref;
switch (command) {
case 'action.devices.commands.OnOff':
//Add secondary user verification challenge
if (!challenge || !challenge.ack) {
throw new ChallengeNeededError('ackNeeded');
}
state = {on: params.on};
ref = firebaseRef.child(deviceId).child('OnOff');
break;
...
}
return ref.update(state)
.then(() => state);
};
In Firebase bereitstellen
Führen Sie den folgenden Befehl aus, um die aktualisierte Funktion bereitzustellen:
firebase deploy --only functions
Nachdem Sie den aktualisierten Code bereitgestellt haben, müssen Sie die Aktion bestätigen, wenn Sie Assistant bitten, Ihre Waschmaschine ein- oder auszuschalten. Gehen Sie dazu so vor:
Sie: „Hey Google, schalte die Waschmaschine ein.“
Assistant: „Möchten Sie die Waschmaschine wirklich einschalten?“
Sie: „Ja.“
In den Firebase-Protokollen finden Sie auch eine detaillierte Antwort für jeden Schritt des Ablaufs der sekundären Nutzerbestätigung.
8. Glückwunsch
Glückwunsch! Sie haben die Funktionen von Cloud-zu-Cloud-Integrationen durch die Merkmale Modes und Toggles erweitert und ihre Ausführung durch eine sekundäre Nutzerbestätigung gesichert.
Weitere Informationen
Hier sind einige Ideen, wie Sie tiefer in die Materie einsteigen können:
- Fügen Sie Ihren Geräten Funktionen zur lokalen Ausführung hinzu.
- Verwenden Sie einen anderen Typ der Bestätigungsaufgabe für die sekundäre Nutzerbestätigung, um den Gerätestatus zu ändern.
- Aktualisieren Sie die QUERY-Antwort für das
RunCycle-Attribut, damit sie dynamisch aktualisiert wird. - Dieses GitHub-Beispiel ansehen