Questa guida fornisce vari esempi per l'implementazione dei webhook, nonché consigli per la risoluzione dei problemi relativi ai webhook.
Imposta un parametro sessione
I seguenti esempi mostrano come impostare un parametro di 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 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
I seguenti esempi 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 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
I seguenti esempi 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
I seguenti esempi 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.
ID sessione di log
L'esempio seguente mostra come registrare 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 dei servizi web generici provengono da un indirizzo IP internet che appartiene a 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 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 del webhook di solito comporta la raccolta dei log di Cloud Logging Dialogflow CX e dei log del server webhook. Se il server webhook è implementato utilizzando Cloud Run Functions, i relativi log si troveranno in Cloud Logging. In caso contrario, i log si troverebbero in genere nella posizione in cui viene eseguito il server webhook.
I log dei webhook standard contengono un campo detectIntentResponseId con un UUID che può essere utile per tracciare una determinata chiamata 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 un po' di 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 del fatto 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 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 di solito porta ai risultati migliori, anche se in molti casi non è semplice. Tieni presente che esiste un limite massimo di timeout per i webhook e che i chiamanti o gli utenti finali dovrebbero 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 termine della chiamata webhook. Questo limite viene solitamente impostato a livello di integrazione ed è indipendente dai parametri di Dialogflow CX e dai limiti di timeout del 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 o perché 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.
Tracciamento delle 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. Il tracciamento flessibile del webhook può essere eseguito utilizzando il timestamp della chiamata e i valori dei parametri della sessione specificati nella definizione del webhook in fase di progettazione. Per saperne di più sulle richieste di 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 del 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 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 della traccia per associare un particolare log degli errori dell'agente Dialogflow CX alle voci di log del webhook di Cloud Run Functions corrispondenti. L'esempio utilizza i filtri di Cloud Logging per un agente che ha attivato Cloud Logging.
1. Filtra i log di Dialogflow CX per i log degli errori di un determinato agente
Utilizza il seguente filtro di Cloud Logging per filtrare i log di Dialogflow CX in base ai log degli errori di un determinato agente:
labels.location_id="global"
labels.agent_id="AGENT_ID"
severity=ERROR
Una voce di errore del log del 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. Filtra i log di Cloud Run Functions in base all'ID sessione
Utilizza il seguente filtro di Cloud Logging per filtrare i log di Cloud Run Functions 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. Filtra i log di Cloud Functions per una determinata traccia
Utilizza il seguente filtro di Cloud Logging per filtrare i log di Cloud Function per una determinata traccia:
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
}