Am 13. Juni 2023 wurden Konversationsaktionen eingestellt. Weitere Informationen finden Sie unter Einstellung von Konversationsaktionen.

Diese Seite wurde von der Cloud Translation API übersetzt.

Webhooks

Damit Sie Aktionen noch flexibler erstellen können, können Sie zu HTTPS-Webdiensten (Auftragsausführung). Ihre Aktionen können Webhooks auslösen, Anfragen an einen HTTPS-Endpunkt senden. Einige Beispiele dafür, was Sie in Die Auftragsausführung umfassen Folgendes:

Dynamische Aufforderung generieren, die auf vom Nutzer bereitgestellten Informationen basiert.
Eine Bestellung in einem externen System aufgeben und den Erfolg bestätigen
Slots mit Back-End-Daten werden validiert.

**Abbildung 1.** Aufruf-Intents und Szenen können Webhooks.

Webhook-Trigger und -Handler

Ihre Aktionen können einen Webhook in Aufruf-Intents oder Szenen auslösen, die sendet eine Anfrage an den Endpunkt für die Auftragsausführung. Die Auftragsausführung enthält einen Webhook. Handler, die die JSON-Nutzlast in der Anfrage verarbeiten. Sie können Webhooks auslösen in den folgenden Situationen:

Nach Abgleich eines Aufruf-Intents
Während einer Szene im Eingangsbereich
Nachdem eine Bedingung in der Bedingungsphase einer Szene als wahr ausgewertet wurde
Während der Slot-Füllungsphase einer Szene
Nachdem eine Intent-Übereinstimmung in der Eingabephase einer Szene stattgefunden hat

Wenn Sie in Ihren Aktionen einen Webhook auslösen, sendet Google Assistant eine Anfrage mit einer JSON-Nutzlast zu Ihrer Auftragsausführung hinzu, die die Name des Handlers, der zum Verarbeiten des Ereignisses verwendet werden soll. Der Auftragsausführungsendpunkt kann das Ereignis an den entsprechenden Handler weiterleiten, um die Logik auszuführen und einen entsprechende Antwort mit einer JSON-Nutzlast.

Nutzlasten

Die folgenden Snippets zeigen Beispielanfragen, an die deine Aktionen gesendet werden Fulfillment und eine Antwort, die von der Auftragsausführung zurückgesendet wird. Weitere Informationen finden Sie in der Referenzdokumentation finden Sie weitere Informationen Informationen.

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 häufige Aufgaben beschrieben, die Sie in Ihrem Webhook-Handler.

Aufforderungen senden

Du kannst Prompts mit einfachem Text, Rich-Text, Karten und sogar HTML-Prompts, die von einer Web-App unterstützt werden, mit Interactive Canvas Die prompts-Dokumentation enthält vollständige Informationen zum Erstellen eines Prompts 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 mit einem Intent übereinstimmt, extrahiert sie alle definierten Parameter. Die ursprüngliche Eigenschaft entsprach der Eingabe durch den Nutzer und der „Resolved“-Attribut ist das, in das die NLU die Eingabe auf Grundlage des Typs Spezifikation zu ändern.

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

In der Dokumentation zu Speicher finden Sie umfassende Informationen dazu, wie Sie verschiedene Speicherfunktionen nutzen.

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 Gesprächsabläufe.

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 Funktionen findest du in der Capability Referenz.

Laufzeittypüberschreibungen

Mit Laufzeittypen können Sie Typspezifikationen zur Laufzeit ändern. Sie können diese -Funktion zum Laden von Daten aus anderen Quellen, um die gültigen Werte eines Typs zu füllen. Für Sie können z. B. Laufzeittypüberschreibungen verwenden, um einer Umfrage dynamische Optionen hinzuzufügen. oder um einem Menü einen täglichen Artikel hinzuzufügen.

Zur Verwendung von Laufzeittypen lösen Sie über Ihre Aktion einen Webhook aus, der eine -Handler in der Auftragsausführung. Anschließend können Sie die session.typeOverrides als Antwort auf Ihre Aktion zurückgegeben. Verfügbar Modi umfassen 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

Mithilfe der Sprachgewichtung können Sie Hinweise für die NLU angeben, um die Zuordnung von Intents zu verbessern. Ich 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

Neben der Definition statischer Übergänge in Ihrem Actions-Projekt können Sie führen zur Laufzeit Szenenübergänge.

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 mithilfe der Auftragsausführung den Slot validieren oder die Status der Slot-Füllung (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 In diesem Beispiel lautet der Name der Anzeigenfläche datetime1. Um die Zeitzone zu ermitteln, verwenden:

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 entwerten

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

</ph>

Actions Builder bietet einen Inline-Editor namens Cloud Functions-Editor. mit dem Sie eine Cloud Functions-Funktion für Firebase direkt in der . Sie können die Auftragsausführung auch im Hosting Ihrer Wahl erstellen und bereitstellen und registrieren Sie den HTTPS-Auftragsausführungsendpunkt als Webhook-Handler.

Inline-Editor

So entwickeln Sie mit dem Cloud Functions-Editor:

Erstellen Sie die Datei sdk/webhooks/ActionsOnGoogleFulfillment.yaml, und definiere die Handler für deine Aktion sowie die verwendete Inline-Cloud Functions-Funktion. für die Auftragsausführung.
```
handlers:
- name: questionOnEnterFunc
- name: fruitSlotValidationFunc
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment
    
```

Erstellen Sie den Ordner sdk/webhooks/ActionsOnGoogleFulfillment. und fügen Sie eine index.js-Datei hinzu, in der die Handler implementiert sind. und einer package.json-Datei, die npm definiert, Anforderungen für Ihren Code.

// index.js
const {conversation} = require('@assistant/conversation');
const functions = require('firebase-functions');

const app = conversation();

app.handle('questionOnEnterFunc', conv => {
  conv.add('questionOnEnterFunc triggered on webhook');
});

app.handle('fruitSlotValidationFunc', conv => {
  conv.add('fruitSlotValidationFunc triggered on webhook');
});

exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

// package.json
{
  "name": "ActionsOnGoogleFulfillment",
  "version": "0.1.0",
  "description": "Actions on Google fulfillment",
  "main": "index.js",
  "dependencies": {
    "@assistant/conversation": "^3.0.0",
    "firebase-admin": "^5.4.3",
    "firebase-functions": "^0.7.1"
  }
}

Externer HTTPS-Endpunkt

In diesem Abschnitt wird beschrieben, wie Sie Cloud Functions for Firebase als Ausführungsdienst für Ihre Konversationsaktion. Sie können jedoch Auftragsausführung an einen Hostingdienst deiner Wahl.

Umgebung einrichten

Wir empfehlen die folgende Projektstruktur, wenn Sie Cloud Functions für Firebase als Fulfillment-Dienst:

ProjectFolder        - Root folder for the project
  sdk                - Actions project configuration files
  functions          - Cloud functions for Firebase files

So richten Sie Ihre Umgebung ein:

Laden Sie Node.js herunter und installieren Sie es.
Richten Sie die Firebase CLI ein und initialisieren Sie sie. Wenn der folgende Befehl fehlschlägt, einen EACCES-Fehler anzeigt, müssen Sie möglicherweise die npm-Berechtigungen ändern.
```
npm install -g firebase-tools
```
Authentifizieren Sie das Firebase-Tool mit Ihrem Google-Konto:
```
firebase login
```
Starten Sie das Projektverzeichnis, in dem Sie Ihr Actions-Projekt gespeichert haben. Sie werden aufgefordert, die Firebase CLI-Funktionen auszuwählen, für die Sie die Einrichtung vornehmen möchten Ihr Actions-Projekt. Wähle Functions und andere Funktionen aus, die dich interessieren könnten wie Firestore verwenden. Drücken Sie dann die Eingabetaste, um den Vorgang zu bestätigen und fortzufahren:
```
$ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init
```
Verknüpfen Sie das Firebase-Tool mit Ihrem Actions-Projekt, indem Sie es über mit den Pfeiltasten durch die Projektliste:

Hinweis: Sie können diesen Schritt überspringen, indem Sie [Richten Sie kein Standardprojekt ein], aber dann müssen Sie dies tun. Verknüpfung mit dem Befehl firebase use PROJECT_ID an.

Nachdem Sie das Projekt ausgewählt haben, startet das Firebase-Tool die Funktion und fragt Sie, welche Sprache Sie verwenden möchten. Mit den Pfeiltasten auswählen 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 mögliche Fehler zu erkennen und den Stil durch Eingabe von Y oder N zu erzwingen:
```
? 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, sehen Sie in etwa folgende Ausgabe:
```
✔  Firebase initialization complete!
```

Installieren Sie die Abhängigkeit @assistant/conversation:

$ cd <ACTIONS_PROJECT_DIRECTORY>/functions
$ npm install @assistant/conversation --save

Rufen Sie die Abhängigkeiten der Auftragsausführung ab und stellen Sie die Auftragsausführungsfunktion bereit:
```
$ npm install
$ firebase deploy --only functions
```
Die Bereitstellung dauert einige Minuten. Wenn Sie fertig sind, sehen Sie eine Ausgabe, die in etwa in das Folgende ein. Sie benötigen die Function URL (Funktions-URL), die Sie in Dialogflow eingeben.
```
✔  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 URL für die Auftragsausführung, die im nächsten Abschnitt verwendet werden soll.

Webhook-Handler registrieren

Erstellen Sie die Datei sdk/webhooks/ActionsOnGoogleFulfillment.yaml und definieren Sie die Handler für deine Aktion und die URL für Webhook-Anfragen.

httpsEndpoint:
  baseUrl: https://my.web.hook/ActionsOnGoogleFulfillment
  endpointApiVersion: 2
handlers:
- name: questionOnEnterFunc
- name: fruitSlotValidationFunc