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

Die Node.js-Clientbibliothek für Actions on Google ist die empfohlene Methode, um auf die Actions on Google-Plattform zuzugreifen und damit zu interagieren, wenn Sie einen Auftragsausführungs-Webhook in JavaScript erstellen.

Einführung

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

  • Unterstützt alle Actions on Google-Funktionen, einschließlich Text- und umfangreiche Multimedia-Antworten, Kontoanmeldung, Datenspeicher, Transaktionen und mehr.
  • Bietet eine idiomatische Abstraktionsschicht in JavaScript, die die HTTP/JSON-Webhook API für die Unterhaltung umschließt.
  • Übernimmt die Low-Level-Kommunikationsdetails zwischen der Auftragsausführung und der Actions on Google-Plattform.
  • Sie können mit vertrauten Paketverwaltungstools wie npm oder yarn installiert werden.
  • Ermöglicht das einfache Bereitstellen des Webhooks für die Auftragsausführung auf serverlosen Computing-Plattformen wie Cloud Functions for Firebase oder AWS Lambda. Sie können den Auftragsausführungs-Webhook auch auf einem Cloud-Dienstanbieter oder in einer selbst gehosteten und selbstverwalteten Umgebung hosten.
  • Es ist mit Node.js v6.0.0 und höher kompatibel.

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 für die Verwendung der Clientbibliothek finden Sie auf der Beispielseite.

API-Referenz ansehen

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

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

yarn docs

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

Funktionsweise

Bevor Sie die Clientbibliothek verwenden, sollten Sie wissen, wie der Auftragsausführungs-Webhook die Clientbibliothek verwendet, um Nutzeranfragen zu verarbeiten, die von Actions on Google an die Auftragsausführung gesendet werden.

Wenn Sie einen Auftragsausführungs-Webhook in JavaScript erstellen, können Sie Ihren Code in einer serverlosen Computing-Umgebung wie Cloud Functions for Firebase oder AWS Lambda von Google bereitstellen und hosten. Mit dem Express-Web-Framework können Sie den Code auch ohne zusätzlichen Aufwand selbst hosten.

Innerhalb der Laufzeitumgebung kann der Auftragsausführungs-Webhook Funktionen in der Clientbibliothek aufrufen, um Nutzeranfragen zu verarbeiten und Antworten für das Rendering in die Nutzerausgabe an Actions on Google zurückzusenden.

Die wichtigsten Aufgaben, die Ihr Auftragsausführungs-Webhook mithilfe der Clientbibliothek verarbeitet, werden im Folgenden kurz zusammengefasst:

Abbildung 1. Gesamtarchitektur 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 Ihren Auftragsausführungs-Webhook. Die Anfrage enthält eine JSON-Nutzlast, die den Intent und andere Daten wie den Rohtext der Nutzereingabe und die Oberflächenfunktionen des Nutzergeräts enthält. Weitere Beispiele für den Inhalt der JSON-Nutzlast finden Sie in den Anleitungen zum Dialogflow-Webhook-Format und zum Format von Konversations-Webhooks.
  2. Erkennung des Framework-Aufrufformats: Bei unterstützten Frameworks erkennt die Clientbibliothek automatisch das Aufrufformat des Frameworks (z. B. wenn die Anfrage vom Express-Web-Framework oder von AWS Lambda stammt) und weiß, wie die Kommunikation mit der Actions on Google-Plattform nahtlos abgewickelt werden kann.
  3. Dienst-Handler-Verarbeitung:Die Clientbibliothek stellt die HTTP/JSON-Webhook API für Dialogflow und das Actions SDK als Dienstfunktion dar. Der Auftragsausführungs-Webhook erstellt mit dem entsprechenden Dienst eine globale app-Instanz. 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 Auftragsausführungs-Webhook kann das Objekt Conversation verwenden, um dialogorientierte gespeicherte Daten oder Statusinformationen abzurufen, Antworten an Nutzer zu senden oder das Mikrofon zu schließen.
  5. Middleware-Verarbeitung:Mit der Clientbibliothek können Sie Ihre eigene Middleware für Unterhaltungsdienste erstellen. Diese besteht aus einer oder mehreren von Ihnen definierten Funktionen, die von der Clientbibliothek automatisch ausgeführt werden, bevor der Intent-Handler aufgerufen wird. Der Auftragsausführungs-Webhook kann dem Objekt Conversation über Ihre Middleware Attribute oder Hilfsklassen hinzufügen.
  6. Verarbeitung von Intent-Handlern: Mit der Clientbibliothek können Sie Handler für Intents definieren, die der Auftragsausführungs-Webhook versteht. Bei Dialogflow leitet die Clientbibliothek die Anfrage an den richtigen Intent-Handler weiter. Dazu ordnet sie die Anfrage dem genauen String des Intent-Namens zu, der in der Dialogflow-Konsole definiert ist. Beim Actions SDK erfolgt die Weiterleitung auf Grundlage der intent-Property, die von Actions on Google gesendet wurde.
  7. Antworten an Nutzer senden:Zum Erstellen von Antworten ruft der Auftragsausführungs-Webhook 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 Auftragsausführungs-Webhook implementieren, müssen Sie zuerst die Clientbibliothek installieren.

Clientbibliothek installieren

Am einfachsten lässt sich die Clientbibliothek in Ihrer lokalen Entwicklungsumgebung mit einem Paketmanager wie npm oder yarn installieren.

Führen Sie zur Installation einen der folgenden Befehle über das 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 (Cloud Functions for Firebase von Google, 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 einrichten. Führen Sie dazu die Schritte unter Node.js und Firebase CLI einrichten und Firebase für Cloud Functions initialisieren aus. Bei Cloud Functions for Firebase schreiben Sie den Auftragsausführungs-Webhook normalerweise in die Datei /functions/index.js.

Anwendungsinstanz erstellen

Actions on Google verwendet bestimmte Nachrichtenformate, um Anfragen und Antworten mit dem Auftragsausführungs-Webhook auszutauschen, je nachdem, ob Sie eine dialogorientierte Aktion mit Dialogflow oder dem Actions SDK oder einer Smart-Home-Aktion erstellen.

Zur Darstellung dieser verschiedenen Anfrage- und Antwortprotokolle bietet die Clientbibliothek drei Dienstfunktionen:

Das Unterhaltungs-Webhook-Protokoll wird von beiden Konversationsdiensten (Dialogflow und Actions SDK) verwendet, aber jeder Dienst verpackt Nachrichten unterschiedlich.

Sie verwenden einen Dienst, um eine app-Instanz zu erstellen. Die app-Instanz kapselt den globalen Status und die Auftragsausführungslogik für den Webhook und verwaltet die Kommunikation zwischen Actions on Google und der Auftragsausführung mithilfe des dienstspezifischen Protokolls.

Sie können die Attribute der Instanz app konfigurieren und ihre Methoden aufrufen, um das Verhalten des Webhooks für die Auftragsausführung festzulegen. Sie können die Instanz app auch einfach in eine serverlose Computing-Umgebung wie Cloud Functions for Firebase einstecken, die JavaScript-Funktionen als Handler für HTTP-Anfragen akzeptiert.

So erstellen Sie eine app-Instanz in Ihrem Auftragsausführungs-Webhook:

  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 zum Erstellen von Antworten laden und einer Konstante mit dem Namen dialogflow zuweisen:

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

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

    Beim Abrufen einer app-Instanz können Sie optional Klassen angeben, die Rich-Media-Antworten, Hilfs-Intents und andere Actions on Google-Funktionen darstellen, 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 Unterhaltungsantwort und Hilfs-Intent.

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

    const app = dialogflow();

  3. Zum Konfigurieren der Instanz app bei der Initialisierung können Sie ein options-Objekt als erstes Argument angeben, wenn Sie den Dienst aufrufen. Weitere Informationen finden Sie unter DialogflowOptions. Das folgende Snippet zeigt beispielsweise, wie die JSON-Rohutzlast der Nutzeranfrage oder -antwort durch Festlegen des Flags { debug: true } protokolliert wird:

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

Handler für Ereignisse festlegen

Um Actions on Google-Ereignisse zu verarbeiten, die von der Clientbibliothek während des Lebenszyklus der Nutzerinteraktion mit Ihrer Aktion erstellt wurden, verwenden Sie die Clientbibliothek, um Handler zu erstellen, mit denen Nutzeranfragen verarbeitet und Antworten zurückgesendet werden.

Sie können Funktionen erstellen, die als Handler für die folgenden Haupttypen von Ereignissen fungieren, die die Clientbibliothek erkennt:

  • Intent-Ereignisse:Intents sind eindeutige Kennungen, die von Actions on Google an die Auftragsausführung gesendet werden, wenn ein Nutzer eine bestimmte Funktion anfordert. Wenn Sie Dialogflow verwenden, entspricht dies, dass Dialogflow eine Nutzerabfrage mit einem Intent in Ihrem Dialogflow-Agent zuordnet.
  • Fehlerereignisse: Wenn ein JavaScript- oder Clientbibliotheksfehler auftritt, können Sie mit der catch-Funktion der app-Instanz die Fehlerausnahme entsprechend verarbeiten. Sie sollten eine einzige 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 Actions on Google nicht erkennen kann. Mit der Funktion fallback der app-Instanz können Sie einen generischen Fallback-Handler registrieren, der ausgelöst wird, wenn der eingehende Auftragsausführungsanfrage kein Intent-Handler zugeordnet wurde. Sie sollten eine einzige fallback-Funktion implementieren, die alle Fallback-Ereignisse verarbeitet. Wenn Sie Dialogflow verwenden, kann Dialogflow einen bestimmten Fallback-Intent auslösen, wenn kein anderer Intent zugeordnet ist. Sie sollten einen entsprechenden Intent-Handler für diesen Fallback-Intent erstellen.

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

Nutzerabfragen können auch Parameter enthalten, die deine Aktion extrahieren und zum Verfeinern von Antworten verwenden kann.

  • Wenn Sie das Actions SDK verwenden, definieren Sie die Parameter im Aktionspaket. Ein Beispiel dafür, wie Sie Parameter aus Intents extrahieren können, 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 Zugriffsparameter und Kontexte.

Handler für Intents festlegen

Rufen Sie die Funktion intent() der app-Instanz auf, um den Handler für einen Intent festzulegen. Wenn Sie beispielsweise Dialogflow verwenden, ist dies die Funktion DialogflowApp#intent(). Geben Sie in den Argumenten den Intent-Namen an und stellen Sie eine Handler-Funktion bereit.

Wenn Sie Dialogflow verwenden, müssen Sie nicht für jeden Intent in Ihrem Agent einen 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 auf diese Weise an Dialogflow delegiert werden.

Das folgende Beispiel zeigt Intent-Handler für die Intents „greeting“ (Begrüßung) und „bye“ (bye). Die anonymen Handler-Funktionen verwenden ein conv-Argument und senden über die Funktion conv.ask() eine einfache Stringantwort an den Nutzer zurück:

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 wird und die Unterhaltung beendet ist.

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() der app-Instanz auf, um die Handler für Fehler festzulegen. Wenn Sie beispielsweise Dialogflow verwenden, ist dies die Funktion DialogflowApp#catch().

Das folgende Beispiel zeigt einen einfachen Catch-Fehler-Handler, der den Fehler an die Konsolenausgabe sendet und eine einfache Stringantwort zurücksendet, 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 generischen Fallback-Handler festlegen möchten, wenn der eingehende Anfrage zur Auftragsausführung kein Intent zugeordnet wird, rufen Sie die Funktion fallback() der Instanz app auf. Wenn Sie beispielsweise Dialogflow verwenden, ist dies die Funktion DialogflowApp#fallback().

Das folgende Beispiel zeigt einen einfachen Fallback-Handler, der eine einfache Stringantwort zurücksendet, 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 behandelt, wenn Sie Intent-Handler mit der Clientbibliothek implementieren. Informationen dazu, wie die Clientbibliothek mit dem Intent übereinstimmt, finden Sie im Abschnitt „Intent-Handler-Verarbeitung“ unter Funktionsweise.

Zugriffsparameter und Kontexte

Wenn Sie Dialogflow verwenden, können Sie im Dialogflow-Agent Parameter und Kontexte definieren, um Statusinformationen zu verwalten und den Unterhaltungsablauf zu steuern.

Parameter sind nützlich, um wichtige Wörter, Wortgruppen oder Werte in Nutzerabfragen zu erfassen. Dialogflow extrahiert zur Laufzeit die entsprechenden Parameter aus Nutzerabfragen. Sie können diese Parameterwerte in Ihrem Auftragsausführungs-Webhook verarbeiten, um festzustellen, wie auf Nutzer geantwortet werden soll.

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

Das folgende Snippet zeigt, 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}?`);
});

Im Folgenden finden Sie ein alternatives Snippet, das dieselbe Funktion bietet. Die geschweiften Klammern ({}) führen in JavaScript eine Destrukturierung durch, um das Attribut name aus dem Objekt parameters 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 namens name zugewiesen:

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

Kontexte sind eine erweiterte Funktion von Dialogflow. Sie können Kontexte verwenden, um den Status, den Ablauf und die Verzweigung der Unterhaltung zu verwalten. Die Clientbibliothek bietet über das Objekt DialogflowConversation#contexts Zugriff auf einen Kontext. Das folgende Snippet zeigt, wie Sie in Ihrem Auftragsausführungs-Webhook programmatisch einen Kontext 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 Hilfs-Intent-Klassen, die gängige Arten von Nutzerdaten umfassen, die von Actions häufig angefordert werden. Dazu gehören Klassen, die die Ergebnisse für die verschiedenen Hilfs-Intents von Actions on Google darstellen. Sie verwenden Hilfs-Intents, wenn Google Assistant Teile der Unterhaltung verarbeiten soll, in denen der Nutzer Eingaben geben muss, um die Unterhaltung fortzusetzen.

Beispiel: Ergebnisse des Bestätigungsassistenten

Mit dem Bestätigungs-Hilfs-Intent können Sie eine Ja/Nein-Bestätigung vom Nutzer anfordern und die resultierende Antwort erhalten. Das folgende Snippet zeigt, wie der Webhook seine Antwort basierend auf den vom Bestätigungs-Hilfs-Intent zurückgegebenen Ergebnissen anpassen kann. Ein ausführlicheres Beispiel finden Sie in der Referenzdokumentation zur Klasse 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 Auftragsausführungs-Webhook seine Antwort basierend auf der Nutzereingabe für ein Karussell anpassen kann. Mit der Karussellkomponente kann deine Aktion Nutzern eine Auswahl von Optionen präsentieren. Ein ausführlicheres Beispiel finden Sie in der Referenzdokumentation zur Klasse 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!`);
  }
});

Unterhaltungsantwortobjekte konfigurieren

Die Clientbibliothek bietet Unterhaltungsantwortklassen, die Rich-Antworten oder Multimedia-Elemente darstellen, die deine Aktion senden kann. Sie senden diese Antworten oder Elemente in der Regel, wenn Nutzer keine Eingabe eingeben müssen, um die Unterhaltung fortzusetzen.

Beispiel: Bild

Das folgende Snippet zeigt, wie Ihr Auftragsausführungs-Webhook eine Image in einer Antwort senden kann, die von der Bibliothek automatisch 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 durchführen

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

Das folgende Snippet zeigt, wie Sie mit einem asynchronen Funktionsaufruf ein Promise-Objekt zurückgeben und dann mit einer Nachricht antworten können, wenn der Auftragsausführungs-Webhook den Begrüßungs-Intent empfängt. In diesem Snippet sorgt das Promise dafür, dass der Auftragsausführungs-Webhook erst dann eine Konversationsantwort zurückgibt, wenn das Promise für den externen API-Aufruf aufgelöst wurde.

In diesem Beispiel verwenden wir eine fiktive 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 denselben Effekt, verwendet jedoch die in ECMA 2017 (Node.js Version 8) eingeführte Funktion async await. 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 haben.

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

Konversationsdaten speichern

Mithilfe der Clientbibliothek kann der Auftragsausführungs-Webhook Daten in Unterhaltungen für die zukünftige Verwendung speichern. Die wichtigsten Objekte, die Sie für die Datenspeicherung verwenden können, sind:

Das folgende Snippet zeigt, wie der Auftragsausführungs-Webhook Daten in einem beliebigen von Ihnen definierten Attribut (someProperty) speichern und an das Objekt Conversation#user.storage anhängen kann. Ein ausführlicheres Beispiel finden Sie in der Referenzdokumentation zur Klasse 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 von der Clientbibliothek automatisch ausgeführt werden, bevor der Intent-Handler aufgerufen wird. Wenn Sie eine Middleware-Ebene verwenden, können Sie die Conversation-Instanz ändern und zusätzliche Funktionen hinzufügen.

Die Dialogflow- und Actions SDK-Dienste bieten eine app.middleware()-Funktion, mit der Sie der Conversation-Instanz Attribute oder Hilfsklassen 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

Wenn Sie den Auftragsausführungs-Webhook für ein Web-Framework oder eine serverlose Computing-Plattform verfügbar machen möchten, müssen Sie das app-Objekt als öffentlich zugänglichen Webhook exportieren. Die Clientbibliothek unterstützt standardmäßig die Bereitstellung in einer Reihe von Umgebungen.

Die folgenden Snippets zeigen, wie Sie app innerhalb verschiedener 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;