Ce guide fournit différents exemples d'implémentation de webhooks , ainsi que des recommandations de dépannage.
Définir un paramètre de session
Les exemples suivants montrent comment définir un paramètre de session.
Go
Pour vous authentifier auprès de Dialogflow CX, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Consultez le guide de démarrage rapide sur les webhooks.Java
Pour vous authentifier auprès de Dialogflow CX, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Pour vous authentifier auprès de Dialogflow CX, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Pour vous authentifier auprès de Dialogflow CX, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Renvoyer une réponse de fulfillment
Les exemples suivants montrent comment renvoyer une réponse de fulfillment.
Go
Pour vous authentifier auprès de Dialogflow CX, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Consultez le guide de démarrage rapide sur les webhooks.Java
Pour vous authentifier auprès de Dialogflow CX, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Pour vous authentifier auprès de Dialogflow CX, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Pour vous authentifier auprès de Dialogflow CX, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Définir des paramètres de formulaire si nécessaire
Les exemples suivants montrent comment marquer un paramètre comme obligatoire.
Java
Pour vous authentifier auprès de Dialogflow CX, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Pour vous authentifier auprès de Dialogflow CX, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Valider un paramètre de formulaire
Les exemples suivants montrent comment valider un paramètre de formulaire.
Java
Pour vous authentifier auprès de Dialogflow CX, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Pour vous authentifier auprès de Dialogflow CX, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Pour vous authentifier auprès de Dialogflow CX, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Enregistrer l'ID de session
L'exemple suivant montre comment enregistrer le session ID
à partir d'une requête de webhook.
Python
Pour vous authentifier auprès de Dialogflow CX, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Dépannage
Durée de vie d'un appel de webhook
Les appels de webhook sont toujours initiés par Dialogflow CX et sont envoyés à un serveur Web via HTTPS. Les appels de webhook de service Web génériques proviennent d'une adresse IP Internet appartenant à Google et peuvent atteindre des serveurs Web (serveurs de webhook) disponibles sur l'Internet public. En revanche, les webhooks de l'Annuaire des services commencent toujours à partir d'une adresse interne Google Cloud et ne peuvent atteindre que les serveurs de webhook dans les réseaux privés internes Google Cloud.
Journaux utiles pour le débogage des webhooks
Le débogage des problèmes de webhook implique généralement la collecte des journaux Cloud Logging Dialogflow CX et des journaux du serveur de webhook. Si le serveur de webhook est implémenté à l'aide de Cloud Run Functions, ses journaux se trouvent dans Cloud Logging. Sinon, les journaux se trouvent généralement à l'endroit où le serveur de webhook s'exécute.
Les journaux de webhook standards contiennent un champ detectIntentResponseId avec un UUID qui peut être utile pour suivre un appel particulier dans les serveurs de webhook. Ce journal existe dans les journaux Cloud Logging Dialogflow CX lorsque Cloud Logging est activé.
Problèmes courants liés aux webhooks
Voici quelques erreurs qui peuvent être trouvées dans les journaux Dialogflow CX pour les appels de webhook :
Erreur de résolution du nom d'hôte du serveur de webhook
Dialogflow CX a recherché le nom d'hôte d'un webhook générique, mais il n'existe pas dans le DNS. Assurez-vous que le nom d'hôte est enregistré dans le DNS public. Si le nom d'hôte est nouveau, la propagation de l'enregistrement peut prendre un certain temps. Message Cloud Logging : State: URL_ERROR, Reason: ERROR_DNS.
Le serveur de webhook renvoie une erreur côté client
Outre ERROR_DNS, cet état indique une réponse 4xx du serveur de webhook. Il peut s'agir d'un état non autorisé (401 - ERROR_AUTHENTICATION) ou que l'URL n'a pas été trouvée dans le serveur de webhook (404 - ERROR_NOT_FOUND). Message Cloud Logging : State: URL_ERROR.
L'agent Dialogflow expire avant que le serveur de webhook ne renvoie une réponse
Dialogflow CX a atteint la limite de délai avant expiration du webhook avant que le serveur Web ne se termine. Les deux approches possibles sont de réduire le temps de traitement du serveur de webhook ou d'augmenter le temps d'attente de Dialogflow CX pour le webhook. La réduction du temps de traitement donne généralement les meilleurs résultats, bien que cela ne soit pas trivial dans de nombreux cas. Tenez compte du délai avant expiration maximal pour les webhooks et du fait que les appelants ou utilisateurs finaux devront attendre plus longtemps pour obtenir une réponse de l'agent avant d'augmenter ce paramètre. Message Cloud Logging : State: URL_TIMEOUT, Reason: TIMEOUT_WEB.
gRPC expire avant que le serveur de webhook ne renvoie une réponse
La limite de temps définie par gRPC dans l'appel d'API Dialogflow CX a été atteinte avant la fin de l'appel de webhook. Cette limite est généralement définie au niveau de l'intégration et est indépendante des paramètres Dialogflow CX et des limites de délai avant expiration du webhook. Pour en savoir plus sur les délais gRPC, consultez
https://grpc.io/docs/guides/deadlines/.
Message Cloud Logging : State: URL_REJECTED, Reason: REJECTED_DEADLINE_EXCEEDED.
Dialogflow n'a pas pu contacter le serveur de webhook
Le serveur de webhook n'a pas pu être atteint en raison d'une erreur réseau, ou la connexion a été établie et le serveur de webhook a renvoyé l'état HTTP 5xx, indiquant un problème lors du traitement de la requête. Assurez-vous que Dialogflow CX peut atteindre l'adresse du serveur de webhook au niveau du réseau. Si la requête apparaît dans les journaux du serveur de webhook, découvrez pourquoi l'appel a renvoyé une erreur 5xx. Message Cloud Logging :
State: URL_UNREACHABLE.
Suivi des appels de webhook
Un appel de webhook standard peut être corrélé entre Dialogflow CX et un serveur de webhook à l'aide de l'ID de session, de l'ID detectIntentResponse, de l'ID de trace pour Cloud Run Functions et d'un code temporel de l'appel. Le suivi flexible des webhooks peut être effectué à l'aide du code temporel de l'appel et des valeurs des paramètres de session spécifiées dans la définition du webhook au moment de la conception. Pour en savoir plus
sur les requêtes de webhook standards et flexibles, consultez
Webhooks.
L'ID de session apparaît dans le champ sessionInfo.session de
WebhookRequest.
Cet ID de session doit être unique pour chaque conversation. Il peut vous aider à comparer les journaux de l'agent aux journaux de webhook pour les requêtes utilisant le même ID de session.
La section précédente Enregistrer l'ID de session
montre comment enregistrer l'ID de session à partir d'un webhook.
De plus, si vous hébergez votre webhook sur
Cloud Run Functions
ou une option sans serveur Google Cloud similaire,
vous pouvez utiliser le champ trace des
entrées de journal
comme filtre de journal.
Une seule exécution d'une fonction génère plusieurs entrées de journal avec la même valeur de trace.
L'exemple suivant utilise à la fois l'ID de session et la valeur de trace pour associer un journal d'erreurs d'agent Dialogflow CX particulier aux entrées de journal de webhook Cloud Run Functions correspondantes. L'exemple utilise des filtres Cloud Logging pour un agent pour lequel Cloud Loggingest activé.
1. Filtrer les journaux Dialogflow CX pour les journaux d'erreurs d'un agent particulier
Utilisez le filtre Cloud Logging suivant pour filtrer vos journaux Dialogflow CX pour les journaux d'erreurs d'un agent particulier :
labels.location_id="global"
labels.agent_id="AGENT_ID"
severity=ERROR
Une entrée d'erreur de journal de webhook se présente comme suit :
{
"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"
}
Notez le champ labels.session_id qui contient l'ID de session.
Vous utiliserez l'ID de session à l'étape suivante.
2. Filtrer les journaux Cloud Run Functions par ID de session
Utilisez le filtre Cloud Logging suivant pour filtrer vos journaux Cloud Run Functions par ID de session :
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"
Les journaux obtenus correspondent aux journaux de webhook créés lors de la session fournie . Exemple :
{
"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"
}
Notez le champ trace qui sera utilisé à l'étape suivante.
3. Filtrer les journaux Cloud Functions pour une trace particulière
Utilisez le filtre Cloud Logging suivant pour filtrer les journaux Cloud Functions pour une trace particulière :
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"
où TRACE_ID est le dernier segment de la trace. Par exemple, le TRACE_ID
de projects/PROJECT_ID/traces/e41eefc1fac48665b442bfa400cc2f5e est
e41eefc1fac48665b442bfa400cc2f5e.
Le résultat est le journal du serveur de webhook généré lors de l'exécution de la requête de webhook associée à l'ID de session de l'étape 1 et à la trace de l'étape 2. Le journal se présente comme suit.
{
"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
}