Questa guida fornisce vari esempi per l'implementazione dei webhook e consigli per la risoluzione dei problemi relativi ai webhook.
Impostare un parametro sessione
Gli esempi riportati di seguito mostrano come impostare un parametro di sessione.
Go
Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Consulta la guida rapida ai webhook.Java
Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Restituisci una risposta di evasione
Gli esempi riportati di seguito mostrano come restituire una risposta di evasione.
Go
Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Consulta la guida rapida ai webhook.Java
Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Imposta i parametri del modulo in base alle esigenze.
Gli esempi riportati di seguito mostrano come contrassegnare un parametro come obbligatorio.
Java
Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Convalidare un parametro del modulo
Gli esempi riportati di seguito mostrano come convalidare un parametro del modulo.
Java
Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
ID sessione log
Il seguente esempio mostra come registrare session ID
da una richiesta webhook.
Python
Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, 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 Conversational Agents (Dialogflow CX) e vanno 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 server web (server webhook) disponibili su internet pubblico. D'altra parte, i webhook di Service Directory iniziano sempre da un indirizzoGoogle Cloud interno e possono raggiungere solo i server webhook nelle reti private all'interno di Google Cloud.
Log utili per il debug dei webhook
Il debug dei problemi relativi ai webhook in genere comporta la raccolta dei log di Cloud Logging di Dialogflow e dei log del server webhook. Se il server webhook è implementato utilizzando le funzioni Cloud Run, i relativi log si troveranno in Cloud Logging. In caso contrario, i log si trovano in genere 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 quando Cloud Logging è abilitato.
Problemi comuni relativi ai webhook
Alcuni errori che possono essere trovati nei log di Dialogflow per le chiamate webhook sono:
Errore di risoluzione del nome host del server webhook
Dialogflow 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
A parte 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
.
Timeout dell'agente Dialogflow prima che il server webhook restituisca una risposta
Dialogflow 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 del webhook da parte di Dialogflow. La riduzione del tempo di elaborazione di solito porta a risultati migliori, anche se
in molti casi non è semplice. 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. Cloud Logging
message: 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 è stato raggiunto
prima del termine della chiamata webhook. Questo limite viene impostato di solito a livello di integrazione ed è indipendente dai parametri Dialogflow e dai limiti di timeout dei webhook. Per ulteriori informazioni sulle scadenze gRPC, visita la pagina
https://grpc.io/docs/guides/deadlines/.
Cloud Logging
message: 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 o 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 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
.
Tracciamento delle chiamate webhook
Una chiamata webhook standard può essere correlata tra Dialogflow e
un server webhook utilizzando l'ID sessione, l'ID detectIntentResponse
, l'ID traccia
per le funzioni Cloud Run e un timestamp della chiamata. Il tracciamento flessibile dei webhook può essere eseguito utilizzando il timestamp della chiamata e i valori dei parametri di sessione specificati nella definizione del webhook in fase di progettazione. Per ulteriori informazioni
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 degli agenti con i log dei webhook
per le richieste che utilizzano lo stesso ID sessione.
La sezione precedente ID sessione log
mostra come registrare l'ID sessione da un webhook.
Inoltre, se ospiti il webhook su
Cloud Run Functions
o su un'opzione serverless Google Cloud simile,
puoi utilizzare il campo trace
delle
voci di log
come filtro dei log.
Una singola esecuzione di una funzione genera più voci di log
con lo stesso valore di traccia.
L'esempio successivo utilizza sia l'ID sessione sia il valore di traccia per associare un log di errori di un agente Dialogflow specifico alle voci di log del webhook delle funzioni Cloud Run corrispondenti. L'esempio utilizza filtri di Cloud Logging per un agente che ha abilitato Cloud Logging.
1. Filtrare i log di Dialogflow per i log degli errori di un agente specifico
Utilizza il seguente filtro Cloud Logging per filtrare i log di Dialogflow in base ai 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 è simile alla seguente:
{
"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. Filtrare i log delle funzioni Cloud Run per ID sessione
Utilizza il seguente filtro Cloud Logging per filtrare i log delle funzioni Cloud Run in base all'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. 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 viene utilizzato nel passaggio successivo.
3. Filtrare i log di Cloud Functions per una traccia specifica
Utilizza il seguente filtro Cloud Logging per filtrare i log diCloud Functions 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 sarà simile al seguente.
{
"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
}