En esta guía, se proporcionan varias muestras para implementar webhooks así como recomendaciones para solucionar problemas relacionados con ellos.
Establece un parámetro de sesión
En los siguientes ejemplos, se muestra cómo establecer un parámetro de sesión.
Go
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Consulta el inicio rápido de Webhooks.Java
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Muestra una respuesta de entrega
En los siguientes ejemplos, se muestra cómo mostrar una respuesta de entrega.
Go
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Consulta el inicio rápido de Webhooks.Java
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Establece los parámetros del formulario según sea necesario
En los siguientes ejemplos, se muestra cómo marcar un parámetro como obligatorio.
Java
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Valida un parámetro de formulario
En los siguientes ejemplos, se muestra cómo validar un parámetro de formulario.
Java
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Registra el ID de sesión
En el siguiente ejemplo, se muestra cómo registrar el session ID
de una solicitud de webhook.
Python
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Soluciona problemas
Ciclo de vida de una llamada de webhook
Dialogflow CX siempre inicia las llamadas de webhook y se dirigen a un servidor web a través de HTTPS. Las llamadas de webhook de servicio web genérico se originan en una dirección IP de Internet que pertenece a Google y pueden llegar a servidores web (servidores de webhook) que están disponibles en Internet pública. Por otro lado, los webhooks del Directorio de servicios siempre comienzan desde una dirección interna Google Cloud y solo pueden llegar a servidores de webhook en redes privadas dentro de ella Google Cloud.
Registros útiles para depurar webhooks
Por lo general, la depuración de problemas de webhook implica recopilar los registros de Cloud Logging Dialogflow CX y los registros del servidor de webhook. Si el servidor de webhook se implementa con funciones de Cloud Run, sus registros estarán en Cloud Logging. De lo contrario, los registros suelen residir donde se ejecuta el servidor de webhook.
Los registros de webhook estándar contienen un campo detectIntentResponseId con un UUID que puede ser útil para rastrear una llamada en particular en servidores de webhook. Este registro existe en los registros de Cloud Logging de Dialogflow CX cuando Cloud Logging está habilitado.
Problemas comunes con webhook
Algunos errores que se pueden encontrar en los registros de Dialogflow CX para llamadas de webhook son los siguientes:
Error de resolución del nombre de host del servidor de webhook
Dialogflow CX buscó el nombre de host de un webhook genérico y el nombre de host no existe en el DNS. Asegúrate de que el nombre de host esté registrado en el DNS público. Si el nombre de host es nuevo, es posible que el registro tarde un tiempo en propagarse. Mensaje de Cloud Logging: State: URL_ERROR, Reason: ERROR_DNS.
El servidor de webhook muestra un error del cliente
Además de ERROR_DNS, este estado indica una respuesta 4xx del servidor de webhook. Puede ser un estado no autorizado (401 - ERROR_AUTHENTICATION) o que no se encontró la URL en el servidor de webhook (404 - ERROR_NOT_FOUND). Mensaje de Cloud Logging: State: URL_ERROR.
El agente de Dialogflow agota el tiempo de espera antes de que el servidor de webhook muestre una respuesta
Dialogflow CX alcanzó el límite de tiempo de espera del webhook antes de que finalizara el servidor web. Los dos enfoques posibles aquí son reducir el tiempo de procesamiento del servidor de webhook o aumentar el tiempo que Dialogflow CX espera el webhook. Por lo general, reducir el tiempo de procesamiento produce mejores resultados, aunque no es trivial en muchos casos. Ten en cuenta que hay un límite máximo de tiempo de espera para los webhooks y que los usuarios o quienes llaman finales deberán esperar más tiempo para obtener una respuesta del agente antes de aumentar esta configuración. Mensaje de Cloud Logging: State: URL_TIMEOUT, Reason: TIMEOUT_WEB.
gRPC agota el tiempo de espera antes de que el servidor de webhook muestre una respuesta
Se alcanzó el límite de tiempo establecido por gRPC en la llamada a la API de Dialogflow CX antes de que finalizara la llamada de webhook. Por lo general, este límite se establece en el nivel de integración y es independiente de los parámetros de Dialogflow CX y los límites de tiempo de espera del webhook. Para obtener más información sobre los plazos de gRPC, consulta
https://grpc.io/docs/guides/deadlines/.
Mensaje de Cloud Logging: State: URL_REJECTED, Reason: REJECTED_DEADLINE_EXCEEDED.
Dialogflow no pudo comunicarse con el servidor de webhook
No se pudo acceder al servidor de webhook debido a un error de red, o bien se estableció la conexión y el servidor de webhook mostró el estado HTTP 5xx, lo que indica un problema mientras procesaba la solicitud. Asegúrate de que Dialogflow CX pueda llegar a la dirección del servidor de webhook en el nivel de red. Si la solicitud aparece en los registros del servidor de webhook, averigua por qué la llamada mostró un error 5xx. Mensaje de Cloud Logging:
State: URL_UNREACHABLE.
Cómo rastrear llamadas de webhook
Se puede correlacionar una llamada de webhook estándar entre Dialogflow CX y un servidor de webhook con el ID de sesión, el ID de detectIntentResponse, el ID de seguimiento de las funciones de Cloud Run y una marca de tiempo de la llamada. El seguimiento flexible de webhook se puede realizar con la marca de tiempo de la llamada y los valores de los parámetros de sesión especificados en la definición de webhook en el momento del diseño. Para obtener más información
sobre las solicitudes de webhook estándar y flexibles, consulta
Webhooks.
El ID de sesión aparece en el campo sessionInfo.session de
WebhookRequest.
Este ID de sesión debe ser único para cada conversación y puede ayudarte a comparar los registros del agente con los registros de webhook para las solicitudes que usan el mismo ID de sesión.
En la sección anterior, Registra el ID de sesión,
se muestra cómo registrar el ID de sesión de un webhook.
Además, si alojas tu webhook en
funciones de Cloud Run
o en una opción similar Google Cloud sin servidores,
puedes usar el campo trace de las
entradas de registro
como filtro de registro.
Una sola ejecución de una función genera varias entradas de registro con el mismo valor de seguimiento.
En el siguiente ejemplo, se usan el ID de sesión y el valor de seguimiento para asociar un registro de errores de agente de Dialogflow CX en particular con las entradas de registro de webhook de funciones de Cloud Run correspondientes. En el ejemplo, se usan filtros de Cloud Logging para un agente que habilitó Cloud Logging.
1. Filtra los registros de Dialogflow CX para los registros de errores de un agente en particular
Usa el siguiente filtro de Cloud Logging para filtrar los registros de Dialogflow CX para los registros de errores de un agente en particular:
labels.location_id="global"
labels.agent_id="AGENT_ID"
severity=ERROR
Una entrada de error de registro de webhook se ve de la siguiente manera:
{
"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"
}
Observa el campo labels.session_id, que contiene el ID de sesión.
Usarás el ID de sesión en el siguiente paso.
2. Filtra los registros de funciones de Cloud Run por ID de sesión
Usa el siguiente filtro de Cloud Logging para filtrar los registros de funciones de Cloud Run por ID de sesión:
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"
Los registros resultantes corresponden a los registros de webhook realizados durante la sesión proporcionada. Por ejemplo:
{
"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"
}
Observa el campo trace, que se usa en el siguiente paso.
3. Filtra los registros de Cloud Functions para un seguimiento en particular
Usa el siguiente filtro de Cloud Logging para filtrar los registros de Cloud Function para un seguimiento en particular:
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"
donde TRACE_ID es el último segmento del seguimiento. Por ejemplo, el TRACE_ID
para projects/PROJECT_ID/traces/e41eefc1fac48665b442bfa400cc2f5e es
e41eefc1fac48665b442bfa400cc2f5e.
El resultado es el registro del servidor de webhook generado durante la ejecución de la solicitud de webhook asociada con el ID de sesión del paso 1 y con el seguimiento del paso 2. El registro se vería de la siguiente manera.
{
"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
}