Este guia oferece vários exemplos de implementação de webhooks e recomendações de solução de problemas.
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 fulfillment.
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.
Definir 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 do 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
Vida útil de uma chamada de webhook
As chamadas de webhook são sempre iniciadas por agentes de conversação (Dialogflow CX) e acessam um servidor da Web por HTTPS. As chamadas de webhooks de serviço da Web genéricas têm origem em 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 interno do Google Cloud e só podem alcançar servidores de webhook em redes particulares no Google Cloud.
Registros úteis para depurar webhooks
A depuração de problemas de webhook geralmente envolve a coleta dos registros do Dialogflow do Cloud Logging e dos registros do servidor do webhook. Se o servidor do webhook for implementado usando as funções do Cloud Run, os registros dele estarão no Cloud Logging. Caso contrário, os registros normalmente ficam onde o servidor do 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 quando
o Cloud Logging está ativado.
Problemas comuns de webhook
Alguns erros que podem ser encontrados nos registros do Dialogflow para chamadas de webhooks são:
Erro de resolução do nome do host do servidor do webhook
O Dialogflow pesquisou o nome de host de um webhook genérico e
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 do webhook retorna um erro do lado do cliente
Além de ERROR_DNS
, esse estado indica uma resposta 4xx do servidor do webhook. Isso pode ser um status não autorizado (401 - ERROR_AUTHENTICATION
)
ou que o URL não foi encontrado no servidor do webhook (404 - ERROR_NOT_FOUND
).
Mensagem de registro na nuvem: State: URL_ERROR
.
O agente do Dialogflow expira antes que o servidor de webhook retorne uma resposta
O Dialogflow atingiu o limite de tempo do webhook antes que o servidor da Web
terminasse. As duas abordagens possíveis são reduzir o tempo de processamento do servidor do webhook ou aumentar o tempo que o Dialogflow espera pelo webhook. Reduzir o tempo de processamento geralmente traz melhores resultados, embora
isso 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 autores de chamadas finais precisam esperar mais 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 do webhook retorne uma resposta
O limite de tempo definido pelo gRPC na chamada da API Dialogflow foi atingido
antes que a chamada de webhook fosse concluída. Esse limite é definido geralmente no nível da integração
e é independente dos parâmetros do Dialogflow e dos limites de tempo do webhook. Para mais informações sobre os 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 do webhook.
O servidor de webhook não pode ser acessado 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 pode acessar o endereço do servidor do webhook
no nível da rede. Se a solicitação aparecer nos registros do servidor do webhook,
encontre o motivo pelo qual 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 detectIntentResponse
, o ID de rastreamento para funções do Cloud Run e um carimbo de data/hora da chamada. O rastreamento flexível de webhooks pode ser feito usando o carimbo de data/hora da chamada e os valores do parâmetro de sessão especificados na definição do webhook no momento do design. Para mais informações
sobre solicitações de webhooks flexíveis e padrão, 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 os registros do agente com os registros do webhook
para solicitações que usam o mesmo ID de sessão.
A seção ID de sessão de registro anterior
mostra como registrar o ID da sessão em um webhook.
Além disso, se você estiver hospedando seu webhook em funções do Cloud Run ou em uma opção sem servidor semelhante do Google Cloud, use o campo trace
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 próximo exemplo usa o ID da sessão e o valor de rastreamento para associar um registro de erro específico do agente do Dialogflow às entradas de registro de 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 no Dialogflow
Use o seguinte filtro do Cloud Logging para filtrar os registros do Dialogflow de um agente específico:
labels.location_id="global"
labels.agent_id="AGENT_ID"
severity=ERROR
Uma entrada de erro de registro de webhook tem este formato:
{
"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 de sessão
Use o seguinte filtro do Cloud Logging para filtrar os registros de funções do Cloud Run por ID de 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 será usado na próxima etapa.
3. Filtrar registros do Cloud Functions para um rastro específico
Use o seguinte filtro do Cloud Logging para filtrar os registros do função do Cloud de um determinado rastro:
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 rastro. Por exemplo, o TRACE_ID
para projects/PROJECT_ID/traces/e41eefc1fac48665b442bfa400cc2f5e
é
e41eefc1fac48665b442bfa400cc2f5e
.
O resultado é o registro do servidor do webhook gerado durante a execução da solicitação do webhook associada ao ID da sessão da etapa 1 e ao rastreamento da etapa 2. O registro vai ficar 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
}