Questa guida fornisce vari esempi per l'implementazione dei webhook , nonché consigli per la risoluzione dei problemi relativi ai webhook.
Imposta un parametro sessione
Gli esempi riportati di seguito mostrano come impostare un parametro sessione.
Go
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Consulta la guida rapida relativa ai webhook.Java
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Restituisci una risposta di fulfillment
Gli esempi riportati di seguito mostrano come restituire una risposta di fulfillment.
Go
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Consulta la guida rapida relativa ai webhook.Java
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Imposta i parametri del modulo come richiesto
Gli esempi riportati di seguito mostrano come contrassegnare un parametro come obbligatorio.
Java
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Convalida un parametro del modulo
Gli esempi riportati di seguito mostrano come convalidare un parametro del modulo.
Java
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Registra l'ID sessione
L'esempio seguente mostra come registrare il session ID
da una richiesta webhook.
Python
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Risoluzione dei problemi
Durata di una chiamata webhook
Le chiamate webhook vengono sempre avviate da Dialogflow CX e inviate a un server web tramite HTTPS. Le chiamate webhook del servizio web generico hanno origine da un indirizzo IP internet di proprietà di Google e possono raggiungere i server web (server webhook) disponibili su internet pubblico. D'altra parte, i webhook di Service Directory iniziano sempre da un indirizzo Google Cloud interno e possono raggiungere solo i server webhook nelle reti private all'interno Google Cloud.
Log utili per il debug dei webhook
Il debug dei problemi relativi ai webhook in genere comporta la raccolta dei log di Dialogflow CX di Cloud Logging e dei log del server webhook. Se il server webhook viene implementato utilizzando Cloud Run Functions, i relativi log si trovano in Cloud Logging. In caso contrario, i log in genere si trovano nella posizione in cui viene eseguito il server webhook.
I log webhook standard contengono un campo detectIntentResponseId con un UUID che può essere utile per tracciare una chiamata specifica nei server webhook. Questo log esiste nei log di Cloud Logging di Dialogflow CX quando Cloud Logging è abilitato.
Problemi comuni relativi ai webhook
Alcuni errori che possono essere trovati nei log di Dialogflow CX per le chiamate webhook sono:
Errore di risoluzione del nome host del server webhook
Dialogflow CX ha cercato il nome host di un webhook generico e il nome host non esiste nel DNS. Assicurati che il nome host sia registrato nel DNS pubblico. Se il nome host è nuovo, la propagazione del record potrebbe richiedere del tempo. Messaggio di Cloud Logging: State: URL_ERROR, Reason: ERROR_DNS.
Il server webhook restituisce un errore lato client
Oltre a ERROR_DNS, questo stato indica una risposta 4xx dal server webhook. Può trattarsi di uno stato non autorizzato (401 - ERROR_AUTHENTICATION) o che l'URL non è stato trovato nel server webhook (404 - ERROR_NOT_FOUND). Messaggio di Cloud Logging: State: URL_ERROR.
L'agente Dialogflow va in timeout prima che il server webhook restituisca una risposta
Dialogflow CX ha raggiunto il limite di timeout del webhook prima che il server web terminasse. I due approcci possibili sono ridurre il tempo di elaborazione del server webhook o aumentare il tempo di attesa di Dialogflow CX per il webhook. La riduzione del tempo di elaborazione in genere offre risultati migliori, anche se in molti casi non è banale. Tieni presente che esiste un limite di timeout massimo per i webhook e che i chiamanti o gli utenti finali dovranno attendere più a lungo per ricevere una risposta dall'agente prima di aumentare questa impostazione. Messaggio di Cloud Logging: State: URL_TIMEOUT, Reason: TIMEOUT_WEB.
gRPC va in timeout prima che il server webhook restituisca una risposta
Il limite di tempo impostato da gRPC nella chiamata API Dialogflow CX è stato raggiunto prima del completamento della chiamata webhook. Questo limite viene impostato in genere a livello di integrazione ed è indipendente dai parametri di Dialogflow CX e dai limiti di timeout dei webhook. Per saperne di più sulle scadenze di gRPC, consulta
https://grpc.io/docs/guides/deadlines/.
Messaggio di Cloud Logging: State: URL_REJECTED, Reason: REJECTED_DEADLINE_EXCEEDED.
Dialogflow non è riuscito a contattare il server webhook
Non è stato possibile raggiungere il server webhook a causa di un errore di rete oppure la connessione è stata stabilita e il server webhook ha restituito lo stato HTTP 5xx che indica un problema durante l'elaborazione della richiesta. Assicurati che Dialogflow CX possa raggiungere l'indirizzo del server webhook a livello di rete. Se la richiesta viene visualizzata nei log del server webhook, scopri perché la chiamata ha restituito un errore 5xx. Messaggio di Cloud Logging:
State: URL_UNREACHABLE.
Traccia le chiamate webhook
Una chiamata webhook standard può essere correlata tra Dialogflow CX e un server webhook utilizzando l'ID sessione, l'ID detectIntentResponse, l'ID traccia per Cloud Run Functions e un timestamp della chiamata. La tracciabilità flessibile dei webhook può essere eseguita utilizzando il timestamp della chiamata e i valori dei parametri sessione specificati nella definizione del webhook in fase di progettazione. Per saperne di più sulle richieste webhook standard e flessibili, consulta
Webhook.
L'ID sessione viene visualizzato nel campo sessionInfo.session di
WebhookRequest.
Questo ID sessione deve essere univoco per ogni conversazione e può aiutarti a confrontare i log dell'agente con i log webhook per le richieste che utilizzano lo stesso ID sessione.
La sezione precedente Registra l'ID sessione
mostra come registrare l'ID sessione da un webhook.
Inoltre, se ospiti il webhook su
Cloud Run Functions
o su un'opzione Google Cloud serverless simile,
puoi utilizzare il campo trace delle
voci di log
come filtro di log.
Una singola esecuzione di una funzione genera più voci di log con lo stesso valore di traccia.
L'esempio seguente utilizza sia l'ID sessione sia il valore di traccia per associare un log degli errori di un agente Dialogflow CX specifico alle voci di log webhook di Cloud Run Functions corrispondenti. L'esempio utilizza i filtri di Cloud Logging per un agente che ha abilitato Cloud Logging.
1. Filtra i log di Dialogflow CX per i log degli errori di un agente specifico
Utilizza il seguente filtro di Cloud Logging per filtrare i log di Dialogflow CX per i log degli errori di un agente specifico:
labels.location_id="global"
labels.agent_id="AGENT_ID"
severity=ERROR
Una voce di errore del log webhook ha il seguente aspetto:
{
"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"
}
Prendi nota del campo labels.session_id che contiene l'ID sessione.
Utilizzerai l'ID sessione nel passaggio successivo.
2. Filtra i log di Cloud Run Functions per ID sessione
Utilizza il seguente filtro di Cloud Logging per filtrare i log di Cloud Run Functions per ID sessione:
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"
I log risultanti corrispondono ai log webhook creati durante la sessione fornita sessione. Ad esempio:
{
"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"
}
Prendi nota del campo trace, che verrà utilizzato nel passaggio successivo.
3. Filtra i log di Cloud Functions per una traccia specifica
Utilizza il seguente filtro di Cloud Logging per filtrare i log di Cloud Function per una traccia specifica:
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"
dove TRACE_ID è l'ultimo segmento della traccia. Ad esempio, il TRACE_ID
per projects/PROJECT_ID/traces/e41eefc1fac48665b442bfa400cc2f5e è
e41eefc1fac48665b442bfa400cc2f5e.
Il risultato è il log del server webhook generato durante l'esecuzione della richiesta webhook associata all'ID sessione del passaggio 1 e alla traccia del passaggio 2. Il log avrà il seguente aspetto.
{
"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
}