Un webhook può essere un webhook standard o un webhook flessibile. Con un webhook standard, i campi di richiesta e risposta sono definiti da Conversational Agents (Dialogflow CX). Con un webhook flessibile, puoi definire i campi di richiesta e risposta.
Webhook standard
Con i webhook standard, utilizzi i messaggi di richiesta e risposta definiti da Conversational Agents (Dialogflow CX). Il messaggio di richiesta fornisce molti dettagli sulla sessione. Ad esempio, sono inclusi la pagina attiva corrente, l'intenzione associata di recente, i valori dei parametri di sessione e le risposte definite dall'agente.
Richiesta webhook standard
Quando viene chiamato un servizio di evasione con un webhook, gli agenti conversazionali (Dialogflow CX) inviano una richiesta webhook POST HTTPS al servizio webhook.
Il corpo di questa richiesta è un oggetto JSON WebhookRequest
con informazioni sulla sessione.
Alcune
integrazioni
compilano il campo WebhookRequest.payload
con informazioni aggiuntive.
Ad esempio, l'integrazione di Dialogflow CX con Phone Gateway fornisce l'ID chiamante dell'utente finale.
Per maggiori dettagli, consulta la documentazione di riferimento di WebhookRequest
(V3) o WebhookRequest
(V3Beta1).
Risposta webhook standard
Una volta che il servizio webhook riceve una richiesta, deve inviare una risposta. Alla risposta si applicano le seguenti limitazioni:
- La risposta deve avvenire entro un timeout configurato quando crei la risorsa webhook, altrimenti la richiesta scadrà.
- La risposta deve avere dimensioni inferiori o uguali a 64 KiB.
Per maggiori dettagli, consulta la documentazione di riferimento di WebhookResponse
(V3) o WebhookResponse
(V3Beta1).
Impostazioni della risorsa webhook standard
Di seguito sono descritte le impostazioni delle risorse webhook per i webhook standard:
Termine | Definizione |
---|---|
Nome visualizzato | Il nome visualizzato nella console per l'webhook. |
Timeout webhook | Quando Conversational Agents (Dialogflow CX) invia una richiesta webhook al tuo servizio webhook, potrebbe scadere il tempo di attesa mentre attende una risposta. Questa impostazione controlla il timeout in secondi. Se si verifica un timeout, Conversational Agents (Dialogflow CX) richiama un evento webhook.error.timeout. |
Tipo | Imposta Service Directory se utilizzi Service Directory per l'accesso alla rete privata, altrimenti imposta Servizio web generico. |
URL webhook | Fornisci l'indirizzo URL del servizio webhook. |
Sottotipo | Imposta su Standard |
Webhook specifico per l'ambiente | Puoi fornire webhook specifici per l'ambiente. |
Autenticazione | Consulta la sezione sull'autenticazione. |
Certificato CA personalizzato | Viene utilizzato per caricare certificati CA personalizzati. |
Webhook flessibili
Con gli webhook flessibili, puoi definire il metodo HTTP della richiesta, i parametri URL della richiesta e i campi dei messaggi di richiesta e risposta. La richiesta può fornire solo valori di parametro selezionati, mentre la risposta può fornire solo valori di override dei parametri. Questa limitazione è in realtà vantaggiosa, poiché semplifica l'interfaccia tra l'agente e l'webhook. Raramente è necessario comunicare qualcos'altro oltre ai valori dei parametri della sessione tra un agente e un webhook. Semplifica anche l'implementazione degli webhook, poiché i messaggi di richiesta e risposta contengono solo ciò che ti serve e puoi fornire messaggi webhook unici per vari scenari.
Richiesta di webhook flessibile
Quando crei la risorsa webhook per l'agente, puoi specificare quanto segue per le richieste webhook:
- Il metodo HTTP utilizzato per le richieste webhook inviate al servizio webhook.
- Valori dei parametri di sessione che gli agenti conversazionali (Dialogflow CX) devono inviare al servizio webhook utilizzando l'URL.
- Se scegli
POST
,PUT
oPATCH
come metodo, puoi specificare i valori dei parametri di sessione che gli agenti conversazionali (Dialogflow CX) devono inviare al servizio webhook tramite il corpo JSON della richiesta.
Per inviare i valori dei parametri di sessione utilizzando l'URL della richiesta o il corpo JSON, utilizza i riferimenti ai parametri come faresti normalmente. Non è necessario applicare la codifica URL al riferimento del parametro e non è necessario racchiuderlo tra virgolette. In fase di esecuzione, Conversational Agents (Dialogflow CX) eseguirà la codifica URL del valore parametro in base alle esigenze. Un valore composto o un elenco verrà fornito come JSON.
Quando utilizzi un riferimento a un parametro nel corpo JSON, devi racchiudere il riferimento tra virgolette, indipendentemente dal tipo di parametro. Se il parametro è in realtà un valore scalare, un elenco o un valore composito numerico, agenti conversazionali (Dialogflow CX) rimuoverà le virgolette quando invia la richiesta in fase di esecuzione per preservare il tipo di dati del parametro. I tipi scalari di stringa rimarranno tra virgolette. Se a un valore scalare, di elenco o composito numerico viene fatto riferimento all'interno di un valore di stringa (ad esempio: "Questo è un numero: $session.params.size"), il parametro verrà trattato come stringa ("Questo è un numero: 3").
Ad esempio,
puoi fornire i valori dei parametri di sessione fruit
e size
all'URL di richiesta come segue:
https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size
E al corpo JSON della richiesta come segue:
{
"fruitParameter": "$session.params.fruit",
"sizeParameter": "$session.params.size"
}
Risposta webhook flessibile
Quando crei la risorsa webhook per l'agente, puoi specificare i parametri di sessione che Conversational Agents (Dialogflow CX) deve impostare su campi specifici della risposta webhook in fase di esecuzione.
Alla risposta si applicano le seguenti limitazioni:
- La risposta deve avvenire entro un timeout configurato quando crei la risorsa webhook, altrimenti la richiesta scadrà.
- La risposta deve avere dimensioni inferiori o uguali a 64 KiB.
Utilizza il seguente formato per specificare un campo scalare, un elenco o un campo composto:
$.fully.qualified.path.to.field
Ad esempio, considera la seguente risposta JSON:
{
"routes" : [
{
"legs" : [
{
"distance" : {
"text" : "2,064 mi",
"value" : 3321004
}
}
]
}
]
}
Per specificare il campo "value", utilizza quanto segue:
$.routes[0].legs[0].distance.value
Impostazioni flessibili delle risorse webhook
Di seguito sono descritte le impostazioni delle risorse webhook per i webhook flessibili:
Termine | Definizione |
---|---|
Nome visualizzato | Il nome visualizzato nella console per l'webhook. |
Timeout webhook | Quando Conversational Agents (Dialogflow CX) invia una richiesta webhook al tuo servizio webhook, potrebbe scadere il tempo di attesa mentre attende una risposta. Questa impostazione controlla il timeout in secondi. Se si verifica un timeout, Conversational Agents (Dialogflow CX) richiama un evento webhook.error.timeout. |
Tipo | Imposta Service Directory se utilizzi Service Directory per l'accesso alla rete privata, altrimenti imposta Servizio web generico. |
URL webhook | Fornisci l'indirizzo URL del servizio webhook, che può includere riferimenti ai parametri di sessione. |
Sottotipo | Impostato su Flessibile |
Metodo | Imposta il metodo HTTP per la richiesta webhook. |
Corpo della richiesta | Fornisci il corpo JSON della richiesta come descritto sopra. |
Configurazione della risposta | Fornisci i parametri di sessione che devono essere impostati sui campi di risposta come descritto sopra. |
Webhook specifico per l'ambiente | Puoi fornire webhook specifici per l'ambiente. |
Autenticazione | Consulta la sezione sull'autenticazione. |
Certificato CA personalizzato | Viene utilizzato per caricare certificati CA personalizzati. |
Utilizzare un modello personalizzato predefinito
Dialogflow offre modelli personalizzati predefiniti che puoi utilizzare per integrare webhook flessibili con Salesforce CRM.
Nella scheda Gestisci, fai clic su Webhook e poi su + Crea.
In Sottotipo, seleziona Flessibile.
Fai clic su Configura utilizzando un modello predefinito per attivare la funzionalità.
Nel menu a discesa Tipo di integrazione, seleziona Salesforce.
Nel menu a discesa Nome API, seleziona un nome per l'API. Il modello compila automaticamente il modulo webhook in base al nome dell'API scelto.
Se applicabile, puoi configurare manualmente i seguenti campi in base ai parametri:
- URL webhook
- Metodo
- Corpo JSON della richiesta
- Configurazione della risposta
I campi OAuth obbligatori verranno evidenziati nella sezione Autenticazione.
Fai clic su Salva per creare l'webhook.
Requisiti del servizio webhook
Il servizio webhook deve soddisfare i seguenti requisiti:
- Deve gestire le richieste HTTPS. HTTP non è supportato. Se ospiti il servizio webhook sulla Google Cloud Platform utilizzando una soluzione di computing o computing serverless, consulta la documentazione del prodotto per la pubblicazione con HTTPS. Per altre opzioni di hosting, consulta Ottenere un certificato SSL per il tuo dominio.
- L'URL per le richieste deve essere accessibile pubblicamente, a meno che non sia ospitato come funzione Cloud Run o non sia accessibile come webhook della directory dei servizi.
- Deve gestire le richieste e le risposte come descritto nella sezione relativa ai webhook standard o ai webhook flessibili.
- Se il tuo agente non si integra con l'accesso alla rete privata di Service Directory, le chiamate webhook sono considerate esterne al perimetro di servizio e vengono bloccate quando attivi i Controlli di servizio VPC. Gli endpoint con limitazioni sono supportati da Service Directory. Per informazioni dettagliate, consulta Service Directory.
Autenticazione
È importante proteggere il servizio webhook, in modo che solo tu o il tuo agente Conversational Agents (Dialogflow CX) siate autorizzati a effettuare richieste. Viene configurato durante la creazione di una risorsa webhook. Conversational Agents (Dialogflow CX) supporta i seguenti meccanismi di autenticazione:
Termine | Definizione |
---|---|
Intestazioni di autenticazione | Per le impostazioni del webhook, puoi specificare coppie chiave-valore facoltative dell'intestazione HTTP. Se fornite, Conversational Agents (Dialogflow CX) aggiunge queste intestazioni HTTP alle richieste webhook. È comune fornire una singola coppia con una chiave authorization . I valori dell'intestazione supportano i riferimenti ai parametri di sessione e l'analisi di sistema delle funzioni, come nei messaggi di risposta statici. |
Autenticazione di base con nome utente e password | Per le impostazioni del webhook, puoi specificare valori facoltativi per nome utente e password di accesso. Se specificato, Conversational Agents (Dialogflow CX) aggiunge un'intestazione HTTP di autorizzazione alle richieste webhook. Questa intestazione è del tipo: "authorization: Basic <base 64 encoding of the string username:password>" . |
OAuth di terze parti | Puoi specificare la configurazione OAuth di terze parti in modo che gli agenti di conversazione (Dialogflow CX) scambino un token di accesso dal sistema OAuth e lo aggiungano all'intestazione HTTP di autorizzazione. È supportato solo il flusso delle credenziali client. |
Token di accesso dell'agente di servizio | Puoi selezionare il token di accesso nell'autenticazione dell'agente di servizio per utilizzare i token di accesso dell'agente di servizio per l'autenticazione. Questo token può essere utilizzato per accedere ad altre API Google Cloud. |
Token ID agente di servizio | Puoi selezionare il token ID nell'autenticazione dell'agente di servizio per utilizzare i token ID agente di servizio per l'autenticazione. Può essere utilizzato per accedere alle funzioni e ai servizi Cloud Run. |
Autenticazione TLS reciproca | Consulta la documentazione sull'autenticazione TLS reciproca. |
OAuth di terze parti
Gli agenti conversazionali (Dialogflow CX) possono raccogliere un token di accesso da un provider OAuth di terze parti e aggiungerlo all'intestazione HTTP di autorizzazione quando effettuano le richieste webhook.
Di seguito sono descritte le impostazioni delle risorse per OAuth di terze parti:
Termine | Definizione |
---|---|
ID client | L'ID client da utilizzare per richiedere un token OAuth. |
Client secret | Il segreto da utilizzare per richiedere un token OAuth. |
URL endpoint OAuth | L'URL da utilizzare per richiedere un token OAuth. |
Ambiti OAuth | Un elenco separato da virgole di ambiti per i quali è possibile utilizzare il token OAuth. |
Le richieste inviate all'URL dell'endpoint OAuth per ricevere un token non includono le intestazioni delle richieste personalizzate configurate per la richiesta webhook. Puoi passare informazioni personalizzate al server OAuth come parametri all'interno della stringa di query dell'URL dell'endpoint OAuth.
Token di accesso dell'agente di servizio
Conversational Agents (Dialogflow CX) può generare un token ID o un token di accesso utilizzando l'agente di servizio Conversational Agents (Dialogflow CX).
Il token viene aggiunto nell'intestazione HTTP di autorizzazione quando Conversational Agents (Dialogflow CX) chiama un webhook.
Token ID
Un token ID può essere utilizzato per accedere alle funzioni e ai servizi Cloud Run dopo aver concesso il ruolo Invoker a
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Il segmento di pubblico utilizzato per generare il token ID sarà l'intero URL dell'webhook, ad eccezione dei parametri di query. Se utilizzi Cloud Run, assicurati che questo URL sia supportato dai segmenti di pubblico Cloud Run. Ad esempio, se l'URL del webhook è
https://myproject.cloudfunctions.net/my-function/method1?query=value
Il seguente URL deve essere presente nei segmenti di pubblico personalizzati.
https://myproject.cloudfunctions.net/my-function/method1
Qualsiasi webhook può anche convalidare facoltativamente il token utilizzando le librerie client di Google o librerie open source come github.com/googleapis/google-auth-library-nodejs.
Token di accesso
Un token di accesso può essere utilizzato per accedere ad altre API Google Cloud dopo aver concesso i ruoli richiesti a
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Verifica del certificato HTTPS
Per impostazione predefinita, Conversational Agents (Dialogflow CX) utilizza l'archivio attendibilità predefinito di Google per verificare i certificati HTTPS. Se intendi utilizzare certificati non riconosciuti dall'archivio attendibile predefinito di Google per il tuo server HTTPS, ad esempio certificati autofirmati o certificati radice personalizzati, consulta Certificati CA personalizzati.
Webhook specifici per l'ambiente
Se utilizzi gli ambienti per isolare i sistemi di produzione da quelli di sviluppo (opzione consigliata), puoi configurare gli webhook in modo che siano specifici per l'ambiente. Per ogni risorsa webhook che definisci, puoi fornire impostazioni di autenticazione e URL univoche per ogni ambiente che hai definito per l'agente.
In questo modo, puoi sviluppare e testare in sicurezza gli aggiornamenti del codice webhook prima di implementarli in produzione.
Creare o modificare le risorse webhook
Una volta eseguito un servizio webhook, devi creare una risorsa webhook nell'agente con informazioni su connettività e autenticazione. Dopo la creazione, puoi anche modificare le impostazioni della risorsa webhook in qualsiasi momento.
Per creare o modificare una risorsa webhook:
Console
- Apri la console Dialogflow CX.
- Scegli il tuo progetto Google Cloud.
- Seleziona il tuo agente.
- Seleziona la scheda Gestisci.
- Fai clic su Webhook.
- Fai clic su Crea o su una risorsa webhook nell'elenco da modificare.
- Inserisci le impostazioni delle risorse webhook standard o le impostazioni delle risorse webhook flessibili.
- Fai clic su Salva.
API
Per creare una risorsa webhook, consulta il metodo create
per il tipo Webhook
.
Per modificare una risorsa webhook (tranne le impostazioni specifiche dell'ambiente), consulta il metodo patch
o update
per il tipo Webhook
.
Seleziona un protocollo e una versione per il riferimento webhook:
Protocollo | V3 | V3beta1 |
---|---|---|
REST | Risorsa webhook | Risorsa webhook |
RPC | Interfaccia webhook | Interfaccia webhook |
C++ | WebhooksClient | Non disponibile |
C# | WebhooksClient | Non disponibile |
Vai | WebhooksClient | Non disponibile |
Java | WebhooksClient | WebhooksClient |
Node.js | WebhooksClient | WebhooksClient |
PHP | Non disponibile | Non disponibile |
Python | WebhooksClient | WebhooksClient |
Ruby | Non disponibile | Non disponibile |
Per modificare le impostazioni specifiche dell'ambiente per un webhook, consulta il metodo patch
o update
per il tipo Environment
.
Seleziona un protocollo e una versione per il riferimento all'ambiente:
Protocollo | V3 | V3beta1 |
---|---|---|
REST | Risorsa ambiente | Risorsa ambiente |
RPC | Interfaccia dell'ambiente | Interfaccia dell'ambiente |
C++ | EnvironmentsClient | Non disponibile |
C# | EnvironmentsClient | Non disponibile |
Vai | EnvironmentsClient | Non disponibile |
Java | EnvironmentsClient | EnvironmentsClient |
Node.js | EnvironmentsClient | EnvironmentsClient |
PHP | Non disponibile | Non disponibile |
Python | EnvironmentsClient | EnvironmentsClient |
Ruby | Non disponibile | Non disponibile |
Errori webhook
Se il servizio webhook rileva un errore durante la gestione di una richiesta webhook, il codice webhook deve restituire uno dei seguenti codici di stato HTTP:
400
Richiesta errata401
Non autorizzato403
Vietato404
Non trovato500
Errore del server503
Servizio non disponibile
In una delle seguenti situazioni di errore, Conversational Agents (Dialogflow CX) richiama un evento predefinito di errore o timeout del webhook e continua l'elaborazione come di consueto:
- È stato superato il timeout della risposta.
- Codice di stato di errore ricevuto.
- La risposta non è valida.
- Il servizio webhook non è disponibile.
Inoltre, se la chiamata al servizio webhook è stata attivata da una chiamata all'API di rilevamento dell'intenzione, il campo queryResult.webhookStatuses
nella risposta al rilevamento dell'intenzione contiene le informazioni sullo stato del webhook.
Nuovi tentativi automatici
Conversational Agents (Dialogflow CX) include meccanismi interni che tentano automaticamente di nuovo in caso di determinati errori webhook per migliorare la robustezza. Verranno eseguiti nuovi tentativi solo per gli errori non terminali (ad esempio timeout o errori di connessione).
Per ridurre la probabilità di chiamate duplicate:
- Imposta soglie di timeout dei webhook più lunghe.
- Supporta l'idempotenza nella logica del webhook o esegui la deduplica.
Utilizzo di Cloud Run Functions
Conversational Agents (Dialogflow CX) si integra con le funzioni Cloud Run, in modo da poter creare facilmente un webhook sicuro e serverless. Se crei una funzione che si trova nello stesso progetto del tuo agente, basta selezionare Auth Service Agent -> ID Token nella configurazione di Auth, in modo che l'agente possa chiamare in modo sicuro il tuo webhook.
Tuttavia, esistono due situazioni in cui devi configurare manualmente questa integrazione:
- Per il progetto dell'agente deve esistere l'account di servizio
Agenti conversazionali (Dialogflow CX) con il seguente indirizzo:
In genere, questo account di servizio speciale e la chiave associata vengono creati automaticamente quando crei il primo agente per un progetto. Se il tuo agente è stato creato prima del 1° novembre 2020, puoi attivare la creazione di questo account di servizio speciale:service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
- Crea un nuovo agente per il progetto.
- Esegui questo comando:
gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
- Se la funzione webhook si trova in un progetto diverso dall'agente, devi fornire il ruolo IAM Invoker di Cloud Functions all'account di servizio Agente di servizio per gli agenti conversazionali (Dialogflow CX) nel progetto della funzione.
- Seleziona Auth agente di servizio -> Token ID nella sezione di configurazione dell'autenticazione.
Utilizzo di webhook containerizzati e del framework ezcx per Go
Se vuoi implementare un webhook containerizzato utilizzando Go, consulta il framework Go ezcx. Questo framework può semplificare molti dei passaggi necessari per creare un webhook.
Utilizzo di Cloud Run functions con traffico solo interno
Le funzioni Cloud Run configurate per accettare il traffico interno dalle reti VPC nello stesso progetto o nello stesso perimetro dei controlli di servizio VPC possono essere utilizzate come webhook purché l'agente si trovi nello stesso progetto o nello stesso perimetro dei controlli di servizio VPC.
Utilizzo di Service Directory per l'accesso alla rete privata
Gli agenti conversazionali (Dialogflow CX) si integrano con l'accesso alla rete privata di Service Directory, pertanto possono connettersi ai target webhook all'interno della rete VPC. In questo modo, il traffico rimane all'interno della rete Google Cloud e vengono applicati IAM e Controlli di servizio VPC.
Per configurare un webhook che ha come target una rete privata:
Segui la configurazione della rete privata di Service Directory per configurare la rete VPC e l'endpoint di Service Directory.
Per il progetto dell'agente deve esistere l'account di servizio Agenti conversazionali (Dialogflow CX) con il seguente indirizzo:
Concedi all'account di servizio Agente di servizio per gli agenti conversazionali (Dialogflow CX) i seguenti ruoli IAM:service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
servicedirectory.viewer
del progetto Service Directoryservicedirectory.pscAuthorizedService
del progetto di rete
Fornisci il servizio Directory dei servizi insieme all'URL e alle informazioni di autenticazione facoltative durante la creazione dell'webhook.
Console
API
Consulta il campo
serviceDirectory
per il tipoWebhook
.Seleziona un protocollo e una versione per il riferimento webhook:
Protocollo V3 V3beta1 REST Risorsa webhook Risorsa webhook RPC Interfaccia webhook Interfaccia webhook C++ WebhooksClient Non disponibile C# WebhooksClient Non disponibile Vai WebhooksClient Non disponibile Java WebhooksClient WebhooksClient Node.js WebhooksClient WebhooksClient PHP Non disponibile Non disponibile Python WebhooksClient WebhooksClient Ruby Non disponibile Non disponibile
Per risolvere i problemi, puoi configurare un controllo di uptime privato per verificare che Service Directory sia configurato correttamente.
Samples e risoluzione dei problemi
Consulta la guida illustrativa sui webhook.