Für noch mehr Flexibilität beim Erstellen von Aktionen können Sie Logik an HTTPS-Webdienste (Auftragsausführung) delegieren. Deine Aktionen können Webhooks auslösen, die Anfragen an einen HTTPS-Endpunkt senden. Beispiele dafür, was Sie bei der Auftragsausführung tun können:
- Generieren einer dynamischen Aufforderung basierend auf den vom Nutzer bereitgestellten Informationen.
- Die Bestellung in einem externen System aufgeben und den Erfolg bestätigen
- Slots mit Back-End-Daten validieren.
Webhook-Trigger und -Handler
Ihre Aktionen können einen Webhook innerhalb von Aufruf-Intents oder Szenen auslösen. Dadurch wird eine Anfrage an den Auftragsausführungsendpunkt gesendet. Die Auftragsausführung enthält Webhook-Handler, die die JSON-Nutzlast in der Anfrage verarbeiten. Sie können Webhooks in den folgenden Situationen auslösen:
- Nach einem Aufruf-Intent-Abgleich
- Während einer Szene auf der Bühne
- Nachdem eine Bedingung in der Bedingungsphase einer Szene als wahr ausgewertet wird
- Während der Slot-Füllung einer Szene
- Nach einer Intent-Zuordnung in der Eingabephase einer Szene
Wenn Sie in Ihren Aktionen einen Webhook auslösen, sendet Google Assistant eine Anfrage mit einer JSON-Nutzlast an die Auftragsausführung, die den Namen des Handlers enthält, mit dem das Ereignis verarbeitet werden soll. Der Auftragsausführungsendpunkt kann das Ereignis an den entsprechenden Handler weiterleiten, um die Logik auszuführen und eine entsprechende Antwort mit einer JSON-Nutzlast zurückzugeben.
Nutzlasten
Die folgenden Snippets zeigen Beispielanfragen, die Ihre Aktionen an die Auftragsausführung senden, und eine Antwort, die von der Auftragsausführung zurückgeschickt wird. Weitere Informationen finden Sie in der Referenzdokumentation.
Beispielanfrage
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "actions.intent.MAIN",
"params": {},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "UNSPECIFIED",
"slots": {}
},
"session": {
"id": "example_session_id",
"params": {},
"typeOverrides": []
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED"
}
},
"home": {
"params": {}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO"
]
}
}
Beispielantwort
{
"session": {
"id": "example_session_id",
"params": {}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "Hello World.",
"text": ""
}
},
"scene": {
"name": "SceneName",
"slots": {},
"next": {
"name": "actions.scene.END_CONVERSATION"
}
}
}
Laufzeitinteraktionen
In den folgenden Abschnitten werden allgemeine Aufgaben beschrieben, die Sie in Ihren Webhook-Handlern ausführen können.
Aufforderungen senden
Mit Interactive Canvas können Sie Aufforderungen mit einfachem Text, Rich-Text, Karten und sogar vollständigen HTML-Prompts erstellen, die von einer Webanwendung unterstützt werden. Die prompts-Dokumentation enthält umfassende Informationen zum Erstellen einer Eingabeaufforderung bei der Verarbeitung eines Webhook-Ereignisses. Die folgenden Snippets zeigen eine Kartenaufforderung:
Node.js
app.handle('rich_response', conv => {
conv.add('This is a card rich response.');
conv.add(new Card({
title: 'Card Title',
subtitle: 'Card Subtitle',
text: 'Card Content',
image: new Image({
url: 'https://developers.google.com/assistant/assistant_96.png',
alt: 'Google Assistant logo'
})
}));
});
Antwort (JSON)
{
"session": {
"id": "example_session_id",
"params": {}
},
"prompt": {
"override": false,
"content": {
"card": {
"title": "Card Title",
"subtitle": "Card Subtitle",
"text": "Card Content",
"image": {
"alt": "Google Assistant logo",
"height": 0,
"url": "https://developers.google.com/assistant/assistant_96.png",
"width": 0
}
}
},
"firstSimple": {
"speech": "This is a card rich response.",
"text": ""
}
}
}
Intent-Parameter lesen
Wenn die Assistant-Laufzeit einem Intent zugeordnet wird, werden alle definierten Parameter extrahiert. Das ursprüngliche Attribut war das, was der Nutzer als Eingabe angegeben hat, und die NLU hat die Eingabe basierend auf der Typspezifikation in das aufgelöste Attribut aufgelöst.
Node.js
conv.intent.params['param_name'].original
conv.intent.params['param_name'].resolved
Anfrage (JSON)
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "intent_name",
"params": {
"slot_name": {
"original": "1",
"resolved": 1
}
},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "UNSPECIFIED",
"slots": {},
"next": {
"name": "actions.scene.END_CONVERSATION"
}
},
"session": {
"id": "session_id",
"params": {},
"typeOverrides": []
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED"
}
},
"home": {
"params": {}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO"
]
}
}
Nutzersprache lesen
Dieser Wert entspricht der Spracheinstellung des Nutzers für Google Assistant.
Node.js
conv.user.locale
JSON
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "actions.intent.MAIN",
"params": {},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "UNSPECIFIED",
"slots": {}
},
"session": {
"id": "session_id",
"params": {},
"typeOverrides": []
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED"
}
},
"home": {
"params": {}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO"
]
}
}
Speicher lesen und schreiben
Umfassende Informationen zur Verwendung verschiedener Speicherfunktionen finden Sie in der Speicherdokumentation.
Node.js
//read
conv.session.params.key
conv.user.params.key
conv.home.params.key
// write
conv.session.params.key = value
conv.user.params.key = value
conv.home.params.key = value
Anfrage (JSON)
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "actions.intent.MAIN",
"params": {},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "UNSPECIFIED",
"slots": {}
},
"session": {
"id": "session_id",
"params": {
"key": "value"
},
"typeOverrides": [],
"languageCode": ""
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED",
"key": "value"
}
},
"home": {
"params": {
"key": "value"
}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO"
]
}
}
Antwort (JSON)
{
"session": {
"id": "session_id",
"params": {
"key": "value"
}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "Hello world.",
"text": ""
}
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED",
"key": "value"
}
},
"home": {
"params": {
"key": "value"
}
}
}
Gerätefunktionen prüfen
Sie können die Funktionen eines Geräts prüfen, um unterschiedliche Funktionen oder Unterhaltungsabläufe bereitzustellen.
Node.js
const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE");
const supportsLongFormAudio = conv.device.capabilities.includes("LONG_FORM_AUDIO");
const supportsSpeech = conv.device.capabilities.includes("SPEECH");
const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS");
Anfrage (JSON)
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "actions.intent.MAIN",
"params": {},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "UNSPECIFIED",
"slots": {}
},
"session": {
"id": "session_id",
"params": {},
"typeOverrides": [],
"languageCode": ""
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED"
}
},
"home": {
"params": {}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO",
"INTERACTIVE_CANVAS"
]
}
}
Eine vollständige Liste der Oberflächenfunktionen finden Sie in der Referenz zu Capability.
Laufzeittypüberschreibungen
Mit Laufzeittypen können Sie Typspezifikationen zur Laufzeit ändern. Sie können diese Funktion verwenden, um Daten aus anderen Quellen zu laden, um die gültigen Werte eines Typs zu füllen. Sie können beispielsweise Laufzeittypüberschreibungen verwenden, um einer Umfragefrage dynamische Optionen oder einem Menü einen täglichen Eintrag hinzuzufügen.
Zur Verwendung von Laufzeittypen lösen Sie einen Webhook von Ihrer Aktion aus, der einen Handler in der Auftragsausführung aufruft. Von dort aus kannst du den Parameter session.typeOverrides als Antwort auf deine Aktion füllen. Verfügbare Modi sind TYPE_MERGE, um vorhandene Typeinträge beizubehalten, oder TYPE_REPLACE, um vorhandene Einträge durch die Überschreibungen zu ersetzen.
Node.js
conv.session.typeOverrides = [{
name: type_name,
mode: 'TYPE_REPLACE',
synonym: {
entries: [
{
name: 'ITEM_1',
synonyms: ['Item 1', 'First item']
},
{
name: 'ITEM_2',
synonyms: ['Item 2', 'Second item']
},
{
name: 'ITEM_3',
synonyms: ['Item 3', 'Third item']
},
{
name: 'ITEM_4',
synonyms: ['Item 4', 'Fourth item']
},
]
}
}];
Antwort (JSON)
{
"session": {
"id": "session_id",
"params": {},
"typeOverrides": [
{
"name": "type_name",
"synonym": {
"entries": [
{
"name": "ITEM_1",
"synonyms": [
"Item 1",
"First item"
]
},
{
"name": "ITEM_2",
"synonyms": [
"Item 2",
"Second item"
]
},
{
"name": "ITEM_3",
"synonyms": [
"Item 3",
"Third item"
]
},
{
"name": "ITEM_4",
"synonyms": [
"Item 4",
"Fourth item"
]
}
]
},
"typeOverrideMode": "TYPE_REPLACE"
}
]
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "This is an example prompt.",
"text": "This is an example prompt."
}
}
}
Sprachgewichtung bereitstellen
Mit der Sprachgewichtung können Sie Hinweise für die NLU angeben, um die Intent-Zuordnung zu verbessern. Sie können bis zu 1.000 Einträge angeben.
Node.js
conv.expected.speech = ['value_1', 'value_2']
conv.expected.language = 'locale_string'
Antwort (JSON)
{
"session": {
"id": "session_id",
"params": {}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "This is an example prompt.",
"text": "This is an example prompt."
}
},
"expected": {
"speech": "['value_1', 'value_2']",
"language": "locale_string"
}
}
Übergangsszenen
Sie können nicht nur statische Übergänge in Ihrem Actions-Projekt definieren, sondern auch Szenenübergänge zur Laufzeit veranlassen.
Node.js
app.handle('transition_to_hidden_scene', conv => {
// Dynamic transition
conv.scene.next.name = "HiddenScene";
});
Antwort (JSON)
{
"session": {
"id": "session_id",
"params": {}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "This is an example prompt.",
"text": ""
}
},
"scene": {
"name": "SceneName",
"slots": {},
"next": {
"name": "HiddenScene"
}
}
}
Szenenslots lesen
Während der Slot-Füllung können Sie die Auftragsausführung verwenden, um den Slot zu validieren oder den Status der Slot-Füllung zu prüfen (SlotFillingStatus).
Node.js
conv.scene.slotFillingStatus // FINAL means all slots are filled
conv.scene.slots // Object that contains all the slots
conv.scene.slots['slot_name'].<property_name> // Accessing a specific slot's properties
Angenommen, Sie möchten die Zeitzone aus einer Antwort extrahieren. In diesem Beispiel lautet der Slotname datetime1. So rufen Sie die Zeitzone ab:
conv.scene.slots['datetime1'].value.time_zone.id
Anfrage (JSON)
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "",
"params": {
"slot_name": {
"original": "1",
"resolved": 1
}
},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "FINAL",
"slots": {
"slot_name": {
"mode": "REQUIRED",
"status": "SLOT_UNSPECIFIED",
"updated": true,
"value": 1
}
},
"next": {
"name": "actions.scene.END_CONVERSATION"
}
},
"session": {
"id": "session_id",
"params": {
"slot_name": 1
},
"typeOverrides": []
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED"
}
},
"home": {
"params": {}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO"
]
}
}
Szenenslots ungültig machen
Sie können Slots entwerten und den Nutzer dazu bringen, einen neuen Wert anzugeben.
Node.js
conv.scene.slots['slot_name'].status = 'INVALID'
Antwort (JSON)
{
"session": {
"id": "session_id",
"params": {
"slot_name": 1
}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "This is an example prompt.",
"text": ""
}
},
"scene": {
"name": "SceneName",
"slots": {
"slot_name": {
"mode": "REQUIRED",
"status": "INVALID",
"updated": true,
"value": 1
}
},
"next": {
"name": "actions.scene.END_CONVERSATION"
}
}
}
Entwicklungsoptionen
Actions Builder bietet einen Inline-Editor namens Cloud Functions-Editor, mit dem Sie eine Cloud Functions-Funktion für Firebase direkt in der Console erstellen und bereitstellen können. Sie können die Auftragsausführung auch für Ihr gewünschtes Hosting erstellen und bereitstellen und Ihren HTTPS-Auftragsausführungsendpunkt als Webhook-Handler registrieren.
Inline-Editor
So entwickeln Sie mit dem Cloud Functions-Editor:
- Öffnen Sie Ihr Actions-Projekt und rufen Sie den Tab Develop > Webhook > Change Auftragsausführungsmethode ändern auf. Das Fenster Fulfillment method (Auftragsausführungsmethoden) wird angezeigt.
- Wählen Sie Inline Cloud Functions aus und klicken Sie auf Confirm (Bestätigen).
Externer HTTPS-Endpunkt
In diesem Abschnitt wird beschrieben, wie Sie Cloud Functions for Firebase als Auftragsausführungsdienst für Ihre Konversationsaktion einrichten. Sie können die Auftragsausführung jedoch auch bei einem Hostingdienst Ihrer Wahl bereitstellen.
Umgebung einrichten
So richten Sie Ihre Umgebung ein:
- Laden Sie Node.js herunter und installieren Sie die App.
Firebase CLI einrichten und initialisieren Wenn der folgende Befehl mit dem Fehler
EACCESfehlschlägt, müssen Sie möglicherweise npm-Berechtigungen ändern.npm install -g firebase-toolsAuthentifizieren Sie das Firebase-Tool mit Ihrem Google-Konto:
firebase loginStarten Sie das Projektverzeichnis, in dem Sie Ihr Actions-Projekt gespeichert haben. Sie werden aufgefordert, die Firebase CLI-Features auszuwählen, die Sie für Ihr Actions-Projekt einrichten möchten. Wählen Sie
Functionsund andere Features aus, die Sie verwenden möchten, z. B. Firestore. Drücken Sie dann die Eingabetaste, um den Vorgang zu bestätigen und fortzufahren:$ cd <ACTIONS_PROJECT_DIRECTORY> $ firebase initVerknüpfen Sie das Firebase-Tool mit Ihrem Actions-Projekt, indem Sie es mithilfe der Pfeiltasten in der Projektliste auswählen:
Nachdem Sie das Projekt ausgewählt haben, startet das Firebase-Tool die Functions-Einrichtung und fragt Sie, welche Sprache Sie verwenden möchten. Verwenden Sie die Pfeiltasten, um eine Auswahl zu treffen, und drücken Sie die Eingabetaste, um fortzufahren.
=== Functions Setup A functions directory will be created in your project with a Node.js package pre-configured. Functions can be deployed with firebase deploy. ? What language would you like to use to write Cloud Functions? (Use arrow keys) > JavaScript TypeScript
Wählen Sie aus, ob Sie ESLint verwenden möchten, um wahrscheinliche Fehler zu erkennen und den Stil zu erzwingen. Geben Sie dazu Y oder N ein:
? Do you want to use ESLint to catch probable bugs and enforce style? (Y/n)
Rufen Sie die Projektabhängigkeiten ab, indem Sie Y in die Eingabeaufforderung eingeben:
? Do you want to install dependencies with npm now? (Y/n)
Sobald die Einrichtung abgeschlossen ist, sollte die Ausgabe in etwa so aussehen:
✔ Firebase initialization complete!Installieren Sie die Abhängigkeit @assistant/conversation:
$ cd <ACTIONS_PROJECT_DIRECTORY>/functions $ npm install @assistant/conversation --saveRufen Sie die Auftragsausführungsabhängigkeiten ab und stellen Sie die Auftragsausführungsfunktion bereit:
$ npm install $ firebase deploy --only functionsDie Bereitstellung dauert einige Minuten. Anschließend sollte die Ausgabe in etwa so aussehen. Sie benötigen die Funktions-URL, die Sie in Dialogflow eingeben müssen.
✔ Deploy complete!
Project Console: https://console.firebase.google.com/project/<PROJECT_ID>/overview Function URL (<FUNCTION_NAME>): https://us-central1-<PROJECT_ID>.cloudfunctions.net/<FUNCTION_NAME>Kopieren Sie die Ausführungs-URL, um sie im nächsten Abschnitt zu verwenden.
Webhook-Handler registrieren
So registrieren Sie den Cloud Functions-Endpunkt als Webhook-Handler:
- Klicken Sie in der Actions Console auf Develop > Webhook.
- Klicken Sie auf Auftragsausführungsmethode ändern. Das Fenster Auftragsausführungsmethoden wird angezeigt.
- Wählen Sie Webhook aus und klicken Sie auf Bestätigen.
- Fügen Sie die Webdienst-URL in das Feld Webhook ein.
- Klicken Sie auf Speichern.