Webhooks

Webhooks sind Dienste, die Ihre Geschäftslogik hosten oder andere Dienste anrufen. Während einer Sitzung können Sie mit Webhooks Folgendes verwenden: die von den Natural Language Processing-Funktionen von Conversational Agents (Dialogflow CX) extrahierten Daten dynamische Antworten generieren, erhobene Daten validieren, oder Aktionen im Back-End auslösen.

Ein Webhook kann entweder ein Standard-Webhook oder ein flexibler Webhook sein. Bei einem Standard-Webhook werden die Anfrage- und Antwortfelder von Konversations-Agents (Dialogflow CX) definiert. Mit einem flexiblen Webhook die Anfrage- und Antwortfelder.

Standard-Webhooks

Bei Standard-Webhooks verwenden Sie Anfrage- und Antwortnachrichten, die von Konversations-Agents (Dialogflow CX) definiert wurden. Die Anfrage enthält viele Details zur Sitzung. Dazu gehören beispielsweise die aktuell aktive Seite, der zuletzt zugeordnete Intent, Werte für Sitzungsparameter und vom Kundenservicemitarbeiter definierte Antworten.

Standard-Webhook-Anfrage

Wenn eine Auftragsausführung mit einem Webhook aufgerufen wird, sendet Conversational Agents (Dialogflow CX) eine HTTPS-POST-Webhook-Anfrage an Ihren Webhook-Dienst. Der Text dieser Anfrage ist ein WebhookRequest-JSON-Objekt mit Informationen zur Sitzung.

Einige Integrationen geben Sie in das Feld WebhookRequest.payload zusätzliche Informationen ein. Die Dialogflow CX Phone Gateway-Integration liefert beispielsweise die Anrufer-ID des Endnutzers.

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 Console für den Webhook angezeigt wird.
Webhook-Zeitlimit	Wenn Conversational Agents (Dialogflow CX) eine Webhook-Anfrage an Ihren Webhook-Dienst senden, 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, rufen Konversations-Agents (Dialogflow CX) das Ereignis webhook.error.timeout 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 für Ihren Webhook-Dienst an.
Subtyp	Legen Sie Standard fest.
Umgebungsspezifischer Webhook	Sie können umgebungsspezifische Webhooks bereitstellen.
Authentifizierung	Weitere Informationen finden Sie im Abschnitt Authentifizierung.
Benutzerdefiniertes CA-Zertifikat	Hiermit werden benutzerdefinierte CA-Zertifikate hochgeladen.

Flexible Webhooks

Mit flexiblen Webhooks definieren Sie die HTTP-Anfragemethode, die URL-Anfrageparameter und die Felder der Anfrage- und Antwortnachrichten. Die Anfrage kann nur ausgewählte Parameterwerte bereitstellen, und in der Antwort können nur Werte für die Parameterüberschreibung angegeben werden. Diese Einschränkung ist tatsächlich vorteilhaft, da die Schnittstelle zwischen dem Agent und dem Webhook vereinfacht wird. In der Regel müssen zwischen einem Kundenservicemitarbeiter und einem Webhook nur Sitzungsparameterwerte ausgetauscht werden. Außerdem wird die Webhook-Implementierung vereinfacht, da die Anfrage- und Antwortnachrichten nur das enthalten, was Sie brauchen, Außerdem können Sie für verschiedene Szenarien eindeutige Webhook-Nachrichten bereitstellen.

Flexible Webhook-Anfrage

Wenn Sie die Webhook-Ressource für Ihren Kundenservicemitarbeiter erstellen, können Sie Folgendes für Webhook-Anfragen angeben:

• Die für Webhook-Anfragen verwendete HTTP-Methode die an Ihren Webhook-Dienst gesendet wurden.
• Sitzungsparameterwerte, die Conversational Agents (Dialogflow CX) an Ihren Webhook-Dienst senden sollen mithilfe der URL.
• Wenn Sie POST, PUT oder PATCH als Methode auswählen, Sie können Sitzungsparameterwerte angeben, die Conversational Agents (Dialogflow CX) verwenden. über den JSON-Texttext der Anfrage an Ihren Webhook-Dienst senden sollte.

Um Sitzungsparameterwerte über die Anfrage-URL oder den JSON-Text zu senden, verwenden Sie Parameterverweise wie gewohnt. Sie müssen die Parameterreferenz nicht URL-entkommentieren und sie nicht in Anführungszeichen setzen. Zur Laufzeit wird der Parameterwert von Conversational Agents (Dialogflow CX) nach Bedarf URL-codiert. Eine Liste oder ein zusammengesetzter Wert wird als JSON bereitgestellt.

Wenn Sie im JSON-Textkörper eine Parameterreferenz verwenden, müssen Sie die Referenz unabhängig vom Parametertyp in Anführungszeichen setzen. Wenn es sich bei dem Parameter tatsächlich um einen numerischen Skalar-, Listen- oder zusammengesetzten Wert handelt, entfernt der Konversationsagent (Dialogflow CX) die Anführungszeichen beim Senden der Anfrage zur Laufzeit, 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 Beispiel: "Das ist eine Zahl: $session.params.size". wird der Parameter als String ("Dies ist eine Zahl: 3").

So können Sie beispielsweise die Werte der Sitzungsparameter fruit und size in die Anfrage-URL einfügen:

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

Wenn Sie die Webhook-Ressource für den Agent erstellen, Sie können Sitzungsparameter angeben, die von Conversational Agents (Dialogflow CX) festgelegt werden sollen. bestimmten Feldern der Webhook-Antwort zur Laufzeit hinzugefügt werden.

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

Beispiel: Betrachten Sie die folgende JSON-Antwort:

{
  "routes" : [
    {
      "legs" : [
        {
          "distance" : {
            "text" : "2,064 mi",
            "value" : 3321004
          }
        }
      ]
    }
  ]
}

Um den „Wert“ anzugeben, Feld, verwenden Sie Folgendes:

$.routes[0].legs[0].distance.value

Flexible Webhook-Ressourceneinstellungen

Im Folgenden werden die Einstellungen für Webhook-Ressourcen für flexible Webhooks beschrieben:

Begriff	Definition
Anzeigename	Der Name, der in der Console für den Webhook angezeigt wird.
Webhook-Zeitlimit	Wenn Conversational Agents (Dialogflow CX) eine Webhook-Anfrage an Ihren Webhook-Dienst senden, 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, rufen Konversations-Agents (Dialogflow CX) das Ereignis webhook.error.timeout 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	Legen Sie Flexibel fest.
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 wie oben beschrieben in Antwortfeldern festgelegt werden sollen.
Umgebungsspezifischer Webhook	Sie können umgebungsspezifische Webhooks angeben.
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.

1. Klicken Sie auf dem Tab Manage (Verwalten) auf Webhooks (Webhooks) und dann auf + Create (+ Erstellen).

2. Wählen Sie unter Untertyp die Option Flexibel aus.

3. Klicken Sie auf Mit vordefinierter Vorlage konfigurieren, um die Funktion zu aktivieren.

4. Wählen Sie im Drop-down-Menü Integrationstyp die Option Salesforce aus.

5. Wählen Sie im Drop-down-Menü API-Name einen API-Namen aus. Anhand des von Ihnen ausgewählten API-Namens wird das Webhook-Formular automatisch ausgefüllt.

   1. Sie können die folgenden Felder bei Bedarf manuell konfigurieren, basierend auf Ihre Parameter:

      • Webhook-URL
      • Methode
      • JSON-Anfragetext
      • Antwortkonfiguration

   2. Die erforderlichen OAuth-Felder werden im Abschnitt Authentifizierung hervorgehoben.

6. 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 Ersuchen muss öffentlich zugänglich sein. Es sei denn, sie wird als Cloud Run-Funktion gehostet oder als Dienstverzeichnis-Webhook aufgerufen.
• Er muss Anfragen und Antworten wie in der Abschnitt Standard-Webhook oder flexibler Webhook.
• 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

Hinweis: Webhook-Quell-IP-Adressen gehören zu den unter https://www.gstatic.com/ipranges/goog.json aufgeführten IP-Adressen, ausgenommen die unter https://www.gstatic.com/ipranges/cloud.json. Darüber hinaus kann Dialogflow keine Garantien für IP-Bereiche für Maschinen geben, die Webhook-Anfragen senden. Anstatt den Zugriff anhand des IP-Bereichs einzuschränken, sollten Sie eine der Authentifizierungsmethoden, die in der folgenden Tabelle aufgeführt sind.

Es ist wichtig, den Webhook-Dienst zu sichern, damit nur Sie oder Ihr Conversational Agents (Dialogflow CX)-Agent zum Senden von Anfragen berechtigt sind. Dies wird beim Erstellen einer Webhook-Ressource konfiguriert. Konversations-Agents (Dialogflow CX) unterstützen die folgenden Authentifizierungsmechanismen:

Begriff	Definition
Authentifizierungs-Header	Für Webhook-Einstellungen können Sie optionale Schlüssel/Wert-Paare im HTTP-Header angeben. Wenn angegeben, werden diese HTTP-Header von Conversational Agents (Dialogflow CX) zu Webhook-Anfragen hinzugefügt. Ü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 den Anmeldenutzernamen und das Anmeldepasswort angeben. Wenn angegeben, fügt Conversational Agents (Dialogflow CX) einen Autorisierungs-HTTP-Header zu Webhook-Anfragen hinzu. Dieser Header hat das Format "authorization: Basic <base 64 encoding of the string username:password>".
OAuth von Drittanbietern	Sie können die OAuth-Konfiguration für Drittanbieter so festlegen, dass Conversational Agents (Dialogflow CX) ein Zugriffstoken aus dem OAuth-System austauschen und im HTTP-Header für die Autorisierung hinzufügen. Es wird nur der Vorgang für Clientanmeldedaten unterstützt.
Zugriffstokens des Dienst-Agents	Sie können „Zugriffstoken“ in der Authentifizierung für Kundenservicemitarbeiter auswählen, um Zugriffstokens für Kundenservicemitarbeiter für die Authentifizierung zu verwenden. Damit kann auf andere Google Cloud APIs zugegriffen werden.
Dienst-Agent-ID-Tokens	Sie können „ID-Token“ in der Authentifizierung für Kundenservicemitarbeiter auswählen, um ID-Tokens für Kundenservicemitarbeiter für die Authentifizierung zu verwenden. Damit können Sie auf Cloud Run-Funktionen und Cloud Run-Dienste zugreifen.
Gegenseitige TLS-Authentifizierung	Weitere Informationen finden Sie in der Dokumentation zur gegenseitigen TLS-Authentifizierung.

Hinweis: Wenn mehrere Authentifizierungsoptionen aktiviert sind, haben Optionen mit höherer Priorität Vorrang. Prioritätsreihenfolge der Authentifizierungsoptionen: Authentifizierungsheader, Basisauthentifizierung, OAuth von Drittanbietern, Authentifizierung des Service-Agenten.

Drittanbieter-OAuth

Conversational Agents (Dialogflow CX) können ein Zugriffstoken von einem Drittanbieter-OAuth-Anbieter abrufen und bei Webhook-Anfragen dem Autorisierungs-HTTP-Header hinzufügen.

Im Folgenden werden die Ressourceneinstellungen für OAuth von Drittanbietern beschrieben:

Begriff	Definition
Client-ID	Die Client-ID, die beim Anfordern eines OAuth-Tokens verwendet werden soll.
Clientschlüssel	Das Geheimnis, das beim Anfordern eines OAuth-Tokens verwendet werden soll.
OAuth-Endpunkt-URL	Die URL, die zum Anfordern eines OAuth-Tokens verwendet werden soll.
OAuth-Bereiche	Eine durch Kommas getrennte Liste von Bereichen, für die das OAuth-Token verwendet werden kann.

Anfragen, die zum Erhalt eines Tokens an die URL des OAuth-Endpunkts gesendet werden, enthalten nicht die benutzerdefinierten Anfrageheader, die für die Webhook-Anfrage konfiguriert sind. Sie können benutzerdefinierte Informationen als Parameter im Abfragestring der OAuth-Endpunkt-URL an den OAuth-Server übergeben.

Hinweis: OAuth-Tokens von Drittanbietern werden für Webhook-Anfragen mit derselben Client-ID, Endpoint-URL und denselben Bereichen innerhalb desselben Conversational AI-Agents (Dialogflow CX) wiederverwendet, sofern die Anfrage an denselben Conversational AI-Server (Dialogflow CX) gesendet wird und das Token nicht abgelaufen ist. Um eine hohe Verfügbarkeit zu erreichen, werden Agents auf vielen einzelnen Servern bereitgestellt, die keine gemeinsamen OAuth-Token-Caches verwenden. Wenn Sie eine Lösung bereitstellen, die OAuth-Tokens von Drittanbietern verwendet, sollten Sie die Implementierung eines API-Proxy sorgfältig in Betracht ziehen, um die Menge der Anfragen zu verwalten, die Ihr Agent möglicherweise an Ihren OAuth-Drittanbieter sendet.

Zugriffstokens des Dienst-Agents

Konversations-KI-Agents (Dialogflow CX) können mit dem Konversations-KI-Agent (Dialogflow CX)-Dienst ein ID-Token oder ein Zugriffstoken generieren.

Das Token wird in den Autorisierungs-HTTP-Header eingefügt, wenn Conversational Agents (Dialogflow CX) einen Webhook aufrufen.

ID-Token

Ein ID-Token kann verwendet werden, um auf Cloud Run-Funktionen und Cloud Run-Dienste zuzugreifen, nachdem Sie der

[e-mail]

Wenn sich die Cloud Run-Funktionen und Cloud Run-Dienste im selben Ressourcenprojekt befinden, benötigen Sie keine zusätzlichen IAM-Berechtigung zum Aufrufen.

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 zum Zugriff auf andere Google Cloud APIs verwendet werden, nachdem Sie die erforderlichen Rollen für

[e-mail]

HTTPS-Zertifikatsüberprüfung

Konversations-Agents (Dialogflow CX) verwenden standardmäßig den Standard-Trust Store von Google, um HTTPS zu verifizieren. Zertifikate. 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 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, die Sie für den Agent definiert haben.

So können Sie Ihre Webhook-Codeupdates 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

1. Öffnen Sie die Dialogflow CX Console.
2. Wählen Sie Ihr Google Cloud-Projekt aus.
3. Wählen Sie den Agent aus.
4. Wählen Sie den Tab Verwalten.
5. Klicken Sie auf Webhooks.
6. Klicken Sie auf Erstellen oder auf eine Webhook-Ressource in der Liste, die Sie bearbeiten möchten.
7. Geben Sie Standardeinstellungen für Webhook-Ressourcen oder flexible Einstellungen für Webhook-Ressourcen ein.
8. Klicken Sie auf Speichern.

API

Informationen zum Erstellen einer Webhook-Ressource finden Sie in der Methode create für den Typ Webhook. So bearbeiten Sie eine Webhook-Ressource (außer umgebungsspezifischen Einstellungen): Siehe die Methode patch oder update für den Typ Webhook. Zur Webhook API-Referenz

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
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

Schließen

So bearbeiten Sie die umgebungsspezifischen Einstellungen für einen Webhook: Siehe die Methode patch oder update für den Typ Environment. Rufen Sie die Umgebung zur API-Referenz auf

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
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

Schließen

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 Anfrage
• 401 Nicht autorisiert
• 403 Unzulässig
• 404 Nicht gefunden
• 500 Serverfehler
• 503 Dienst nicht verfügbar

In einer der folgenden Fehlersituationen Conversational Agents (Dialogflow CX) rufen einen Webhook-Fehler oder eine Zeitüberschreitung auf integriertes Ereignis und die Verarbeitung wie gewohnt fortgesetzt:

• 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.

Automatische Wiederholungsversuche

Konversations-Agents (Dialogflow CX) umfassen interne Mechanismen, die den Vorgang automatisch wiederholen bestimmte Webhook-Fehler, um die Stabilität zu verbessern. Nur nicht-terminale Fehler Wiederholungsversuche (z. B. Zeitüberschreitung oder Verbindungsfehler)

So verringern Sie die Wahrscheinlichkeit doppelter Aufrufe:

• Legen Sie längere Zeitlimits für Webhooks fest.
• Unterstützung von Idempotenz in Webhook-Logik oder Deduplizierung.

Cloud Run-Funktionen verwenden

Hinweis: In diesem Abschnitt wird beschrieben, wie Sie sichere Cloud Run-Funktionen für Webhooks von Conversational Agents (Dialogflow CX) verwenden. Wir empfehlen, Ihre Funktionen zu schützen. Wenn Sie sich jedoch mit einem URL-basierten Nutzernamen und Passwort oder mit HTTP-Headern authentifizieren, sollten Sie nicht authentifizierten Zugriff auf Ihre Funktion zulassen.

Conversational Agents (Dialogflow CX) können in Cloud Run-Funktionen So können Sie ganz einfach einen sicheren, serverlosen Webhook erstellen. Wenn Sie eine Funktion erstellen, die sich im selben Projekt wie der Agent befindet, wählen Sie einfach Service Agent Auth -> ID Token in der Auth-Konfiguration kann der Agent den Webhook dann sicher aufrufen.

Es gibt jedoch zwei Situationen, in denen Sie diese Integration manuell einrichten müssen:

1. Der Dienst-Agent für Konversations-Agents (Dialogflow CX) Dienstkonto mit der folgenden Adresse für Ihr Agent-Projekt vorhanden sein:

   [e-mail]

   Dieses spezielle Dienstkonto und der zugehörige Schlüssel werden beim Erstellen des ersten Agents für ein Projekt normalerweise automatisch erstellt. Wenn Ihr Agent vor dem 1. November 2020 erstellt wurde, können Sie dieses spezielle Dienstkonto erstellen:
   1. Erstellen Sie einen neuen Agent für das Projekt.
   2. Führen Sie folgenden Befehl aus:

      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id

2. Wenn sich die Webhook-Funktion in einem anderen Projekt als der Agent befindet, müssen Sie den Cloud Functions Invoker IAM-Rolle auf das Dienstkonto Conversational Agents (Dialogflow CX) Service Agent im Projekt Ihrer Funktion.
3. Wählen Sie Dienst-Agent-Authentifizierung -> ID Token (ID-Token) aus.

Containerisierte Webhooks und das Go ezcx-Framework verwenden

Informationen zum Implementieren eines Container-Webhooks mit Go finden Sie in der Go ezcx-Framework Dieses Framework kann viele der zum Erstellen eines Webhooks erforderlichen Schritte vereinfachen.

Cloud Run-Funktionen nur für internen Traffic verwenden

Hinweis: Die Verwendung von Cloud Run-Funktionen außerhalb des VPC Service Controls-Perimeters eines Dialogflow CX-Kundenservicemitarbeiterprojekts für Webhooks wird nicht unterstützt.

Cloud Run-Funktionen, die so eingerichtet sind, dass sie internen Traffic von VPC-Netzwerken im selben Projekt oder im selben VPC SC-Perimeter akzeptieren, können als Webhook verwendet werden, solange sich der Agent im selben Projekt oder im selben VPC SC-Perimeter befindet.

Service Directory für den privaten Netzwerkzugriff verwenden

Conversational Agents (Dialogflow CX) können in Zugriff auf private Netzwerke auf Service Directory um eine Verbindung zu Webhook-Zielen in Ihrem VPC-Netzwerk herzustellen. 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:

1. Folgen Sie der Anleitung unter Private Netzwerkkonfiguration für Service Directory, um Ihr VPC-Netzwerk und Ihren Service Directory-Endpunkt zu konfigurieren.

   Hinweis: Conversational Agents (Dialogflow CX) speichern Service Directory-Informationen 90 Sekunden lang im Cache. Wenn Sie den Service Directory-Endpunkt aktualisieren, dauert es 90 Sekunden, bis die Änderung wirksam wird. Wenn Sie mehrere Endpunkte für Redundanz einrichten, Konversations-Agents (Dialogflow CX) senden möglicherweise 90 Sekunden lang Traffic über einen ausgefallenen Endpunkt.

2. Der Dienst-Agent für Konversations-Agents (Dialogflow CX) Dienstkonto mit der folgenden Adresse für Ihr Agent-Projekt vorhanden sein:

   [e-mail]

   Weisen Sie dem Dienstkonto Conversational Agents (Dialogflow CX) Service Agent die folgenden IAM-Rollen zu:
   • servicedirectory.viewer des Service Directory-Projekts
   • servicedirectory.pscAuthorizedService des Netzwerkprojekts

3. 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 Typ Webhook. Zur Webhook API-Referenz

   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
   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

   Schließen

Zur Fehlerbehebung können Sie eine private Verfügbarkeitsdiagnose einrichten, um zu prüfen, ob Ihre Service Directory korrekt konfiguriert ist.

Beispiele und Fehlerbehebung

Weitere Informationen finden Sie in der Anleitung für Webhooks