Dieser Leitfaden enthält verschiedene Beispiele für die Implementierung von webhooks sowie Empfehlungen zur Fehlerbehebung bei Webhooks.
Sitzungsparameter festlegen
In den folgenden Beispielen wird gezeigt, wie ein Sitzungsparameter festgelegt wird.
Go
Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Kurzanleitung für WebhooksJava
Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Node.js
Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Python
Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Auftragsausführungsantwort zurückgeben
Die folgenden Beispiele zeigen, wie eine Ausführungsantwort zurückgegeben wird.
Go
Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Kurzanleitung für WebhooksJava
Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Node.js
Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Python
Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Legen Sie nach Bedarf die Formularparameter fest.
In den folgenden Beispielen wird gezeigt, wie ein Parameter als erforderlich gekennzeichnet wird.
Java
Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Node.js
Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Formularparameter validieren
In den folgenden Beispielen wird gezeigt, wie ein Formularparameter validiert wird.
Java
Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Node.js
Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Python
Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Sitzungs-ID protokollieren
Im folgenden Beispiel wird gezeigt, wie du die session ID
aus einer Webhook-Anfrage protokollierst.
Python
Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Fehlerbehebung
Ablauf eines Webhook-Aufrufs
Webhook-Aufrufe werden immer von Conversational Agents (Dialogflow CX) initiiert und über HTTPS an einen Webserver gesendet. Generische Webhook-Aufrufe für Webdienste stammen von einer Internet-IP-Adresse, die zu Google gehört, und können Webserver (Webhook-Server) erreichen, die im öffentlichen Internet verfügbar sind. Service Directory-Webhooks starten dagegen immer von einer internen Google Cloud-Adresse und können nur Webhook-Server in privaten Netzwerken innerhalb von Google Cloud erreichen.
Hilfreiche Protokolle zur Fehlerbehebung bei Webhooks
Zum Beheben von Webhook-Problemen müssen in der Regel die Dialogflow-Protokolle von Cloud Logging und die Webhook-Serverprotokolle erfasst werden. Wenn der Webhook-Server mit Cloud Run-Funktionen implementiert ist, befinden sich seine Protokolle in Cloud Logging. Andernfalls befinden sich die Protokolle normalerweise dort, wo der Webhook-Server ausgeführt wird.
Standard-Webhook-Logs enthalten ein Feld detectIntentResponseId
mit einer UUID, die nützlich sein kann, um einen bestimmten Aufruf in Webhook-Servern zu verfolgen. Dieses Protokoll ist in den Dialogflow-Cloud Logging-Logs verfügbar, wenn Cloud Logging aktiviert ist.
Häufige Webhook-Probleme
Beispiele für Fehler in den Dialogflow-Logs für Webhook-Aufrufe:
Fehler bei der Auflösung des Hostnamens des Webhook-Servers
Dialogflow hat den Hostnamen eines generischen Webhooks ermittelt und der Hostname ist im DNS nicht vorhanden. Der Hostname muss im öffentlichen DNS registriert sein. Wenn der Hostname neu ist, kann es einige Zeit dauern, bis der Eintrag übernommen wird. Cloud Logging-Nachricht:
State: URL_ERROR, Reason: ERROR_DNS
.
Der Webhook-Server gibt einen clientseitigen Fehler zurück
Außer ERROR_DNS
gibt dieser Status eine 4xx-Antwort vom Webhook-Server an. Dies kann ein nicht autorisierter Status (401 – ERROR_AUTHENTICATION
) oder ein Fehler sein, dass die URL nicht auf dem Webhook-Server gefunden wurde (404 – ERROR_NOT_FOUND
).
Cloud Logging-Nachricht: State: URL_ERROR
.
Dialogflow-Agent löst Zeitüberschreitung aus, bevor der Webhook-Server eine Antwort zurückgibt
Dialogflow hat das Timeout-Limit für Webhooks erreicht, bevor der Webserver fertig war. Es gibt zwei mögliche Ansätze: Sie können die Verarbeitungszeit des Webhook-Servers verkürzen oder die Zeit verlängern, die Dialogflow auf den Webhook wartet. Die Verkürzung der Verarbeitungszeit führt in der Regel zu den besten Ergebnissen, ist aber in vielen Fällen nicht trivial. Beachten Sie, dass es ein maximales Zeitlimit für Webhooks gibt und dass Anrufer oder Nutzer länger warten müssen, um eine Antwort vom Kundenservicemitarbeiter zu erhalten, bevor Sie diese Einstellung erhöhen. Cloud Logging-Nachricht: State: URL_TIMEOUT, Reason: TIMEOUT_WEB
.
gRPC-Zeitüberschreitung, bevor der Webhook-Server eine Antwort zurückgibt
Das von gRPC im Dialogflow API-Aufruf festgelegte Zeitlimit wurde erreicht, bevor der Webhook-Aufruf abgeschlossen wurde. Dieses Limit wird in der Regel auf Integrationsebene festgelegt und ist unabhängig von den Dialogflow-Parametern und Timeout-Limits für Webhooks. Weitere Informationen zu gRPC-Fristen finden Sie unter https://grpc.io/docs/guides/deadlines/.
Cloud Logging-Nachricht: State: URL_REJECTED, Reason: REJECTED_DEADLINE_EXCEEDED
.
Dialogflow konnte den Webhook-Server nicht kontaktieren
Der Webhook-Server konnte aufgrund eines Netzwerkfehlers nicht erreicht werden oder die Verbindung wurde hergestellt und der Webhook-Server gab den HTTP-Status 5xx zurück, was auf ein Problem bei der Verarbeitung der Anfrage hinweist. Achten Sie darauf, dass Dialogflow die Webhook-Serveradresse auf Netzwerkebene erreichen kann. Wenn die Anfrage in den Webhook-Serverprotokollen angezeigt wird, ermitteln Sie, warum der Aufruf einen 5xx-Fehler zurückgegeben hat. Cloud Logging-Nachricht:
State: URL_UNREACHABLE
.
Webhook-Aufrufe erfassen
Ein Standard-Webhook-Aufruf kann mithilfe der Sitzungs-ID, der detectIntentResponse
-ID, der Trace-ID für Cloud Run-Funktionen und eines Zeitstempels des Aufrufs zwischen Dialogflow und einem Webhook-Server in Beziehung gesetzt werden. Eine flexible Webhook-Analyse kann mithilfe des Zeitstempels der Aufrufe und der Sitzungsparameterwerte durchgeführt werden, die in der Webhook-Definition zur Laufzeit festgelegt wurden. Weitere Informationen zu Standard- und flexiblen Webhook-Anfragen finden Sie unter Webhooks.
Die Sitzungs-ID wird im Feld sessionInfo.session
der WebhookRequest angezeigt.
Diese Sitzungs-ID sollte für jede Unterhaltung eindeutig sein. Sie kann Ihnen helfen, Kundenservicemitarbeiter-Logs mit Webhook-Logs für Anfragen mit derselben Sitzungs-ID zu vergleichen.
Im vorherigen Abschnitt Sitzungs-ID protokollieren wird beschrieben, wie die Sitzungs-ID über einen Webhook protokolliert wird.
Wenn Sie Ihren Webhook mit Cloud Run-Funktionen oder einer ähnlichen serverlosen Google Cloud-Option hosten, können Sie das Feld trace
aus Logeinträgen als Logfilter verwenden.
Eine einzelne Ausführung einer Funktion führt zu mehreren Logeinträgen mit demselben Trace-Wert.
Im nächsten Beispiel werden sowohl die Sitzungs-ID als auch der Trace-Wert verwendet, um ein bestimmtes Dialogflow-Agent-Fehlerprotokoll mit den entsprechenden Webhook-Logeinträgen der Cloud Run-Funktionen zu verknüpfen. Im Beispiel werden Cloud Logging-Filter für einen Agenten verwendet, für den Cloud Logging aktiviert ist.
1. Dialogflow-Logs nach den Fehlerprotokollen eines bestimmten Kundenservicemitarbeiters filtern
Verwenden Sie den folgenden Cloud Logging-Filter, um Ihre Dialogflow-Logs nach den Fehlerprotokollen eines bestimmten Kundenservicemitarbeiters zu filtern:
labels.location_id="global"
labels.agent_id="AGENT_ID"
severity=ERROR
Ein Fehlereintrag im Webhook-Log sieht in etwa so aus:
{
"insertId": "-j4gkkre31e2o",
"jsonPayload": {
"code": 14,
"message": "Error calling webhook 'https://us-central1-PROJECT_ID.cloudfunctions.net/function-webhook': State: URL_UNREACHABLE, Reason: UNREACHABLE_5xx, HTTP status code: 500"
},
"labels": {
"agent_id": "e9e01392-1351-42dc-9b15-b583fb2d2881",
"environment_id": "",
"location_id": "global",
"session_id": "07c899-a86-78b-a77-569625b37"
},
"logName": "projects/PROJECT_ID/logs/dialogflow-runtime.googleapis.com%2Frequests",
"receiveTimestamp": "2024-10-28T21:49:04.288439054Z",
"resource": {
"labels": {
"project_id": "PROJECT_ID"
},
"type": "global",
},
"severity": "ERROR",
"timestamp": "2024-10-28T21:49:04.132548Z"
}
Beachten Sie das Feld labels.session_id
, das die Sitzungs-ID enthält.
Sie benötigen die Sitzungs-ID für den nächsten Schritt.
2. Cloud Run-Funktionslogs nach Sitzungs-ID filtern
Verwenden Sie den folgenden Cloud Logging-Filter, um Ihre Cloud Run-Funktionslogs nach Sitzungs-ID zu filtern:
resource.type = "cloud_run_revision"
resource.labels.service_name = "CLOUD_RUN_FUNCTION_NAME"
resource.labels.location = "CLOUD_RUN_FUNCTION_REGION"
textPayload="Debug Node: session ID = SESSION_ID"
Die resultierenden Logs entsprechen den Webhook-Logs, die während der angegebenen Sitzung erstellt wurden. Beispiel:
{
"insertId": "671c42940007ebebdbb1d56e",
"labels": {
"execution_id": "pgy8jvvblovs",
"goog-managed-by": "cloudfunctions",
"instance_id": "004940b3b8e3d975a4b11a4ed7d1ded4ce3ed37467ffc5e2a8f13a1908db928f8200b01cc554a5eda66ffc9d23d76dd75cec1619a07cb5751fa2e8a93bc6cfc3df86dfa0650a"
},
"logName": "projects/PROJECT_ID/logs/run.googleapis.com%2Fstdout",
"receiveTimestamp": "2024-10-26T01:15:00.523313187Z",
"resource": {
"labels": {
"configuration_name": "function-webhook",
"location": "us-central1",
"project_id": "PROJECT_ID",
"revision_name": "function-webhook-00001-jiv",
"service_name": "function-webhook",
},
"type": "cloud_run_revision"
},
"spanId": "6938366936362981595",
"trace": "d1b54fbc8945dd59bdcaed37d7d5e185",
"textPayload": "Debug Node: session ID = 07c899-a86-78b-a77-569625b37",
"timestamp": "2024-10-26T01:15:00.519147Z"
}
Notieren Sie sich das Feld trace
, das im nächsten Schritt verwendet wird.
3. Cloud Functions-Logs nach einem bestimmten Trace filtern
Verwenden Sie den folgenden Cloud Logging-Filter, um Cloud Function-Logs nach einer bestimmten Spur zu filtern:
resource.type = "cloud_run_revision"
resource.labels.service_name = "CLOUD_RUN_FUNCTION_NAME"
resource.labels.location = "CLOUD_RUN_FUNCTION_REGION"
trace="projects/PROJECT_ID/traces/TRACE_ID"
Dabei ist TRACE_ID
das letzte Segment des Symbols. Die TRACE_ID
für projects/PROJECT_ID/traces/e41eefc1fac48665b442bfa400cc2f5e
ist beispielsweise e41eefc1fac48665b442bfa400cc2f5e
.
Das Ergebnis ist das Webhook-Serverprotokoll, das während der Ausführung der Webhook-Anfrage generiert wurde und mit der Sitzungs-ID aus Schritt 1 und dem Trace aus Schritt 2 verknüpft ist. Das Protokoll würde dann so aussehen:
{
"insertId": "671c42940008465e29f5faf0",
"httpRequest": {
"requestMethod": "POST",
"requestUrl": "https://us-central1-TEST_PROJECT.cloudfunctions.net/function-webhook",
"requestSize": "2410",
"status": 200,
"responseSize": "263",
"userAgent": "Google-Dialogflow",
"remoteIp": "8.34.210.1",
"serverIp": "216.239.36.1",
"latency": "0.166482342s",
"protocol": "HTTP/1.1"
},
"resource": {
"type": "cloud_run_revision",
"labels": {
"project_id": "PROJECT_ID",
"service_name": "function-webhook",
"location": "us-central1",
"revision_name": "function-webhook-00001-jiv",
"configuration_name": "function-webhook"
}
},
"timestamp": "2024-10-26T01:15:00.352197Z",
"severity": "INFO",
"labels": {
"instanceId": "004940b3b813af8a656c92aac1bd07ffad5165f1353e1e346b6161c14bcde225f68f4a88ceedc08aa9020f387b1b59471f73de45f2882a710ced37dea921f05ad962347690be",
"goog-managed-by": "cloudfunctions"
},
"logName": "projects/test-project-12837/logs/run.googleapis.com%2Frequests",
"trace": "projects/test-project-12837/traces/d1b54fbc8945dd59bdcaed37d7d5e185",
"receiveTimestamp": "2024-10-26T01:15:00.548931586Z",
"spanId": "604a07f7b33b18db",
"traceSampled": true
}