En esta guía se proporcionan varias muestras para implementar webhooks, así como recomendaciones para solucionar problemas relacionados con ellos.
Definir un parámetro de sesión
En los siguientes ejemplos se muestra cómo definir un parámetro de sesión.
Go
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Consulta la guía de inicio rápido de webhooks.Java
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Python
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Devolver una respuesta de cumplimiento
En los siguientes ejemplos se muestra cómo devolver una respuesta de cumplimiento.
Go
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Consulta la guía de inicio rápido de webhooks.Java
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Python
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Definir 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, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Validar un parámetro de formulario
En los siguientes ejemplos se muestra cómo validar un parámetro de formulario.
Java
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Python
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
ID de sesión de registro
En el siguiente ejemplo se muestra cómo registrar el session ID
de una solicitud de webhook.
Python
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Solución de problemas
Ciclo de vida de una llamada de webhook
Las llamadas a webhooks siempre las inician los agentes conversacionales (Dialogflow CX) y se dirigen a un servidor web a través de HTTPS. Las llamadas de webhooks de servicios web genéricos proceden de una dirección IP de Internet que pertenece a Google y pueden llegar a servidores web (servidores de webhooks) que están disponibles en Internet público. Por otro lado, los webhooks de Service Directory siempre empiezan desde una dirección internaGoogle Cloud y solo pueden llegar a servidores de webhook en redes privadas Google Cloud.
Registros útiles para depurar webhooks
Para depurar problemas de webhooks, normalmente se recogen los registros de Cloud Logging y los registros del servidor de webhook. Si el servidor de webhook se implementa con funciones de Cloud Run, sus registros se encontrarán en Cloud Logging. De lo contrario, los registros se suelen encontrar en el lugar donde se ejecuta el servidor webhook.
Los registros de webhook estándar contienen un campo detectIntentResponseId
con un UUID que puede ser útil para rastrear una llamada concreta en servidores de webhook. Este registro se encuentra en los registros de Cloud Logging de Dialogflow cuando Cloud Logging está habilitado.
Problemas habituales de webhook
Estos son algunos de los errores que se pueden encontrar en los registros de Dialogflow de las llamadas a webhooks:
Error de resolución del nombre de host del servidor de webhook
Dialogflow ha buscado el nombre de host de un webhook genérico y 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 devuelve un error del lado del cliente
Aparte de ERROR_DNS
, este estado indica una respuesta 4xx del servidor webhook. Puede tratarse de un estado no autorizado (401 - ERROR_AUTHENTICATION
)
o de que no se haya encontrado la URL en el servidor 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 webhook devuelva una respuesta
Dialogflow ha alcanzado el límite de tiempo de espera del webhook antes de que terminara el servidor web. Las dos opciones posibles son reducir el tiempo de procesamiento del servidor webhook o aumentar el tiempo que espera Dialogflow al webhook. Reducir el tiempo de procesamiento suele dar los mejores resultados, aunque en muchos casos no es trivial. Ten en cuenta que hay un límite de tiempo de espera máximo para los webhooks y que los usuarios finales tendrían que esperar más tiempo para obtener una respuesta del agente antes de aumentar este ajuste. Mensaje de Cloud Logging: State: URL_TIMEOUT, Reason: TIMEOUT_WEB
.
Se agota el tiempo de espera de gRPC antes de que el servidor webhook devuelva una respuesta
Se ha alcanzado el límite de tiempo establecido por gRPC en la llamada a la API Dialogflow
antes de que finalizara la llamada al webhook. Este límite se suele definir a nivel de integración y es independiente de los parámetros de Dialogflow y de los límites de tiempo de espera de 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 ha podido ponerse en contacto con el servidor webhook
No se ha podido acceder al servidor webhook debido a un error de red o se ha establecido la conexión, pero el servidor webhook ha devuelto el estado HTTP 5xx, lo que indica que ha habido un problema al procesar la solicitud. Asegúrate de que Dialogflow puede acceder a la dirección del servidor webhook
a nivel de red. Si la solicitud aparece en los registros del servidor webhook, averigua por qué la llamada ha devuelto un error 5xx. Mensaje de Cloud Logging:
State: URL_UNREACHABLE
.
Seguimiento de llamadas de webhook
Una llamada de webhook estándar se puede correlacionar entre Dialogflow y un servidor de webhook mediante el ID de sesión, el ID detectIntentResponse
, el ID de seguimiento de las funciones de Cloud Run y una marca de tiempo de la llamada. El seguimiento flexible de webhooks se puede hacer usando la marca de tiempo de la llamada y los valores del parámetro de sesión especificados en la definición del webhook en tiempo de diseño. Para obtener más información sobre las solicitudes de webhooks 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 de agentes con los registros de webhooks de las solicitudes que usen el mismo ID de sesión.
En la sección anterior ID de sesión de registro se explica cómo registrar el ID de sesión de un webhook.
Además, si alojas tu webhook en Cloud Run functions o en una opción sin servidor similar, puedes usar el campo trace
de las entradas de registro como filtro de registro. Google Cloud
Una sola ejecución de una función da como resultado varias entradas de registro con el mismo valor de seguimiento.
En el siguiente ejemplo, se usan tanto el ID de sesión como el valor de la traza para asociar un registro de errores de un agente de Dialogflow concreto con las entradas de registro del webhook de las funciones de Cloud Run correspondientes. En el ejemplo se usan filtros de Cloud Logging para un agente que ha habilitado Cloud Logging.
1. Filtrar los registros de Dialogflow para ver los registros de errores de un agente concreto
Utiliza el siguiente filtro de Cloud Logging para filtrar los registros de errores de un agente concreto de Dialogflow:
labels.location_id="global"
labels.agent_id="AGENT_ID"
severity=ERROR
Una entrada de error de registro de webhook tiene el siguiente aspecto:
{
"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"
}
Anote el campo labels.session_id
, que contiene el ID de sesión.
Usará el ID de sesión en el siguiente paso.
2. Filtrar los registros de Cloud Run Functions por ID de sesión
Usa el siguiente filtro de Cloud Logging para filtrar los registros de tus 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"
}
Anote el campo trace
, que se usa en el siguiente paso.
3. Filtrar los registros de Cloud Functions de un rastreo concreto
Usa el siguiente filtro de Cloud Logging para filtrar los registros de Cloud Functions de un determinado rastreo:
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 rastro. Por ejemplo, el TRACE_ID
de projects/PROJECT_ID/traces/e41eefc1fac48665b442bfa400cc2f5e
es e41eefc1fac48665b442bfa400cc2f5e
.
El resultado es el registro del servidor webhook generado durante la ejecución de la solicitud webhook asociada al ID de sesión del paso 1 y a la traza del paso 2. El registro tendría este aspecto:
{
"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
}