Este guia fornece várias amostras para implementar webhooks e recomendações para solucionar problemas relacionados a eles.
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. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Consulte o guia de início rápido dos webhooks.Java
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Para 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. Para 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. Para 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 atendimento.
Go
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Consulte o guia de início rápido dos webhooks.Java
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Para 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. Para 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. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Defina os parâmetros de formulário conforme necessário
Os exemplos a seguir mostram como sinalizar um parâmetro como obrigatório.
Java
Para autenticar no Dialogflow CX, configure o Application Default Credentials. Para 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. Para 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. Para 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. Para 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. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
ID da sessão de registro
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. Para 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 por HTTPS. As chamadas de webhook de serviço da Web genérico têm origem em um endereço IP da Internet pertencente 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 com um endereço Google Cloud interno e só podem alcançar servidores de webhook em redes particulares dentro de Google Cloud.
Registros úteis para depurar webhooks
Para depurar problemas de webhook, geralmente é necessário coletar os registros do Cloud Logging do Dialogflow CX e os registros do servidor de webhook. Se o servidor de webhook for implementado usando funções do Cloud Run, os registros dele estarão no Cloud Logging. Caso contrário, os registros normalmente ficariam onde o servidor webhook é executado.
Os registros padrão de webhook 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 do nome do host do servidor de webhook
O Dialogflow CX pesquisou o nome de host de um webhook genérico, e ele não existe no DNS. Confirme se o nome do host está registrado no DNS público. Se o nome do host for novo, a propagação do
registro poderá levar algum tempo. 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
webhook. Isso pode ser um status não autorizado (401 - ERROR_AUTHENTICATION) ou 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 da conclusão do servidor da Web. 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. Reduzir o 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 usuários ou chamadores 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 expira antes que o servidor de webhook retorne uma resposta
O limite de tempo definido pelo gRPC na chamada da API Dialogflow CX foi atingido antes da conclusão da chamada de webhook. Esse limite geralmente é definido no nível da 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 porque 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 webhook
no nível da 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 do detectIntentResponse, o ID do rastreamento
para funções do Cloud Run 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 do 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 você a comparar registros do agente com registros do webhook
para solicitações que usam o mesmo ID de sessão.
A seção anterior ID da sessão de registro mostra como registrar o ID de sessão de um webhook.
Além disso, se você estiver hospedando seu webhook no
Cloud Run functions
ou em uma opção Google Cloud sem servidor semelhante,
use o campo trace das
entradas de registro
como um filtro de registros.
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 determinado registro de erros do agente do Dialogflow CX às entradas de registro do webhook das funções do Cloud Run correspondentes. O exemplo usa filtros do Cloud Logging para um agente que ativou o Cloud Logging.
1. Filtrar registros de erros de um agente específico do Dialogflow CX
Use o seguinte filtro do Cloud Logging para filtrar os registros de erro de um agente específico do Dialogflow CX:
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 de funções do Cloud Run por ID da sessão
Use o seguinte filtro do Cloud Logging para filtrar os registros de funções do Cloud Run 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"
}
Anote o campo trace, que será 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 registros do função do Cloud de um determinado rastreamento:
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 ficaria assim:
{
"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
}