En esta guía, se proporcionan varios ejemplos para implementar webhooks, así como recomendaciones para solucionar problemas relacionados con ellos.
Cómo establecer 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, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para 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. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Devuelve 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. Si deseas obtener más información, consulta Configura la autenticación para 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. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Si deseas 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, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Si deseas 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, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para 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. Si deseas 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
Las llamadas de webhook siempre las inician los agentes conversacionales (Dialogflow CX) y se dirigen a un servidor web a través de HTTPS. Las llamadas de webhook de servicios web genéricos se originan desde una dirección IP de Internet que pertenece a Google y pueden llegar a servidores web (servidores de webhook) que están disponibles en la Internet pública. Por otro lado, los webhooks de Directorio de servicios siempre comienzan desde una direcciónGoogle Cloud interna y solo pueden llegar a los servidores de webhook en redes privadas dentro de Google Cloud.
Registros útiles para depurar webhooks
Por lo general, la depuración de problemas de webhook implica recopilar los registros de Cloud Logging de Dialogflow y los registros del servidor de webhook. Si el servidor de webhook se implementa con Cloud Run Functions, sus registros se encontrarán en Cloud Logging. De lo contrario, los registros suelen residir donde se ejecuta el servidor de webhook.
Los registros estándar de webhook contienen un campo detectIntentResponseId
con un UUID que puede ser útil para rastrear una llamada en particular en los servidores de webhook. Este registro existe en los registros de Cloud Logging de Dialogflow cuando Cloud Logging está habilitado.
Problemas comunes con los webhooks
Estos son algunos errores que se pueden encontrar en los registros de Dialogflow para las llamadas a webhooks:
Error de resolución del nombre de host del servidor de webhook
Dialogflow buscó el nombre de host de un webhook genérico, pero este 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 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 espera el webhook. Reducir el tiempo de procesamiento suele brindar los mejores resultados, aunque no es trivial en muchos casos. Ten en cuenta que hay un límite de tiempo de espera máximo para los webhooks y que los usuarios o quienes llaman al final deberán esperar más tiempo para obtener una respuesta del agente antes de aumentar este parámetro de configuración. Mensaje de Cloud Logging: State: URL_TIMEOUT, Reason: TIMEOUT_WEB
.
Se agota el tiempo de espera de gRPC antes de que el servidor de webhook devuelva una respuesta
Se alcanzó el límite de tiempo establecido por gRPC en la llamada a la API de Dialogflow antes de que finalizara la llamada al webhook. Este límite se establece, por lo general, a nivel de la integración y es independiente de los parámetros de Dialogflow 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 devolvió el estado HTTP 5xx, lo que indica un problema mientras procesaba la solicitud. Asegúrate de que Dialogflow pueda acceder a la dirección del servidor de webhook a nivel de la red. Si la solicitud aparece en los registros del servidor de webhook, busca por qué la llamada devolvió un error 5xx. Mensaje de Cloud Logging:
State: URL_UNREACHABLE
.
Cómo hacer un seguimiento de las llamadas de webhook
Una llamada de webhook estándar se puede correlacionar entre Dialogflow y un servidor de webhook con el ID de sesión, el ID de detectIntentResponse
, el ID de seguimiento para Cloud Run Functions y una marca de tiempo de la llamada. El seguimiento flexible de webhooks 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 del 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 del webhook para las solicitudes que usan el mismo ID de sesión.
En la sección anterior, ID de sesión de registro, se muestra cómo registrar el ID de sesión desde un webhook.
Además, si alojas tu webhook en Cloud Run Functions o en una opción sin servidores Google Cloud similar, 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 error de un agente de Dialogflow en particular 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 tiene habilitado Cloud Logging.
1. Cómo filtrar los registros de Dialogflow para ver los registros de errores de un agente en particular
Usa el siguiente filtro de Cloud Logging para filtrar los registros de errores de un agente en particular de Dialogflow:
labels.location_id="global"
labels.agent_id="AGENT_ID"
severity=ERROR
Una entrada de error del 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 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"
}
Toma nota del campo trace
, que se usa en el siguiente paso.
3. Cómo filtrar los registros de Cloud Functions para un seguimiento en particular
Usa el siguiente filtro de Cloud Logging para filtrar los registros de Cloud Function de 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 registro. 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 al ID de sesión del paso 1 y al registro 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
}