Konversationsaktionen werden am 13. Juni 2023 eingestellt. Weitere Informationen finden Sie unter Einstellung von Konversationsaktionen.

Auftragsausführung mit der Node.js-Clientbibliothek für Actions on Google erstellen

Wenn Sie einen Auftragsausführungs-Webhook in JavaScript erstellen, wird die Node.js-Clientbibliothek von Actions on Google empfohlen, um auf die Actions on Google-Plattform zuzugreifen und mit dieser zu interagieren.

Einführung

Die Node.js-Clientbibliothek ist eine Auftragsausführungsbibliothek für Actions on Google, die folgende Funktionen bietet:

  • Unterstützt alle Funktionen von Actions on Google, einschließlich Text- und Rich-Media-Antworten, Kontoanmeldung, Datenspeicherung, Transaktionen und mehr.
  • Stellt eine idiomatische Abstraktionsschicht in JavaScript bereit, die die Conversation HTTP/JSON Webhook API umschließt.
  • Verarbeitet die allgemeinen Details der Kommunikation zwischen der Auftragsausführung und der Actions on Google-Plattform.
  • Kann mit bekannten Paketverwaltungstools wie npm oder yarn installiert werden.
  • Damit können Sie den Auftragsausführungs-Webhook ganz einfach auf serverlosen Computing-Plattformen wie Cloud Functions for Firebase oder AWS Lambda bereitstellen. Sie können Ihren Auftragsausführungs-Webhook auch in einem Cloud-Dienstanbieter oder in einer selbst gehosteten und selbstverwalteten Umgebung hosten.
  • Kompatibel mit Node.js 6.0.0 und höher.

Sie können die Clientbibliothek in Verbindung mit der Dialogflow-Integration für Actions on Google oder mit dem Actions SDK verwenden.

Vollständige Codebeispiele zur Verwendung der Clientbibliothek finden Sie auf der Seite „Beispiele“.

API-Referenz ansehen

Die API-Referenz wird auf der GitHub-Seite zur Actions on Google-Node.js-Clientbibliothek gehostet.

Sie können auch eine lokale Kopie der Referenz generieren. Führen Sie dazu den folgenden Befehl in dem Verzeichnis aus, in das Sie den Clientbibliothekscode heruntergeladen haben:

yarn docs

Die generierten Dokumente sind im Ordner docs des Verzeichnisses verfügbar, in das Sie den Clientbibliothekscode heruntergeladen haben.

Funktionsweise

Bevor Sie die Clientbibliothek verwenden, sollten Sie sich darüber informieren, wie Ihr Webhook-Webhook die Clientbibliothek verwendet, um Nutzeranfragen zu verarbeiten, die von Actions on Google an Ihre Auftragsausführung gesendet werden.

Wenn Sie einen Webhook für die Auftragsausführung in JavaScript erstellen, können Sie Ihren Code in einer serverlosen Computing-Umgebung wie Cloud Functions for Firebase oder AWS Lambda bereitstellen und hosten. Sie können den Code auch selbst hosten, indem Sie das Express-Webframework nutzen.

Innerhalb der Laufzeitumgebung kann der Auftragsausführungs-Webhook Funktionen in der Clientbibliothek aufrufen, um Nutzeranfragen zu verarbeiten und Antworten an Actions on Google zurückzugeben, um sie in die Nutzerausgabe zu rendern.

Die wichtigsten Aufgaben, die der Auftragsausführungs-Webhook mithilfe der Clientbibliothek verarbeitet, sind unten kurz zusammengefasst:

Abbildung 1. Allgemeine Architektur der Node.js-Clientbibliothek
  1. Nutzeranfragen empfangen: Wenn ein Nutzer eine Anfrage an Google Assistant sendet, sendet die Actions on Google-Plattform eine HTTP-Anfrage an den Webhook für die Auftragsausführung. Die Anfrage enthält eine JSON-Nutzlast, die den Intent und andere Daten wie den Rohtext der Nutzereingabe und die Oberflächenfunktionen des Geräts des Nutzers enthält. Weitere Beispiele für die Inhalte der JSON-Nutzlast finden Sie in den Leitfäden für das Dialogflow-Webhook-Format und die Conversation-Webhook-Format-Anleitungen.
  2. Framework der Formataufruf von Anrufen: Bei unterstützten Frameworks erkennt die Clientbibliothek das Aufrufformat des Frameworks automatisch (z. B. wenn die Anfrage aus dem Express-Web-Framework oder von AWS Lambda stammt) und weiß, wie die Kommunikation mit der Actions on Google-Plattform nahtlos erfolgen kann.
  3. Verarbeitung von Dienst-Handlern:Die Clientbibliothek stellt die Unterhaltung HTTP/JSON-Webhook API für Dialogflow und das Actions SDK als Dienstfunktion dar. Der Webhook für die Auftragsausführung verwendet den entsprechenden Dienst, um eine globale app-Instanz zu erstellen. Die Instanz app fungiert als Handler für HTTP-Anfragen und versteht das spezifische Protokoll des Dienstes.
  4. Unterhaltungsverarbeitung: Die Clientbibliothek stellt Informationen pro Unterhaltung als Conversation-Objekt dar, das an die Instanz app angehängt ist. Der Webhook für die Auftragsausführung kann das objekt Conversation für unterhaltungsübergreifende Daten oder Statusinformationen abrufen, Antworten an Nutzer senden oder das Mikrofon schließen.
  5. Verarbeitung der Mitte: Mit der Clientbibliothek können Sie Ihre eigene Middleware für Kommunikationsdienste erstellen. Sie besteht aus einer oder mehreren Funktionen, die Sie definieren, bevor die Intent-Handler automatisch aufgerufen werden. Der Webhook für die Auftragsausführung kann Ihre Middleware verwenden, um dem Conversation-Objekt Attribute oder Hilfsklassen hinzuzufügen.
  6. Verarbeitung von Intent-Handlern: Mit der Clientbibliothek können Sie Handler für Intents definieren, die der Webhook erkennt. Bei Dialogflow leitet die Clientbibliothek die Anfrage an den richtigen Intent-Handler weiter. Dazu ordnet er den genauen String des Intent-Namens zu, der in der Dialogflow-Konsole definiert wurde. Beim Actions SDK wird diese basierend auf der intent-Property weitergeleitet, die von Actions on Google gesendet wurde.
  7. Antworten an Nutzer senden:Zum Erstellen von Antworten ruft der Webhook für die Auftragsausführung die Funktion Conversation#ask() auf. Die Funktion ask() kann mehrmals aufgerufen werden, um die Antwort inkrementell zu erstellen. Die Clientbibliothek serialisiert die Antwort in eine HTTP-Anfrage mit einer JSON-Nutzlast und sendet sie an Actions on Google. Die Funktion close() verhält sich ähnlich wie ask(), schließt aber die Unterhaltung.

Lokale Entwicklungsumgebung einrichten

Bevor Sie den Webhook für die Auftragsausführung implementieren, müssen Sie die Clientbibliothek installieren.

Clientbibliothek installieren

Die einfachste Methode zum Installieren der Clientbibliothek in deiner lokalen Entwicklungsumgebung ist die Verwendung eines Paketmanagers wie npm oder yarn.

Führen Sie zur Installation einen der folgenden Befehle im Terminal aus:

  • Bei Verwendung von npm: npm install actions-on-google
  • Bei Verwendung von Garn: yarn add actions-on-google

Projektordner einrichten

Je nachdem, wo Sie den Auftragsausführungs-Webhook bereitstellen möchten (Google Cloud Functions for Firebase, AWS Lambda oder selbstgehosteter Express), müssen Sie möglicherweise eine bestimmte Projektordnerstruktur erstellen, um Ihre Dateien zu speichern.

Wenn Sie beispielsweise Cloud Functions for Firebase verwenden, können Sie die erforderlichen Projektordner wie in Node.js und Firebase CLI einrichten und Firebase for Cloud Functions initialisieren beschrieben einrichten. Für Cloud Functions for Firebase schreiben Sie normalerweise einen Webhook für die Auftragsausführung in die Datei /functions/index.js.

Anwendungsinstanz erstellen

Actions on Google verwendet bestimmte Nachrichtenformate für den Austausch von Anfragen und Antworten mit dem Webhook für die Auftragsausführung, je nachdem, ob Sie eine dialogorientierte Aktion mit Dialogflow oder dem Actions SDK oder einer Smart-Home-Aktion erstellen.

Um diese verschiedenen Anfrage- und Antwortprotokolle darzustellen, bietet die Clientbibliothek drei Dienstfunktionen:

Das Conversation-Webhook-Protokoll wird von beiden Kommunikationsdiensten (Dialogflow und Actions SDK) verwendet. Nachrichten werden jedoch von jedem Dienst anders umschlossen.

Sie verwenden einen Dienst, um eine app-Instanz zu erstellen. Die Instanz app kapselt den globalen Status und die Auftragsausführungslogik für Ihren Webhook und übernimmt die Kommunikation zwischen Actions on Google und Ihrer Auftragsausführung über das dienstspezifische Protokoll.

Sie können die Attribute der Instanz app konfigurieren und die Methoden aufrufen, um das Verhalten des Webhook-Webhooks weiterzuleiten. Sie können die Instanz app auch einfach an eine serverlose Computing-Umgebung wie Cloud Functions for Firebase anschließen, die JavaScript-Funktionen als Handler für HTTP-Anfragen akzeptiert.

So erstellen Sie eine app-Instanz im Webhook der Auftragsausführung:

  1. Rufen Sie die Funktion require() auf, um das Modul „actions-on-google“ zu importieren und den gewünschten Dienst zu laden. Das folgende Snippet zeigt beispielsweise, wie Sie den dialogflow-Dienst und einige Elemente, die zum Erstellen von Antworten verwendet werden, laden und der Konstante dialogflow zuweisen können: 

    // Import the service function and various response classes
const {
  dialogflow,
  actionssdk,
  Image,
  Table,
  Carousel,
} = require('actions-on-google');

    Hier bezieht sich actions-on-google auf eine Abhängigkeit, die in einer package.json-Datei in Ihrem Projektordner angegeben ist. Ein Beispiel finden Sie in dieser Beispieldatei package.json.

    Beim Abrufen einer app-Instanz können Sie optional Klassen für reiche Antworten, Hilfs-Intents und andere Actions on Google-Funktionen angeben, die Sie verwenden möchten. Eine vollständige Liste der gültigen Klassen, die Sie laden können, finden Sie in der Referenzdokumentation zu den Modulen Conversation Response und Helper Intent.

  2. Erstellen Sie eine app-Instanz, indem Sie den geladenen Dienst aufrufen. Beispiel: 

    const app = dialogflow();

  3. Wenn Sie die app-Instanz bei der Initialisierung konfigurieren möchten, können Sie beim Aufrufen des Dienstes ein options-Objekt als erstes Argument angeben. Weitere Informationen finden Sie unter DialogflowOptions. Das folgende Snippet zeigt beispielsweise, wie die unformatierte JSON-Nutzlast aus der Nutzeranfrage oder -antwort durch Festlegen des Flags { debug: true } protokolliert wird:

const app = dialogflow({
  debug: true
});

Handler für Ereignisse festlegen

Zum Verarbeiten von Actions on Google-Ereignissen, die von der Clientbibliothek während der Interaktion mit Ihrer Aktion erstellt werden, verwenden Sie die Clientbibliothek. Damit können Sie Handler erstellen, um Nutzeranfragen zu verarbeiten und Antworten zu senden.

Sie können Funktionen erstellen, die als Handler für die folgenden Haupttypen von Ereignissen dienen, die von der Clientbibliothek erkannt werden:

  • Intent-Ereignisse:Intents sind eindeutige Kennungen, die Actions on Google an Ihre Auftragsausführung sendet, wenn ein Nutzer eine bestimmte Funktion anfordert. Wenn Sie Dialogflow verwenden, entspricht dies Dialogflow, das eine Nutzeranfrage einem Intent in Ihrem Dialogflow-Agent zuordnet.
  • Fehlerereignisse: Wenn ein Fehler in JavaScript oder Clientbibliothek auftritt, können Sie die Fehlerausnahme mithilfe der Funktion catch der app-Instanz entsprechend verarbeiten. Sie sollten eine einzelne catch-Funktion implementieren, um alle Fehler zu verarbeiten, die für die Auftragsausführung wichtig sind.
  • Fallback-Ereignisse:Ein Fallback-Ereignis tritt auf, wenn der Nutzer eine Anfrage sendet, die von Actions on Google nicht erkannt wird. Mit der Funktion fallback der app-Instanz können Sie einen generischen Fallback-Handler registrieren. Dieser wird ausgelöst, wenn kein Intent-Handler für die eingehende Auftragsausführung zugeordnet wurde. Sie sollten eine einzelne fallback-Funktion zur Verarbeitung aller Fallback-Ereignisse implementieren. Wenn Sie Dialogflow verwenden, kann Dialogflow einen bestimmten Fallback-Intent auslösen, wenn kein anderer Intent zugeordnet wird. Sie sollten einen entsprechenden Intent-Handler für diesen Fallback-Intent erstellen.

Immer wenn der Nutzer eine Anfrage an Ihre Aktion sendet, erstellt die Instanz app ein Conversation-Objekt, das diese Unterhaltungssitzung darstellt. Der Zugriff auf dieses Objekt erfolgt über den Variablennamen conv, der als erstes Funktionsargument in der Intent-Handler-Funktion übergeben wird. In der Regel verwenden Sie in Ihren Handlern das Objekt conv, um eine Antwort an den Nutzer zu senden.

Nutzerabfragen können auch Parameter enthalten, die von Ihrer Aktion extrahiert und zum Verfeinern von Antworten verwendet werden können.

  • Wenn Sie das Actions SDK verwenden, definieren Sie die Parameter im Aktionspaket. Ein Beispiel für das Extrahieren von Parametern aus Intents finden Sie im Eliza-Codebeispiel.
  • Wenn Sie Dialogflow verwenden, können Sie über die Variable params auf die Parameterwerte zugreifen. Beispiele für die Verarbeitung von Intents mit Parametern in Dialogflow finden Sie unter Zugriff auf Parameter und Kontexte.

Handler für Intents festlegen

Wenn Sie den Handler für einen Intent festlegen möchten, rufen Sie die Funktion intent() Ihrer app-Instanz auf. Wenn Sie beispielsweise Dialogflow verwenden, ist dies die Funktion DialogflowApp#intent(). Geben Sie in den Argumenten den Intent-Namen an und geben Sie eine Handler-Funktion an.

Wenn Sie Dialogflow verwenden, müssen Sie nicht für jeden Intent in Ihrem Agent Handler festlegen. Stattdessen können Sie den integrierten Antwort-Handler von Dialogflow nutzen, um Intents automatisch zu verarbeiten, ohne eigene Handler-Funktionen zu implementieren. Der Standard-Begrüßungs-Intent kann beispielsweise so an Dialogflow delegiert werden.

Das folgende Beispiel zeigt Intent-Handler für die Intents „Begrüßung“ und „Tschüss“. Die Funktion des anonymen Handlers verwendet ein conv-Argument und sendet über die Funktion conv.ask() eine einfache Stringantwort an den Nutzer.

app.intent('Default Welcome Intent', (conv) => {
  conv.ask('How are you?');
});

app.intent('bye', (conv) => {
  conv.close('See you later!');
});

Die Funktion close() ähnelt ask(), mit der Ausnahme, dass das Mikrofon geschlossen und die Unterhaltung beendet wird.

Weitere Informationen zum Erstellen von Handlern für Intents finden Sie unter Intent-Handler erstellen.

Handler für Fehlerereignisse festlegen

Rufen Sie die Funktion catch() Ihrer app-Instanz auf, um die Handler für Fehler festzulegen. Wenn Sie Dialogflow verwenden, ist dies beispielsweise die Funktion DialogflowApp#catch().

Das folgende Beispiel zeigt einen einfachen Catch-Error-Handler, der den Fehler an die Konsolenausgabe und eine einfache Stringantwort sendet, um den Nutzer über die Funktion conv.ask() aufzufordern:

app.catch((conv, error) => {
  console.error(error);
  conv.ask('I encountered a glitch. Can you say that again?');
});

Handler für Fallback-Ereignisse festlegen

Wenn Sie einen Intent für den allgemeinen Fallback festlegen möchten, wenn kein Intent für die eingehende Anfrage für die Auftragsausführung zugeordnet wird, rufen Sie die Funktion fallback() Ihrer app-Instanz auf. Wenn Sie Dialogflow verwenden, ist dies beispielsweise die Funktion DialogflowApp#fallback().

Das folgende Beispiel zeigt einen einfachen Fallback-Handler, der eine einfache Stringantwort zurückgibt, um den Nutzer über die Funktion conv.ask() aufzufordern:

app.fallback((conv) => {
  conv.ask(`I couldn't understand. Can you say that again?`);
});

Intent-Handler erstellen

In diesem Abschnitt werden einige häufige Anwendungsfälle beschrieben, wenn Sie Intent-Handler mit der Clientbibliothek implementieren. Informationen zur Übereinstimmung der Clientbibliothek mit dem Intent finden Sie im Abschnitt "Verarbeitung des Intent-Handlers" unter Funktionsweise.

Auf Parameter und Kontexte zugreifen

Wenn Sie Dialogflow verwenden, können Sie Parameter und Kontexte in Ihrem Dialogflow-Agent definieren, um Statusinformationen beizubehalten und den Unterhaltungsfluss zu steuern.

Parameter sind nützlich, um wichtige Wörter, Wortgruppen oder Werte in Nutzerabfragen zu erfassen. Dialogflow extrahiert die entsprechenden Parameter aus Nutzerabfragen während der Laufzeit. Sie können diese Parameterwerte in Ihrem Webhook für die Auftragsausführung verarbeiten, um zu bestimmen, wie auf Nutzer reagiert werden soll.

Immer wenn der Nutzer eine Anfrage an Ihre Aktion sendet, erstellt die Instanz DialogflowApp ein parameters-Objekt, das die Parameterwerte darstellt, die Dialogflow aus dieser Anfrage extrahiert hat. Dieses Objekt wird über den Variablennamen params aufgerufen.

Im folgenden Snippet sehen Sie, wie Sie über das params-Objekt auf das Attribut name zugreifen können, wenn der Nutzer eine Anfrage sendet:

app.intent('Default Welcome Intent', (conv, params) => {
  conv.ask(`How are you, ${params.name}?`);
});

Hier ist ein alternatives Snippet, das ebenfalls funktioniert. Die geschweiften Klammern ({}) führen eine JavaScript-Destrukturierung aus, um das Attribut name aus dem Objekt parameters zu verwenden und als lokale Variable zu verwenden:

app.intent('Default Welcome Intent', (conv, {name}) => {
  conv.ask(`How are you, ${name}?`);
});

Im folgenden Snippet lautet der Parametername full-name, ist aber destrukturiert und einer lokalen Variablen mit dem Namen name zugewiesen:

app.intent('Default Welcome Intent', (conv, {'full-name': name}) => {
  conv.ask(`How are you, ${name}?`);
});

Kontexte sind ein erweitertes Feature von Dialogflow. Sie können Kontexte verwenden, um den Unterhaltungsstatus, den Ablauf und den Zweig zu verwalten. Die Clientbibliothek bietet Zugriff auf einen Kontext über das DialogflowConversation#contexts-Objekt. Das folgende Snippet zeigt, wie Sie einen Kontext programmatisch in Ihrem Webhook für die Auftragsausführung festlegen und das Kontextobjekt abrufen können:

app.intent('intent1', (conv) => {
  const lifespan = 5;
  const contextParameters = {
    color: 'red',
  };
  conv.contexts.set('context1', lifespan, contextParameters);
  // ...
  conv.ask('...');
});

app.intent('intent2', (conv) => {
  const context1 = conv.contexts.get('context1');
  const contextParameters = context1.parameters;
  // ...
  conv.ask('...');
});

app.intent('intent3', (conv) => {
  conv.contexts.delete('context1');
  // ...
  conv.ask('...');
});

Auf Hilfs-Intent-Ergebnisse zugreifen

Der Einfachheit halber bietet die Clientbibliothek Helper-Klassen, mit denen häufig verwendete Nutzerdatentypen umschlossen werden und die häufig von Aktionen angefordert werden. Dazu gehören Klassen, die die Ergebnisse für die verschiedenen Helper-Intents von Actions on Google darstellen. Sie verwenden Hilfs-Intents, wenn Google Assistant Teile der Unterhaltung übernehmen soll, in denen der Nutzer seine Daten zur Verfügung stellen muss, um die Unterhaltung fortzusetzen.

Beispiel: Bestätigungshilfsergebnisse

Mit dem Intent-Assistent können Sie eine „Ja“/„Nein“-Bestätigung vom Nutzer anfordern und die entsprechende Antwort erhalten. Im folgenden Snippet sehen Sie, wie der Webhook die Antwort anhand der Ergebnisse anpassen kann, die vom Bestätigungs-Intent zurückgegeben werden. Ein ausführlicheres Beispiel finden Sie in der Referenzdokumentation zu Confirmation.

// Create Dialogflow intent with `actions_intent_CONFIRMATION` event
app.intent('get_confirmation', (conv, input, confirmation) => {
  if (confirmation) {
    conv.close(`Great! I'm glad you want to do it!`);
  } else {
    conv.close(`That's okay. Let's not do it now.`);
  }
});

Das folgende Snippet zeigt, wie der Webhook der Auftragsausführung die Antwort auf Basis der Nutzereingabe für ein Karussell anpassen kann. Mit der Komponente „Karussell“ kann Ihre Aktion eine Auswahl von Optionen zur Auswahl bieten. Ein ausführlicheres Beispiel finden Sie in der Referenzdokumentation zu Carousel.

app.intent('carousel', (conv) => {
  conv.ask('Which of these looks good?');
  conv.ask(new Carousel({
    items: {
      car: {
        title: 'Car',
        description: 'A four wheel vehicle',
        synonyms: ['automobile', 'vehicle'],
      },
      plane: {
        title: 'Plane',
        description: 'A flying machine',
        synonyms: ['aeroplane', 'jet'],
      }
    }
  }));
});

// Create Dialogflow intent with `actions_intent_OPTION` event
app.intent('get_carousel_option', (conv, input, option) => {
  if (option === 'one') {
    conv.close(`Number one is a great choice!`);
  } else {
    conv.close(`Number ${option} is a great choice!`);
  }
});

Antwortobjekte für Unterhaltungen konfigurieren

Die Clientbibliothek bietet Unterhaltungsantwortklassen für Rich-Antworten oder Multimedia-Elemente, die von deiner Aktion gesendet werden können. Normalerweise senden Sie diese Antworten oder Elemente, wenn Nutzer keine weiteren Angaben machen müssen, um die Unterhaltung fortzusetzen.

Beispiel: Bild

Das folgende Snippet zeigt, wie der Webhook der Auftragsausführung eine Image in einer Antwort senden kann, die automatisch von der Bibliothek an eine BasicCard-Antwort angehängt wird:

app.intent('Default Welcome Intent', (conv) => {
  conv.ask('Hi, how is it going?');
  conv.ask(`Here's a picture of a cat`);
  conv.ask(new Image({
    url: '/web/fundamentals/accessibility/semantics-builtin/imgs/160204193356-01-cat-500.jpg',
    alt: 'A cat',
  }));
});

Asynchrone Funktionsaufrufe ausführen

Die Node.js-Clientbibliothek von Actions on Google ist für die asynchrone Programmierung konzipiert. Der Intent-Handler kann ein Promise zurückgeben, das aufgelöst wird, wenn der Webhook der Auftragsausführung fertig ist und eine Antwort generiert hat.

Im folgenden Snippet sehen Sie, wie Sie einen asynchronen Funktionsaufruf ausführen, um ein Promise-Objekt zurückzugeben und mit einer Nachricht zu antworten, wenn der Webhook für die Auftragsausführung den „Begrüßung“-Intent empfängt. In diesem Snippet wird durch das Versprechen sichergestellt, dass der Webhook für die Auftragsausführung eine dialogorientierte Antwort erst zurückgibt, nachdem das Versprechen für den externen API-Aufruf aufgelöst wurde.

In diesem Beispiel verwenden wir eine Fake-API zum Abrufen der Wetterdaten.

/**
 * Make an external API call to get weather data.
 * @return {Promise<string>}
 */
const forecast = () => {
  // ...
};

app.intent('Default Welcome Intent', (conv) => {
  return forecast().then((weather) => {
    conv.ask('How are you?');
    conv.ask(`Today's weather is ${weather}.`);
  });
});

Das folgende optimierte Code-Snippet hat den gleichen Effekt, verwendet jedoch die Funktion async await von ECMA 2017 (Node.js-Version 8). Damit Sie diesen Code mit Cloud Functions for Firebase verwenden können, müssen Sie die richtige Version von firebase-tools verwenden und die richtige Konfiguration verwenden.

app.intent('Default Welcome Intent', async (conv) => {
  const weather = await forecast();
  conv.ask('How are you?');
  conv.ask(`Today's weather is ${weather}.`);
});

Unterhaltungsdaten speichern

Mit der Clientbibliothek kann der Webhook der Auftragsausführung Daten in Unterhaltungen zur späteren Verwendung speichern. Die wichtigsten Objekte, die Sie für die Datenspeicherung verwenden können, sind:

Das folgende Snippet zeigt, wie der Webhook der Auftragsausführung Daten in einer beliebigen von Ihnen definierten Property (someProperty) speichern und an das Objekt Conversation#user.storage anhängen kann. Ein ausführlicheres Beispiel finden Sie in der Referenzdokumentation zu Conversation#user.storage.

app.intent('Default Welcome Intent', (conv) => {
  conv.user.storage.someProperty = 'someValue';
  conv.ask('...');
});

Mit dem Objekt Conversation#user können Sie Informationen über den Nutzer abrufen, einschließlich einer String-ID und personenbezogener Daten. Für bestimmte Felder wie conv.user.name.display und conv.user.email muss conv.ask(new Permission) für NAME bzw. conv.ask(new SignIn) für Google Log-in angefordert werden.

const {Permission} = require('actions-on-google');
app.intent('Default Welcome Intent', (conv) => {
  if (conv.user.last.seen) {
    conv.ask('Welcome back! How are you?');
  } else {
    conv.ask('Nice to meet you! How are you doing?');
  }
});

app.intent('permission', (conv) => {
  conv.ask(new Permission({
    context: 'To greet you personally',
    permissions: 'NAME',
  }));
});

// Create Dialogflow intent with `actions_intent_PERMISSION` event
app.intent('get_permission', (conv, input, granted) => {
  if (granted) {
    conv.close(`Hi ${conv.user.name.display}!`);
  } else {
    // User did not grant permission
    conv.close(`Hello!`);
  }
});

Mit Middleware skalieren

Sie können die Clientbibliothek über Middleware erweitern.

Die Middleware-Ebene besteht aus einer oder mehreren von Ihnen definierten Funktionen, die die Clientbibliothek automatisch ausführt, bevor der Intent-Handler aufgerufen wird. Mit einer Middleware-Ebene können Sie die Instanz Conversation ändern und zusätzliche Funktionen hinzufügen.

Die Dialogflow- und Actions SDK-Dienste bieten die Funktion app.middleware(), mit der Sie Attribute oder Hilfsklassen zur Instanz Conversation hinzufügen können.

Das folgende Snippet zeigt ein Beispiel für die Verwendung von Middleware:

class Helper {
  constructor(conv) {
    this.conv = conv;
  }

  func1() {
    this.conv.ask(`What's up?`);
  }
}

app.middleware((conv) => {
  conv.helper = new Helper(conv);
});

app.intent('Default Welcome Intent', (conv) => {
  conv.helper.func1();
});

App exportieren

Damit der Webhook für die Auftragsausführung für ein Web-Framework oder eine serverlose Computing-Plattform bereitgestellt wird, müssen Sie das app-Objekt als öffentlich zugänglichen Webhook exportieren. Die Clientbibliothek unterstützt die Bereitstellung in einer Reihe von Umgebungen.

Die folgenden Snippets zeigen, wie Sie app in verschiedenen Laufzeiten exportieren können:

Beispiel: Cloud Functions for Firebase

const functions = require('firebase-functions');
// ... app code here
exports.fulfillment = functions.https.onRequest(app);

Beispiel: Dialogflow-Inline-Editor

const functions = require('firebase-functions');

// ... app code here

// Exported function name must be 'dialogflowFirebaseFulfillment'
exports.dialogflowFirebaseFulfillment = functions.https.onRequest(app);

Beispiel: Selbst gehosteter Express-Server (einfach)

const express = require('express');
const bodyParser = require('body-parser');  

// ... app code here

express().use(bodyParser.json(), app).listen(3000);

Beispiel: Selbst gehosteter Express-Server (mehrere Routen)

const express = require('express');
const bodyParser = require('body-parser');

// ... app code here

const expressApp = express().use(bodyParser.json());

expressApp.post('/fulfillment', app);

expressApp.listen(3000);

Beispiel: AWS Lambda API-Gateway

// ... app code here

exports.fulfillment = app;