Ein Webhook kann entweder ein Standard-Webhook oder ein flexibler Webhook sein. Bei einem Standard-Webhook werden die Anfrage- und Antwortfelder von Dialogflow definiert. Bei einem flexiblen Webhook definieren Sie die Anfrage- und Antwortfelder.
Standard-Webhooks
Mit Standard-Webhooks verwenden Sie von Dialogflow definierte Anfrage- und Antwortnachrichten. Die Anfragenachricht enthält viele Details zur Sitzung. Dazu gehören beispielsweise die aktuelle aktive Seite, der zuletzt zugeordnete Intent, Sitzungsparameterwerte und vom Agent definierte Antworten.
Standard-Webhook-Anfrage
Wenn eine Auftragsausführung mit einem Webhook aufgerufen wird, sendet Dialogflow eine HTTPS-POST-Webhook-Anfrage an Ihren Webhook-Dienst.
Der Text dieser Anfrage ist ein WebhookRequest
-JSON-Objekt mit Informationen zur Sitzung.
Bei einigen Integrationen wird das Feld WebhookRequest.payload
mit zusätzlichen Informationen ausgefüllt.
Die Integration der Dialogflow CX-Telefonie-Gateway-Integration stellt beispielsweise die Anrufer-ID des Endnutzers bereit.
Weitere Informationen finden Sie in der Referenzdokumentation zu WebhookRequest
(V3) oder WebhookRequest
(V3Beta1).
Standard-Webhook-Antwort
Sobald Ihr Webhook-Dienst eine Webhook-Anfrage empfängt, muss er eine Webhook-Antwort senden. Für die Antwort gelten die folgenden Einschränkungen:
- Die Antwort muss innerhalb eines Zeitlimits auftreten, das Sie beim Erstellen der Webhook-Ressource konfigurieren. Andernfalls wird das Zeitlimit der Anfrage ausgelöst.
- Die Antwort darf maximal 64 KiB groß sein.
Weitere Informationen finden Sie in der Referenzdokumentation zu WebhookResponse
(V3) oder WebhookResponse
(V3Beta1).
Standardeinstellungen für Webhook-Ressourcen
Im Folgenden werden die Einstellungen für Webhook-Ressourcen für Standard-Webhooks beschrieben:
Begriff | Definition |
---|---|
Anzeigename | Der Name, der in der Konsole für den Webhook angezeigt wird. |
Webhook-Zeitlimit | Wenn Dialogflow eine Webhook-Anfrage an Ihren Webhook-Dienst sendet, kann es beim Warten auf eine Antwort zu einer Zeitüberschreitung kommen. Mit dieser Einstellung wird das Zeitlimit in Sekunden festgelegt. Wenn eine Zeitüberschreitung auftritt, ruft Dialogflow ein webhook.error.timeout-Ereignis auf. |
Typ | Legen Sie Dienstverzeichnis fest, wenn Sie das Dienstverzeichnis für den privaten Netzwerkzugriff verwenden. Wählen Sie andernfalls Allgemeiner Webdienst aus. |
Webhook-URL | Geben Sie die URL-Adresse für den Webhook-Dienst an. |
Subtyp | Legen Sie Standard fest. |
Umgebungsspezifischer Webhook | Sie können umgebungsspezifische Webhooks bereitstellen. |
Authentifizierung | Weitere Informationen finden Sie im Abschnitt zur Authentifizierung. |
Benutzerdefiniertes CA-Zertifikat | Hiermit werden benutzerdefinierte CA-Zertifikate hochgeladen. |
Flexible Webhooks
Bei flexiblen Webhooks definieren Sie die HTTP-Anfragemethode, die Anfrage-URL-Parameter und die Felder der Anfrage- und Antwortnachrichten. Die Anfrage kann nur ausgewählte Parameterwerte und die Antwort nur Werte für die Parameterüberschreibung angeben. Diese Einschränkung ist tatsächlich vorteilhaft, da sie die Schnittstelle zwischen dem Agent und dem Webhook vereinfacht. Es ist nur selten notwendig, zwischen einem Agent und einem Webhook etwas anderes als Sitzungsparameterwerte zu kommunizieren. Außerdem wird die Webhook-Implementierung vereinfacht, da die Anfrage- und Antwortnachrichten nur das enthalten, was Sie benötigen. Außerdem können Sie für verschiedene Szenarien eindeutige Webhook-Nachrichten bereitstellen.
Flexible Webhook-Anfrage
Beim Erstellen der Webhook-Ressource für Ihren Agent können Sie für Webhook-Anfragen Folgendes angeben:
- Die HTTP-Methode, die für Webhook-Anfragen verwendet wird, die an Ihren Webhook-Dienst gesendet werden.
- Sitzungsparameterwerte, die Dialogflow mithilfe der URL an den Webhook-Dienst senden soll.
- Wenn Sie
POST
,PUT
oderPATCH
als Methode auswählen, können Sie Sitzungsparameterwerte angeben, die Dialogflow über den JSON-Anfragetext an den Webhook-Dienst senden soll.
Wenn Sie Sitzungsparameterwerte über die Anfrage-URL oder den JSON-Text senden möchten, verwenden Sie wie gewohnt Parameterverweise. Sie müssen für den Parameterverweis kein URL-Escape-Zeichen erstellen und den Verweis nicht in Anführungszeichen setzen. Zur Laufzeit maskiert Dialogflow den Parameterwert bei Bedarf per URL. Eine Liste oder ein zusammengesetzter Wert wird im JSON-Format bereitgestellt.
Wenn Sie eine Parameterreferenz im JSON-Text verwenden, müssen Sie sie unabhängig vom Typ des Parameters in Anführungszeichen setzen. Wenn der Parameter tatsächlich ein numerischer Skalarwert, eine Liste oder ein zusammengesetzter Wert ist, entfernt Dialogflow die Anführungszeichen, wenn die Anfrage zur Laufzeit gesendet wird, um den Datentyp des Parameters beizubehalten. Skalartypen von Strings werden weiterhin in Anführungszeichen gesetzt. Wenn in einem Stringwert auf einen numerischen Skalar-, Listen- oder zusammengesetzten Wert verwiesen wird (z. B. "Dies ist eine Zahl: $session.params.size"), wird der Parameter als String behandelt ("Dies ist eine Zahl: 3").
So können Sie beispielsweise die Sitzungsparameterwerte fruit
und size
an die Anfrage-URL übergeben:
https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size
Fügen Sie in den JSON-Anfragetext Folgendes ein:
{
"fruitParameter": "$session.params.fruit",
"sizeParameter": "$session.params.size"
}
Flexible Webhook-Antwort
Beim Erstellen der Webhook-Ressource für den Agent können Sie Sitzungsparameter angeben, die Dialogflow zur Laufzeit auf bestimmte Felder der Webhook-Antwort festlegen soll.
Für die Antwort gelten die folgenden Einschränkungen:
- Die Antwort muss innerhalb eines Zeitlimits auftreten, das Sie beim Erstellen der Webhook-Ressource konfigurieren. Andernfalls wird das Zeitlimit der Anfrage ausgelöst.
- Die Antwort darf maximal 64 KiB groß sein.
Verwenden Sie das folgende Format, um ein skalares, ein Listen- oder zusammengesetztes Feld anzugeben:
$.fully.qualified.path.to.field
Betrachten Sie beispielsweise die folgende JSON-Antwort:
{
"routes" : [
{
"legs" : [
{
"distance" : {
"text" : "2,064 mi",
"value" : 3321004
}
}
]
}
]
}
Verwenden Sie den folgenden Code, um das Feld „value“ anzugeben:
$.routes[0].legs[0].distance.value
Flexible Einstellungen für Webhook-Ressourcen
Im Folgenden werden die Einstellungen für Webhook-Ressourcen für flexible Webhooks beschrieben:
Begriff | Definition |
---|---|
Anzeigename | Der Name, der in der Konsole für den Webhook angezeigt wird. |
Webhook-Zeitlimit | Wenn Dialogflow eine Webhook-Anfrage an Ihren Webhook-Dienst sendet, kann es beim Warten auf eine Antwort zu einer Zeitüberschreitung kommen. Mit dieser Einstellung wird das Zeitlimit in Sekunden festgelegt. Wenn eine Zeitüberschreitung auftritt, ruft Dialogflow ein webhook.error.timeout-Ereignis auf. |
Typ | Legen Sie Dienstverzeichnis fest, wenn Sie das Dienstverzeichnis für den privaten Netzwerkzugriff verwenden. Wählen Sie andernfalls Allgemeiner Webdienst aus. |
Webhook-URL | Geben Sie die URL-Adresse für Ihren Webhook-Dienst an, die Verweise auf Sitzungsparameter enthalten kann. |
Subtyp | Auf Flexibel festlegen |
Methode | Legen Sie die HTTP-Methode für die Webhook-Anfrage fest. |
Anfragetext | Geben Sie den JSON-Anfragetext wie oben beschrieben an. |
Antwortkonfiguration | Geben Sie die Sitzungsparameter an, die auf Antwortfelder festgelegt werden sollen, wie oben beschrieben. |
Umgebungsspezifischer Webhook | Sie können umgebungsspezifische Webhooks bereitstellen. |
Authentifizierung | Weitere Informationen finden Sie im Abschnitt zur Authentifizierung. |
Benutzerdefiniertes CA-Zertifikat | Hiermit werden benutzerdefinierte CA-Zertifikate hochgeladen. |
Vordefinierte benutzerdefinierte Vorlage verwenden
Dialogflow bietet vordefinierte benutzerdefinierte Vorlagen, mit denen Sie flexible Webhooks in Salesforce CRM einbinden können.
Klicken Sie auf dem Tab Manage (Verwalten) auf Webhooks (Webhooks) und dann auf + Create (+ Erstellen).
Wählen Sie unter Untertyp die Option Flexibel aus.
Klicken Sie auf Mit vordefinierter Vorlage konfigurieren, um die Funktion zu aktivieren.
Wählen Sie im Drop-down-Menü Integrationstyp die Option Salesforce aus.
Wählen Sie im Drop-down-Menü API-Name einen API-Namen aus. Die Vorlage füllt das Webhook-Formular automatisch anhand des von Ihnen gewählten API-Namens aus.
Je nach Parametern können Sie die folgenden Felder bei Bedarf manuell konfigurieren:
- Webhook-URL
- Methode
- JSON-Anfragetext
- Antwortkonfiguration
Die erforderlichen OAuth-Felder werden im Abschnitt Authentifizierung hervorgehoben.
Klicken Sie auf Speichern, um den Webhook zu erstellen.
Webhook-Dienstanforderungen
Der Webhook-Dienst muss die folgenden Anforderungen erfüllen:
- Er muss HTTPS-Anfragen verarbeiten. HTTP wird nicht unterstützt. Wenn Sie Ihren Webhook-Dienst mit einer Computing-Lösung oder einer Lösung für serverloses Computing auf der Google Cloud Platform hosten, lesen Sie die Produktdokumentation zum Bereitstellen mit HTTPS. Informationen zu anderen Hostingoptionen finden Sie unter SSL-Zertifikat für eine Domain anfordern.
- Die URL für Anfragen muss öffentlich zugänglich sein, es sei denn, sie wird als Cloud Functions-Funktion gehostet oder als Dienstverzeichnis-Webhook aufgerufen.
- Anfragen und Antworten müssen wie im Abschnitt Standard-Webhook bzw. Flexibler Webhook beschrieben verarbeitet werden.
- Wenn Ihr Agent nicht in den privaten Verzeichniszugriff von Service Directory eingebunden ist, werden Webhook-Aufrufe außerhalb des Dienstperimeters betrachtet und beim Aktivieren von VPC Service Controls blockiert. Eingeschränkte Endpunkte werden von Service Directory unterstützt. Weitere Informationen finden Sie unter Service Directory.
Authentifizierung
Es ist wichtig, den Webhook-Dienst so zu sichern, dass nur Sie oder Ihr Dialogflow-Agent berechtigt sind, Anfragen zu stellen. Dies wird beim Erstellen einer Webhook-Ressource konfiguriert. Dialogflow CX unterstützt die folgenden Authentifizierungsverfahren:
Begriff | Definition |
---|---|
Authentifizierungsheader | Für Webhook-Einstellungen können Sie optionale Schlüssel/Wert-Paare im HTTP-Header angeben. Wenn angegeben, fügt Dialogflow diese HTTP-Header Webhook-Anfragen hinzu. Üblicherweise wird ein einzelnes Paar mit dem Schlüssel authorization angegeben. Headerwerte unterstützen Verweise auf Sitzungsparameter und das Parsing von Systemfunktionen wie in statischen Antwortnachrichten. |
Basisauthentifizierung mit Nutzername und Passwort | Für die Webhook-Einstellungen können Sie optionale Werte für einen Nutzernamen und ein Passwort für die Anmeldung angeben. Wenn angegeben, fügt Dialogflow Webhook-Anfragen einen Autorisierungs-HTTP-Header hinzu. Dieser Header hat das Format "authorization: Basic <base 64 encoding of the string username:password>" . |
Drittanbieter-OAuth | Sie können die OAuth-Konfiguration des Drittanbieters so festlegen, dass Dialogflow ein Zugriffstoken vom OAuth-Anbieter austauscht und im HTTP-Header für die Autorisierung hinzufügt. Es wird nur der Vorgang für Clientanmeldedaten unterstützt. |
Zugriffstokens des Dienst-Agents | Sie können in der Dienst-Agent-Authentifizierung ein Zugriffstoken auswählen, um Zugriffstokens für den Dienst-Agent für die Authentifizierung zu verwenden. Damit kann auf andere Google Cloud APIs zugegriffen werden. |
Dienst-Agent-ID-Tokens | Sie können das ID-Token in der Dienst-Agent-Authentifizierung auswählen, um Dienst-Agent-ID-Tokens für die Authentifizierung zu verwenden. Damit kann auf Cloud Function- und Cloud Run-Dienste zugegriffen werden. Wenn keine anderen Authentifizierungsoptionen verwendet werden, ist diese Option standardmäßig aktiviert. |
Gegenseitige TLS-Authentifizierung | Weitere Informationen finden Sie in der Dokumentation zur gegenseitigen TLS-Authentifizierung. |
HTTPS-Zertifikatsüberprüfung
Dialogflow verwendet standardmäßig den Standard-Trust Store von Google, um HTTPS-Zertifikate zu prüfen. Wenn Sie Zertifikate verwenden möchten, die vom Standard-Trust Store von Google nicht für Ihren HTTPS-Server erkannt werden, z. B. selbst signierte oder benutzerdefinierte Root-Zertifikate, lesen Sie die Informationen unter Benutzerdefinierte CA-Zertifikate.
Umgebungsspezifische Webhooks
Wenn Sie Umgebungen verwenden, um Produktionssysteme von Entwicklungssystemen zu isolieren (empfohlen), können Sie Ihre Webhooks so konfigurieren, dass sie umgebungsspezifisch sind. Für jede von Ihnen definierte Webhook-Ressource können Sie eindeutige URL- und Authentifizierungseinstellungen für jede Umgebung angeben, die Sie für den Agent definiert haben.
So können Sie Webhook-Codeaktualisierungen sicher entwickeln und testen, bevor Sie sie in der Produktion bereitstellen.
Webhook-Ressourcen erstellen oder bearbeiten
Wenn ein Webhook-Dienst ausgeführt wird, müssen Sie in Ihrem Agent eine Webhook-Ressource mit Verbindungs- und Authentifizierungsinformationen erstellen. Nach der Erstellung können Sie die Einstellungen für Webhook-Ressourcen jederzeit bearbeiten.
So erstellen oder bearbeiten Sie eine Webhook-Ressource:
Console
- Öffnen Sie die Dialogflow CX Console.
- Wählen Sie Ihr Google Cloud-Projekt aus.
- Wählen Sie den Agent aus.
- Wählen Sie den Tab Verwalten.
- Klicken Sie auf Webhooks.
- Klicken Sie auf Erstellen oder auf eine Webhook-Ressource in der Liste, um sie zu bearbeiten.
- Geben Sie Standardeinstellungen für Webhook-Ressourcen oder Einstellungen für flexible Webhook-Ressourcen ein.
- Klicken Sie auf Speichern.
API
Informationen zum Erstellen einer Webhook-Ressource finden Sie in der Methode create
für den Typ Webhook
.
Informationen zum Bearbeiten einer Webhook-Ressource (außer umgebungsspezifischen Einstellungen) finden Sie in der Methode patch
oder update
für den Typ Webhook
.
Wählen Sie ein Protokoll und eine Version für die Webhook-Referenz aus:
Protokoll | V3 | V3beta1 |
---|---|---|
REST | Webhook-Ressource | Webhook-Ressource |
RPC | Webhook-Oberfläche | Webhook-Oberfläche |
C++ | WebhooksClient | Nicht verfügbar |
C# | WebhooksClient | Nicht verfügbar |
Einfach loslegen (Go) | WebhooksClient | Nicht verfügbar |
Java | WebhooksClient | WebhooksClient |
Node.js | WebhooksClient | WebhooksClient |
PHP | Nicht verfügbar | Nicht verfügbar |
Python | WebhooksClient | WebhooksClient |
Ruby | Nicht verfügbar | Nicht verfügbar |
Informationen zum Bearbeiten der umgebungsspezifischen Einstellungen für einen Webhook finden Sie in der Methode patch
oder update
für den Typ Environment
.
Wählen Sie ein Protokoll und eine Version für die Umgebungsreferenz aus:
Protokoll | V3 | V3beta1 |
---|---|---|
REST | Umgebungsressource | Umgebungsressource |
RPC | Umgebungsschnittstelle | Umgebungsschnittstelle |
C++ | EnvironmentsClient | Nicht verfügbar |
C# | EnvironmentsClient | Nicht verfügbar |
Einfach loslegen (Go) | EnvironmentsClient | Nicht verfügbar |
Java | EnvironmentsClient | EnvironmentsClient |
Node.js | EnvironmentsClient | EnvironmentsClient |
PHP | Nicht verfügbar | Nicht verfügbar |
Python | EnvironmentsClient | EnvironmentsClient |
Ruby | Nicht verfügbar | Nicht verfügbar |
Webhook-Fehler
Wenn Ihr Webhook-Dienst bei der Verarbeitung einer Webhook-Anfrage einen Fehler feststellt, muss Ihr Webhook-Code einen der folgenden HTTP-Statuscodes zurückgeben:
400
Fehlerhafte Anfrage401
Nicht autorisiert403
Unzulässig404
Nicht gefunden500
Serverfehler503
Dienst nicht verfügbar
In allen folgenden Fehlersituationen ruft Dialogflow einen Webhook-Fehler oder ein integriertes Zeilimitereignis auf und fährt mit der Verarbeitung wie gewohnt fort:
- Antwortzeitlimit überschritten.
- Fehlerstatuscode empfangen.
- Die Antwort ist ungültig.
- Der Webhook-Dienst ist nicht verfügbar.
Wenn der Webhook-Dienstaufruf durch einen API-Aufruf zur Intent-Erkennung ausgelöst wurde, enthält das Feld queryResult.webhookStatuses
in der Antwort zur Intent-Erkennung die Webhook-Statusinformationen.
Cloud Functions verwenden
Dialogflow lässt sich in Cloud Functions einbinden, sodass Sie problemlos einen sicheren, serverlosen Webhook erstellen können. Wenn Sie eine Funktion erstellen, die sich im selben Projekt wie Ihr Agent befindet, kann der Agent den Webhook ohne spezielle Konfiguration sicher aufrufen.
Es gibt jedoch zwei Situationen, in denen Sie diese Integration manuell einrichten müssen:
- Das Dienstkonto des Dialogflow-Dienst-Agents mit der folgenden Adresse muss für Ihr Agent-Projekt vorhanden sein:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Dieses spezielle Dienstkonto und der zugehörige Schlüssel werden normalerweise automatisch erstellt, wenn Sie den ersten Agent für ein Projekt erstellen. Wenn Ihr Agent vor dem 1. November 2020 erstellt wurde, können Sie die Erstellung dieses speziellen Dienstkontos auslösen:- Erstellen Sie einen neuen Agent für das Projekt.
- Führen Sie den 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 den Cloud Functions-Invoker IAM-Rolle an die Dialogflow-Dienst-Agent Dienstkonto im Projekt Ihrer Funktion.
Container-Webhooks und das Go ezcx-Framework verwenden
Wenn Sie einen Container-Webhook mit Go implementieren möchten, lesen Sie das Go ezcx-Framework. Dieses Framework kann viele der zum Erstellen eines Webhooks erforderlichen Schritte vereinfachen.
Service Directory für den privaten Netzwerkzugriff verwenden
Dialogflow wird in privaten Service Directory-Zugriff eingebunden, sodass eine Verbindung zu Webhook-Zielen in Ihrem VPC-Netzwerk hergestellt werden kann. Dadurch wird der Traffic innerhalb des Google Cloud-Netzwerks beibehalten und IAM sowie VPC Service Controls erzwungen.
So richten Sie einen Webhook ein, der auf ein privates Netzwerk ausgerichtet ist:
Folgen Sie der Anleitung unter Private Netzwerkkonfiguration für Service Directory, um Ihr VPC-Netzwerk und Ihren Service Directory-Endpunkt zu konfigurieren.
Das Dienstkonto des Dialogflow-Dienst-Agents mit der folgenden Adresse muss für Ihr Agent-Projekt vorhanden sein:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Gewähren Sie dem Dienstkonto Dialogflow-Dienst-Agent die folgenden IAM-Rollen:servicedirectory.viewer
des Service Directory-Projektsservicedirectory.pscAuthorizedService
des Netzwerkprojekts
Geben Sie beim Erstellen des Webhooks den Service Directory-Dienst mit der URL und optionalen Authentifizierungsinformationen an.
Console
API
Weitere Informationen finden Sie im Feld
serviceDirectory
für den TypWebhook
.Wählen Sie ein Protokoll und eine Version für die Webhook-Referenz aus:
Protokoll V3 V3beta1 REST Webhook-Ressource Webhook-Ressource RPC Webhook-Oberfläche Webhook-Oberfläche C++ WebhooksClient Nicht verfügbar C# WebhooksClient Nicht verfügbar Einfach loslegen (Go) WebhooksClient Nicht verfügbar Java WebhooksClient WebhooksClient Node.js WebhooksClient WebhooksClient PHP Nicht verfügbar Nicht verfügbar Python WebhooksClient WebhooksClient Ruby Nicht verfügbar Nicht verfügbar
Zur Fehlerbehebung können Sie eine private Verfügbarkeitsdiagnose einrichten, die prüft, ob Service Directory richtig konfiguriert ist.
Dienst-Agent-Authentifizierung
Dialogflow kann mit dem Dialogflow-Dienst-Agent ein ID-Token oder ein Zugriffstoken generieren.
Das Token wird dem Autorisierungs-HTTP-Header hinzugefügt, wenn Dialogflow einen Webhook aufruft.
ID-Token
Ein ID-Token kann verwendet werden, um auf Cloud Function- und Cloud Run-Dienste zuzugreifen, nachdem Sie die Invoker-Rolle zugewiesen haben
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.comWenn sich Cloud Function- und Cloud Run-Dienste im selben Ressourcenprojekt befinden, benötigen Sie keine zusätzliche IAM-Berechtigung, um sie aufzurufen.
Die Zielgruppe, die zum Generieren des ID-Tokens verwendet wird, ist die gesamte Webhook-URL mit Ausnahme von Abfrageparametern. Wenn Sie Cloud Run verwenden, muss diese URL von den Cloud Run-Zielgruppen unterstützt werden. Wenn die Webhook-URL beispielsweise
https://myproject.cloudfunctions.net/my-function/method1?query=value
muss sich die folgende URL in benutzerdefinierten Zielgruppen befinden.
https://myproject.cloudfunctions.net/my-function/method1
Jeder Webhook kann das Token optional mit Google-Clientbibliotheken oder Open-Source-Bibliotheken wie github.com/googleapis/google-auth-library-nodejs validieren.
Zugriffstoken
Ein Zugriffstoken kann für den Zugriff auf andere Google Cloud APIs verwendet werden, nachdem Sie
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.comdie erforderlichen Rollen gewährt haben
Beispiele und Fehlerbehebung
Weitere Informationen finden Sie in der Anleitung für Webhooks.