Wenn Sie die Auftragsausführung in einem Produktionssystem verwenden möchten, müssen Sie einen Webhook-Dienst implementieren und bereitstellen. Zur Ausführung der Auftragsausführung muss Ihr Webhook-Dienst JSON-Anfragen akzeptieren und JSON-Antworten zurückgeben, wie in diesem Leitfaden beschrieben. Der detaillierte Verarbeitungsablauf für die Auftragsausführung und für Webhooks wird im Dokument Übersicht über die Auftragsausführung beschrieben.
Webhook-Dienstanforderungen
Ihr Webhook-Dienst muss die folgenden Anforderungen erfüllen:
- HTTPS-Anfragen verarbeiten. HTTP wird nicht unterstützt. Wenn Sie Ihren Webhook Dienst auf Google Cloud der Google Cloud Platform mit einer Compute- oder serverlosen Computing-Lösung hosten, lesen Sie die Produkt dokumentation zum Bereitstellen mit HTTPS. Informationen zu anderen Hostingoptionen finden Sie unter SSL-Zertifikat für eine Domain anfordern.
- Die Webhook-Dienst-URL muss öffentlich zugänglich sein.
- POST-Anfragen mit einem JSON
WebhookRequestText verarbeiten. - Auf
WebhookRequest-Anfragen mit einem JSONWebhookResponse-Text antworten.
Authentifizierung
| X | Element |
|---|---|
| Nutzername und Passwort für die Anmeldung | In den Webhook-Einstellungen können Sie optional einen Nutzernamen und ein Passwort für die Anmeldung angeben. Wenn Sie diese angeben, fügt Dialogflow den Webhook-Anfragen einen HTTP-Autorisierungsheader hinzu. Dieser Header hat das folgende Format: "authorization: Basic <base 64 encoding of the string username:password>". |
| Authentifizierungsheader | In den Webhook-Einstellungen können Sie optionale HTTP-Header-Schlüssel-Wert-Paare angeben. Wenn Sie diese angeben, fügt Dialogflow diese HTTP-Header den Webhook-Anfragen hinzu. Es ist üblich, ein einzelnes Paar mit dem Schlüssel authorization anzugeben. |
| Integrierte Authentifizierung für Cloud Run Functions | Sie können die integrierte Authentifizierung verwenden, wenn Sie Cloud Run Functions verwenden. Wenn Sie diese Art der Authentifizierung verwenden möchten, geben Sie keinen Nutzernamen, kein Passwort und keine Autorisierungsheader an. Wenn Sie eines dieser Felder angeben, werden sie nicht für die integrierte Authentifizierung verwendet. |
| Identitätstokens für Dienste | Sie können Identitätstokens für Dienste zur Authentifizierung verwenden. Wenn Sie keinen Nutzernamen, kein Passwort oder keinen Header mit dem Schlüssel authorization angeben, geht Dialogflow automatisch davon aus, dass Identitätstokens für Dienste verwendet werden sollen, und fügt den Webhook-Anfragen einen HTTP-Autorisierungsheader hinzu. Dieser Header hat das folgende Format: "authorization: Bearer <identity token>". |
| Gegenseitige TLS-Authentifizierung | Weitere Informationen finden Sie in der Dokumentation zur gegenseitigen TLS-Authentifizierung. |
Webhook-Anfrage
Wenn ein für die Auftragsausführung konfigurierter Intent zugeordnet wird, sendet Dialogflow eine HTTPS-POST-Webhook-Anforderung an Ihren Webhook-Dienst. Der Text dieser Anfrage ist ein JSON-Objekt mit Informationen zum übereinstimmenden Intent.
Neben der Endnutzerabfrage senden viele Integrationen auch Informationen über den Endnutzer. Dies kann beispielsweise eine ID sein, mit der der Nutzer eindeutig identifiziert werden kann. Auf diese Informationen kann in der Webhook-Anfrage über das Feld originalDetectIntentRequest zugegriffen werden. Dieses Feld enthält die von der Integrationsplattform gesendeten Informationen.
Weitere Informationen finden Sie in der
WebhookRequest
Referenzdokumentation.
Das folgende Beispiel zeigt eine -Anfrage:
{
"responseId": "response-id",
"session": "projects/project-id/agent/sessions/session-id",
"queryResult": {
"queryText": "End-user expression",
"parameters": {
"param-name": "param-value"
},
"allRequiredParamsPresent": true,
"fulfillmentText": "Response configured for matched intent",
"fulfillmentMessages": [
{
"text": {
"text": [
"Response configured for matched intent"
]
}
}
],
"outputContexts": [
{
"name": "projects/project-id/agent/sessions/session-id/contexts/context-name",
"lifespanCount": 5,
"parameters": {
"param-name": "param-value"
}
}
],
"intent": {
"name": "projects/project-id/agent/intents/intent-id",
"displayName": "matched-intent-name"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en"
},
"originalDetectIntentRequest": {}
}
Webhook-Antwort
Nachdem Ihr Webhook eine Anfrage erhalten hat, muss er eine Antwort senden. Der Text dieser Antwort ist ein JSON-Objekt mit den folgenden Informationen:
- Die Antwort, die Dialogflow an den Endnutzer zurückgibt.
- Updates zu den Kontexten, die für die Unterhaltung aktiv sind.
- Ein Folgeereignis zum Auslösen eines Intent Abgleichs.
- Eine benutzerdefinierte Nutzlast, die an die Einbindung oder den Client zur Intenterkennung gesendet wird.
Für die Antwort gelten die folgenden Einschränkungen:
- Antworten Sie bei Google Assistant Anwendungen innerhalb von 10 Sekunden und bei anderen Anwendungen innerhalb von 5 Sekunden. Andernfalls tritt bei der Anfrage eine Zeitüberschreitung ein.
- Die Antwort darf maximal 64 KiB groß sein.
Weitere Informationen finden Sie in der
WebhookResponse
Referenzdokumentation.
Textantwort
Hier sehen Sie ein Beispiel für eine Textantwort:
{
"fulfillmentMessages": [
{
"text": {
"text": [
"Text response from webhook"
]
}
}
]
}
Kartenantwort
Hier sehen Sie ein Beispiel für eine Kartenantwort:
{
"fulfillmentMessages": [
{
"card": {
"title": "card title",
"subtitle": "card text",
"imageUri": "https://example.com/images/example.png",
"buttons": [
{
"text": "button text",
"postback": "https://example.com/path/for/end-user/to/follow"
}
]
}
}
]
}
Google Assistant-Antwort
Hier sehen Sie ein Beispiel für eine Google Assistant-Antwort:
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "this is a Google Assistant response"
}
}
]
}
}
}
}
Kontext
Hier sehen Sie ein Beispiel, das den Ausgabekontext festlegt:
{
"fulfillmentMessages": [
{
"text": {
"text": [
"Text response from webhook"
]
}
}
],
"outputContexts": [
{
"name": "projects/project-id/agent/sessions/session-id/contexts/context-name",
"lifespanCount": 5,
"parameters": {
"param-name": "param-value"
}
}
]
}
Ereignis
Hier sehen Sie ein Beispiel, das ein benutzerdefiniertes Ereignis aufruft:
{
"followupEventInput": {
"name": "event-name",
"languageCode": "en-US",
"parameters": {
"param-name": "param-value"
}
}
}
Sitzungsentität
Hier sehen Sie ein Beispiel, das eine Sitzungsentität festlegt:
{
"fulfillmentMessages": [
{
"text": {
"text": [
"Choose apple or orange"
]
}
}
],
"sessionEntityTypes":[
{
"name":"projects/project-id/agent/sessions/session-id/entityTypes/fruit",
"entities":[
{
"value":"APPLE_KEY",
"synonyms":[
"apple",
"green apple",
"crabapple"
]
},
{
"value":"ORANGE_KEY",
"synonyms":[
"orange"
]
}
],
"entityOverrideMode":"ENTITY_OVERRIDE_MODE_OVERRIDE"
}
]
}
Benutzerdefinierte Nutzlast
Hier sehen Sie ein Beispiel, das eine benutzerdefinierte Nutzlast bereitstellt:
{
"fulfillmentMessages": [
{
"payload": {
"facebook": { // for Facebook Messenger integration
"attachment": {
"type": "",
"payload": {}
}
},
"slack": { // for Slack integration
"text": "",
"attachments": []
},
"richContent": [ // for Dialogflow Messenger integration
[
{
"type": "image",
"rawUrl": "https://example.com/images/logo.png",
"accessibilityText": "Example logo"
}
]
],
// custom integration payload here
}
}
]
}
Auftragsausführung aktivieren und verwalten
So aktivieren und verwalten Sie die Auftragsausführung für Ihren Agent über die Console:
- Rufen Sie die Dialogflow ES-Konsole auf.
- Wählen Sie einen Agent aus.
- Wählen Sie im Menü der Seitenleiste Auftragsausführung aus.
- Stellen Sie für das Feld Webhook die Option Aktiviert ein.
- Geben Sie im Formular die Details für Ihren Webhook-Dienst an. Wenn für den Webhook keine Authentifizierung erforderlich ist, lassen Sie die Authentifizierungsfelder leer.
- Klicken Sie auf Speichern.
Informationen zum Aktivieren und Verwalten der Auftragsausführung für Ihren Agent mit der API finden Sie in der
Agent-Referenz. Mit den Methoden getFulfillment und updateFulfillment können Sie die Einstellungen für die Auftragsausführung verwalten.
So aktivieren Sie mit der Konsole die Auftragsausführung für einen Intent:
- Wählen Sie im Menü der linken Seitenleiste Intents aus.
- Wählen Sie einen Intent aus.
- Gehen Sie zum Abschnitt Auftragsausführung.
- Stellen Sie für Webhook-Aufruf für diesen Intent aktivieren die Option „Ein“ ein.
- Klicken Sie auf Speichern.
Informationen zum Aktivieren der Auftragsausführung für einen Intent mit der API finden Sie in der
Referenz zu Intents. Legen Sie das
webhookState Feld auf WEBHOOK_STATE_ENABLED fest.
Webhook-Fehler
Wenn Ihr Webhook-Dienst einen Fehler feststellt, sollte er einen der folgenden HTTP-Statuscodes zurückgeben:
400: Ungültige Anfrage401: Nicht autorisiert403: Verboten404: Nicht gefunden500: Interner Serverfehler503: Dienst nicht verfügbar
In den folgenden Fällen antwortet Dialogflow dem Endnutzer mit der integrierten Antwort, die für den zugeordneten Intent konfiguriert ist:
- Das Zeitlimit für die Antwort wurde überschritten.
- Ein Fehlerstatuscode wurde empfangen.
- Die Antwort ist ungültig.
- Der Webhook-Dienst ist nicht verfügbar.
Wenn ein API-Aufruf zur Intent-Erkennung
den Intent-Abgleich auslöst, enthält das status Feld in der Antwort zur Intent-Erkennung
außerdem die Webhook-Fehlerinformationen. Beispiel:
"status": {
"code": 206,
"message": "Webhook call failed. <details of the error...>"
}
Automatische Wiederholungsversuche
Dialogflow ES enthält interne Mechanismen, die bei bestimmten Webhook-Fehlern automatisch Wiederholungsversuche durchführen, um die Robustheit zu verbessern. Es werden nur nicht schwerwiegende Fehler wiederholt, z. B. Zeitüberschreitungs- oder Verbindungsfehler.
So verringern Sie die Wahrscheinlichkeit doppelter Aufrufe:
- Legen Sie längere Zeitüberschreitungsschwellen für Webhooks fest.
- Unterstützen Sie die Idempotenz in Ihrer Webhook-Logik oder entfernen Sie doppelte Anfragen.
Cloud Run Functions verwenden
Sie können Cloud Run Functions auf verschiedene Arten für die Auftragsausführung verwenden. Der Inline-Editor von Dialogflow kann in Cloud Run Functions eingebunden werden. Wenn Sie den Inline-Editor zum Erstellen und Bearbeiten des Webhook-Codes verwenden, stellt Dialogflow eine sichere Verbindung zu Ihrer Cloud Functions-Funktion her.
Sie können auch eine Cloud Functions-Funktion verwenden, die nicht vom Inline-Editor erstellt wurde. Befindet sich Cloud Function im selben Projekt wie der Agent, kann der Agent den Webhook ohne spezielle Konfiguration aufrufen.
In den folgenden beiden Situationen müssen Sie diese Integration jedoch manuell einrichten:
- Das Dialogflow-Dienst-Agent
Dienstkonto
mit der folgenden Adresse muss für Ihr Agent-Projekt vorhanden sein:
service-agent-project-number@gcp-sa-dialogflow.
- Erstellen Sie einen neuen Agent für das Projekt.
- Führen Sie folgenden Befehl aus:
gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
- Wenn sich die Webhook-Funktion in einem anderen Projekt als der Agent befindet, müssen Sie die Cloud Functions-Invoker IAM-Rolle an das Dienstkonto Dialogflow-Dienst-Agent im Projekt Ihrer Funktion.
Identitätstokens für Dienste
Wenn Dialogflow einen Webhook aufruft, wird ein
Google-Identitätstoken
mit der Anfrage bereitgestellt. Jeder Webhook kann das Token optional mit Google
Clientbibliotheken oder Open-Source-Bibliotheken wie
github.com/googleapis/google-auth-library-nodejs validieren.
Sie können beispielsweise die email des ID-Tokens so prüfen:
service-agent-project-number@gcp-sa-dialogflow.
Beispiele
In den folgenden Beispielen wird gezeigt, wie Sie eine WebhookRequest empfangen und eine WebhookResponse senden. In diesen Beispielen werden Intents verwendet, die in der
Kurzanleitung erstellt wurden.
Go
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Dialogflow CX zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
import (
"encoding/json"
"fmt"
"log"
"net/http"
)
type intent struct {
DisplayName string `json:"displayName"`
}
type queryResult struct {
Intent intent `json:"intent"`
}
type text struct {
Text []string `json:"text"`
}
type message struct {
Text text `json:"text"`
}
// webhookRequest is used to unmarshal a WebhookRequest JSON object. Note that
// not all members need to be defined--just those that you need to process.
// As an alternative, you could use the types provided by
// the Dialogflow protocol buffers:
// https://godoc.org/google.golang.org/genproto/googleapis/cloud/dialogflow/v2#WebhookRequest
type webhookRequest struct {
Session string `json:"session"`
ResponseID string `json:"responseId"`
QueryResult queryResult `json:"queryResult"`
}
// webhookResponse is used to marshal a WebhookResponse JSON object. Note that
// not all members need to be defined--just those that you need to process.
// As an alternative, you could use the types provided by
// the Dialogflow protocol buffers:
// https://godoc.org/google.golang.org/genproto/googleapis/cloud/dialogflow/v2#WebhookResponse
type webhookResponse struct {
FulfillmentMessages []message `json:"fulfillmentMessages"`
}
// welcome creates a response for the welcome intent.
func welcome(request webhookRequest) (webhookResponse, error) {
response := webhookResponse{
FulfillmentMessages: []message{
{
Text: text{
Text: []string{"Welcome from Dialogflow Go Webhook"},
},
},
},
}
return response, nil
}
// getAgentName creates a response for the get-agent-name intent.
func getAgentName(request webhookRequest) (webhookResponse, error) {
response := webhookResponse{
FulfillmentMessages: []message{
{
Text: text{
Text: []string{"My name is Dialogflow Go Webhook"},
},
},
},
}
return response, nil
}
// handleError handles internal errors.
func handleError(w http.ResponseWriter, err error) {
w.WriteHeader(http.StatusInternalServerError)
fmt.Fprintf(w, "ERROR: %v", err)
}
// HandleWebhookRequest handles WebhookRequest and sends the WebhookResponse.
func HandleWebhookRequest(w http.ResponseWriter, r *http.Request) {
var request webhookRequest
var response webhookResponse
var err error
// Read input JSON
if err = json.NewDecoder(r.Body).Decode(&request); err != nil {
handleError(w, err)
return
}
log.Printf("Request: %+v", request)
// Call intent handler
switch intent := request.QueryResult.Intent.DisplayName; intent {
case "Default Welcome Intent":
response, err = welcome(request)
case "get-agent-name":
response, err = getAgentName(request)
default:
err = fmt.Errorf("Unknown intent: %s", intent)
}
if err != nil {
handleError(w, err)
return
}
log.Printf("Response: %+v", response)
// Send response
if err = json.NewEncoder(w).Encode(&response); err != nil {
handleError(w, err)
return
}
}
Java
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Dialogflow CX zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Node.js
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Dialogflow CX zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Python
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Dialogflow CX zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.