Este guia fornece vários exemplos para implementar webhooks bem como recomendações de solução de problemas de webhook.
Definir um parâmetro de sessão
Os exemplos a seguir mostram como definir um parâmetro de sessão.
Go
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Consulte o Guia de início rápido de webhooks.Java
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Retornar uma resposta de fulfillment
Os exemplos a seguir mostram como retornar uma resposta de fulfillment.
Go
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Consulte o Guia de início rápido de webhooks.Java
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Definir parâmetros de formulário conforme necessário
Os exemplos a seguir mostram como marcar um parâmetro como obrigatório.
Java
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Validar um parâmetro de formulário
Os exemplos a seguir mostram como validar um parâmetro de formulário.
Java
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Registrar o ID da sessão
O exemplo a seguir mostra como registrar o session ID
de uma solicitação de webhook.
Python
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Solução de problemas
Ciclo de vida de uma chamada de webhook
As chamadas de webhook são sempre iniciadas pelo Dialogflow CX e vão para um servidor da Web via HTTPS. As chamadas de webhook de serviço da Web genérico se originam de um endereço IP da Internet que pertence ao Google e podem alcançar servidores da Web (servidores de webhook) disponíveis na Internet pública. Por outro lado, os webhooks do Diretório de serviços sempre começam em um endereço Google Cloud interno e só podem alcançar servidores de webhook em redes particulares dentro Google Cloud.
Registros úteis para depurar webhooks
A depuração de problemas de webhook geralmente envolve a coleta dos registros do Cloud Logging Dialogflow CX e dos registros do servidor de webhook. Se o servidor de webhook for implementado usando o Cloud Run functions, os registros estarão no Cloud Logging. Caso contrário, os registros normalmente residem onde o servidor de webhook é executado.
Os registros de webhook padrão contêm um campo detectIntentResponseId com um UUID que pode ser útil para rastrear uma chamada específica em servidores de webhook. Esse registro existe nos registros do Cloud Logging do Dialogflow CX quando o Cloud Logging está ativado.
Problemas comuns de webhook
Alguns erros que podem ser encontrados nos registros do Dialogflow CX para chamadas de webhook são:
Erro de resolução de nome do host do servidor de webhook
O Dialogflow CX pesquisou o nome do host de um webhook genérico, mas ele não existe no DNS. Verifique se o nome do host está registrado no DNS público. Se o nome do host for novo, pode levar algum tempo para que o registro seja propagado. Mensagem do Cloud Logging: State: URL_ERROR, Reason: ERROR_DNS.
O servidor de webhook retorna um erro do lado do cliente
Além de ERROR_DNS, esse estado indica uma resposta 4xx do servidor de webhook. Isso pode ser um status não autorizado (401 - ERROR_AUTHENTICATION) ou que o URL não foi encontrado no servidor de webhook (404 - ERROR_NOT_FOUND). Mensagem do Cloud Logging: State: URL_ERROR.
O agente do Dialogflow atinge o tempo limite antes que o servidor de webhook retorne uma resposta
O Dialogflow CX atingiu o limite de tempo limite do webhook antes que o servidor da Web terminasse. As duas abordagens possíveis aqui são reduzir o tempo de processamento do servidor de webhook ou aumentar o tempo que o Dialogflow CX espera pelo webhook. A redução do tempo de processamento geralmente traz os melhores resultados, embora não seja trivial em muitos casos. Considere que há um limite máximo de tempo limite para webhooks e que os autores de chamadas ou usuários finais precisam esperar mais tempo para receber uma resposta do agente antes de aumentar essa configuração. Mensagem do Cloud Logging: State: URL_TIMEOUT, Reason: TIMEOUT_WEB.
O gRPC atinge o tempo limite antes que o servidor de webhook retorne uma resposta
O limite de tempo definido pelo gRPC na chamada de API do Dialogflow CX foi atingido antes que a chamada de webhook terminasse. Esse limite é definido geralmente no nível de integração e é independente dos parâmetros do Dialogflow CX e dos limites de tempo limite do webhook. Para mais informações sobre prazos do gRPC, consulte
https://grpc.io/docs/guides/deadlines/.
Mensagem do Cloud Logging: State: URL_REJECTED, Reason: REJECTED_DEADLINE_EXCEEDED.
O Dialogflow não conseguiu entrar em contato com o servidor de webhook
Não foi possível acessar o servidor de webhook devido a um erro de rede ou a conexão foi estabelecida e o servidor de webhook retornou o status HTTP 5xx, indicando um problema durante o processamento da solicitação. Verifique se o Dialogflow CX pode acessar o endereço do servidor de webhook no nível de rede. Se a solicitação aparecer nos registros do servidor de webhook, descubra por que a chamada retornou um erro 5xx. Mensagem do Cloud Logging:
State: URL_UNREACHABLE.
Como rastrear chamadas de webhook
Uma chamada de webhook padrão pode ser correlacionada entre o Dialogflow CX e um servidor de webhook usando o ID da sessão, o ID detectIntentResponse, o ID de rastreamento do Cloud Run functions e um carimbo de data/hora da chamada. O rastreamento flexível de webhook pode ser feito usando o carimbo de data/hora da chamada e os valores de parâmetro de sessão especificados na definição de webhook no momento do design. Para mais informações
sobre solicitações de webhook padrão e flexíveis, consulte
Webhooks.
O ID da sessão aparece no campo sessionInfo.session do
WebhookRequest.
Esse ID de sessão precisa ser exclusivo para cada conversa e pode ajudar a comparar registros de agentes com registros de webhook para solicitações que usam o mesmo ID de sessão.
A seção anterior Registrar o ID da sessão
mostra como registrar o ID da sessão de um webhook.
Além disso, se você estiver hospedando o webhook no
Cloud Run functions
ou em uma opção sem servidor Google Cloud semelhante,
poderá usar o trace campo das
entradas de registro
como um filtro de registro.
Uma única execução de uma função resulta em várias entradas de registro com o mesmo valor de rastreamento.
O exemplo a seguir usa o ID da sessão e o valor de rastreamento para associar um registro de erros de agente do Dialogflow CX específico às entradas de registro de webhook do Cloud Run functions correspondentes. O exemplo usa filtros do Cloud Logging para um agente que ativou o Cloud Logging.
1. Filtrar registros do Dialogflow CX para registros de erros de um agente específico
Use o seguinte filtro do Cloud Logging para filtrar os registros do Dialogflow CX para registros de erros de um agente específico:
labels.location_id="global"
labels.agent_id="AGENT_ID"
severity=ERROR
Uma entrada de erro de registro de webhook é semelhante a esta:
{
"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"
}
Observe o campo labels.session_id, que contém o ID da sessão.
Você vai usar o ID da sessão na próxima etapa.
2. Filtrar registros do Cloud Run functions por ID da sessão
Use o seguinte filtro do Cloud Logging para filtrar os registros do Cloud Run functions por ID da sessão:
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"
Os registros resultantes correspondem aos registros de webhook feitos durante a sessão fornecida. Exemplo:
{
"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"
}
Observe o campo trace, que é usado na próxima etapa.
3. Filtrar registros do Cloud Functions para um rastreamento específico
Use o seguinte filtro do Cloud Logging para filtrar os registros do função do Cloud para um rastreamento específico:
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"
em que TRACE_ID é o último segmento do rastreamento. Por exemplo, o TRACE_ID
de projects/PROJECT_ID/traces/e41eefc1fac48665b442bfa400cc2f5e é
e41eefc1fac48665b442bfa400cc2f5e.
O resultado é o registro do servidor de webhook gerado durante a execução da solicitação de webhook associada ao ID da sessão da etapa 1 e ao rastreamento da etapa 2. O registro seria semelhante a este.
{
"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
}