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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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 pelos agentes de conversação (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
A depuração de problemas de webhook geralmente envolve a coleta dos registros do Cloud Logging e do Dialogflow e os registros do servidor de webhook. Se o servidor de webhook for implementado usando o Cloud Run functions, 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 quando o Cloud Logging está ativado.
Problemas comuns de webhook
Alguns erros que podem ser encontrados nos registros do Dialogflow para chamadas de webhook são:
Erro de resolução do nome do host do servidor de webhook
O Dialogflow pesquisou o nome do 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
de 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 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 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 finais ou chamadores 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 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 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 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 e um servidor de webhook usando o ID da sessão, o ID do detectIntentResponse
, o ID de 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 em
funções do Cloud Run
ou 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 registro de erros de um determinado agente do Dialogflow às entradas de registro do webhook das funções correspondentes do Cloud Run. 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
Use o seguinte filtro do Cloud Logging para filtrar os registros de erro de um agente específico do Dialogflow:
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 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 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
}