Un webhook può essere un hook standard o un webhook flessibile. Con un webhook standard, i campi della richiesta e della risposta sono definiti da Dialogflow. Con un webhook flessibile, puoi definire i campi della richiesta e della risposta.
Webhook standard
Con i webhook standard, utilizzi i messaggi di richiesta e risposta definiti da Dialogflow. Il messaggio di richiesta fornisce molti dettagli sulla sessione. Ad esempio, sono inclusi la pagina attiva corrente, l'intent con corrispondenza recente, i valori dei parametri della sessione e le risposte definite dall'agente.
Richiesta di webhook standard
Quando viene chiamato un fulfillment con un webhook, Dialogflow invia una richiesta di 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 del gateway telefonico di Dialogflow CX fornisce l'ID chiamante dell'utente finale.
Per informazioni dettagliate, consulta la documentazione di riferimento WebhookRequest
(V3) o WebhookRequest
(V3Beta1).
Risposta webhook standard
Quando il servizio webhook riceve una richiesta, deve inviare una risposta. Alla risposta si applicano le seguenti limitazioni:
- La risposta deve avvenire entro un timeout che hai configurato durante la creazione della risorsa webhook, altrimenti la richiesta scadrà.
- La risposta deve essere inferiore o uguale a 64 KiB.
Per informazioni dettagliate, consulta la documentazione di riferimento WebhookResponse
(V3) o WebhookResponse
(V3Beta1).
Impostazioni delle risorse webhook standard
Di seguito vengono descritte le impostazioni delle risorse webhook per i webhook standard:
Termine | Definizione |
---|---|
Nome visualizzato | Il nome del webhook visualizzato nella console. |
Timeout webhook | Quando Dialogflow invia una richiesta webhook al tuo servizio webhook, potrebbe scadere in attesa di una risposta. Questa impostazione controlla il timeout in secondi. Se si verifica un timeout, Dialogflow richiama un webhook.error.timeout. |
Tipo | Imposta Service Directory se stai utilizzando la directory dei servizi per l'accesso alla rete privata, altrimenti impostala su Servizio web generico. |
URL webhook | Fornisci l'indirizzo URL per il servizio webhook. |
Sottotipo | Imposta su Standard |
Webhook specifico per l'ambiente | Puoi fornire webhook specifici dell'ambiente. |
Autenticazione | Consulta la sezione sull'autenticazione. |
Certificato CA personalizzato | Viene utilizzato per caricare certificati CA personalizzati. |
Webhook flessibili
Con i webhook flessibili, puoi definire il metodo HTTP di richiesta, i parametri URL della richiesta e i campi dei messaggi di richiesta e risposta. La richiesta può fornire solo valori parametro selezionati e la risposta può fornire solo valori di override dei parametri. Questa limitazione è effettivamente vantaggiosa perché semplifica l'interfaccia tra l'agente e il webhook. Raramente è necessario comunicare qualcosa di diverso dai valori dei parametri di sessione tra un agente e un webhook. Inoltre, semplifica l'implementazione del webhook perché i messaggi di richiesta e risposta contengono solo ciò di cui hai bisogno. Inoltre, ti consente di fornire messaggi webhook univoci per vari scenari.
Richiesta 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 di webhook inviate al servizio webhook.
- Valori dei parametri di sessione che Dialogflow deve inviare al tuo servizio webhook utilizzando l'URL.
- Se scegli
POST
,PUT
oPATCH
come metodo, puoi specificare i valori dei parametri di sessione che Dialogflow deve inviare al tuo 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 utilizzare l'escape dell'URL per il riferimento al parametro e non racchiudi il riferimento tra virgolette. In fase di runtime, Dialogflow esegue l'escape dell'URL del valore parametro in base alle esigenze. Verrà fornito un elenco o un valore composto in formato JSON.
Quando utilizzi un riferimento a parametro nel corpo JSON, devi aggregare il riferimento tra virgolette, indipendentemente dal tipo di parametro. Se il parametro è in realtà un valore numerico scalare, elenco o composito, Dialogflow rimuoverà le virgolette durante l'invio della richiesta in fase di runtime per preservare il tipo di dati del parametro. I tipi scalari della stringa rimarranno tra virgolette. Se all'interno di un valore di stringa viene fatto riferimento a un valore scalare, un elenco o composto numerico (ad esempio: "Questo è un numero: $session.params.size"), il parametro verrà trattato come una stringa ("Questo è un numero: 3").
Ad esempio,
puoi fornire i valori dei parametri di sessione fruit
e size
all'URL della richiesta in questo modo:
https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size
Infine, 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 Dialogflow deve impostare su campi specifici della risposta webhook in fase di runtime.
Alla risposta si applicano le seguenti limitazioni:
- La risposta deve avvenire entro un timeout che hai configurato durante la creazione della risorsa webhook, altrimenti la richiesta scadrà.
- La risposta deve essere inferiore o uguale a 64 KiB.
Utilizza il formato seguente per specificare un campo scalare, un elenco o 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 vengono descritte le impostazioni delle risorse webhook per i webhook flessibili:
Termine | Definizione |
---|---|
Nome visualizzato | Il nome del webhook visualizzato nella console. |
Timeout webhook | Quando Dialogflow invia una richiesta webhook al tuo servizio webhook, potrebbe scadere in attesa di una risposta. Questa impostazione controlla il timeout in secondi. Se si verifica un timeout, Dialogflow richiama un webhook.error.timeout. |
Tipo | Imposta Service Directory se stai utilizzando la directory dei servizi per l'accesso alla rete privata, altrimenti impostala su Servizio web generico. |
URL webhook | Fornisci l'indirizzo URL del servizio webhook, che può includere riferimenti ai parametri di sessione. |
Sottotipo | Imposta 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 dell'ambiente. |
Autenticazione | Consulta la sezione sull'autenticazione. |
Certificato CA personalizzato | Viene utilizzato per caricare certificati CA personalizzati. |
Requisiti per il servizio webhook
Il servizio webhook deve soddisfare i seguenti requisiti:
- Deve gestire le richieste HTTPS. HTTP non supportato. Se ospiti il tuo servizio webhook su Google Cloud Platform utilizzando una soluzione di computing o serverless computing, 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 Functions o se si accede come webhook Service Directory.
- Deve gestire le richieste e le risposte come descritto nella sezione relativa al webhook standard o al webhook flessibile.
- Se l'agente non si integra con l'accesso alla rete privata di Service Directory, le chiamate webhook vengono considerate al di fuori del perimetro di servizio e vengono bloccate durante l'attivazione dei Controlli di servizio VPC. Gli endpoint con limitazioni sono supportati da Service Directory. Consulta Service Directory per i dettagli.
Autenticazione
È importante proteggere il servizio webhook in modo che solo tu o il tuo agente Dialogflow siate autorizzati a effettuare richieste. Questo valore viene configurato durante la creazione di una risorsa webhook. Dialogflow CX supporta i seguenti meccanismi per l'autenticazione:
Termine | Definizione |
---|---|
Intestazioni di autenticazione | Per le impostazioni webhook, puoi specificare coppie chiave-valore dell'intestazione HTTP facoltative. Se fornite, Dialogflow aggiunge queste intestazioni HTTP alle richieste di webhook. È comune fornire una singola coppia con la chiave authorization . I valori di intestazione supportano i riferimenti ai parametri di sessione e l'analisi delle funzioni di sistema come nei messaggi di risposta statici. |
Autorizzazione di base con nome utente e password | Per le impostazioni del webhook, puoi specificare valori facoltativi per il nome utente e la password di accesso. Se specificata, Dialogflow aggiunge un'intestazione HTTP di autorizzazione alle richieste di webhook. L'intestazione è nel formato "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 Dialogflow scambi un token di accesso dal provider OAuth e lo aggiunga nell'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. che può essere utilizzata 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 dell'agente di servizio per l'autenticazione. Può essere utilizzato per accedere ai servizi Cloud Function e Cloud Run. Se non vengono utilizzate altre opzioni di autenticazione, è abilitata per impostazione predefinita. |
Autenticazione TLS reciproca | Consulta la documentazione sull'autenticazione TLS reciproca. |
Verifica del certificato HTTPS
Per impostazione predefinita, Dialogflow utilizza l'archivio di attendibilità predefinito di Google per verificare i certificati HTTPS. Se intendi utilizzare certificati non riconosciuti dall'archivio di attendibilità predefinito di Google per il server HTTPS, ad esempio certificati autofirmati o certificati radice personalizzati, consulta la sezione Certificati CA personalizzati.
Webhook specifici dell’ambiente
Se utilizzi ambienti per isolare i sistemi di produzione dai sistemi di sviluppo (opzione consigliata), puoi configurare i webhook in modo che siano specifici per l'ambiente. Per ogni risorsa webhook che definisci, puoi fornire impostazioni di URL e autenticazione univoche per ogni ambiente definito per l'agente.
In questo modo puoi sviluppare e testare in modo sicuro gli aggiornamenti del codice webhook prima di eseguirne il deployment in produzione.
Creare o modificare le risorse webhook
Una volta in esecuzione un servizio webhook, devi creare una risorsa webhook nell'agente con informazioni sulla connettività e sull'autenticazione. Dopo la creazione, puoi anche modificare in qualsiasi momento le impostazioni delle risorse webhook.
Per creare o modificare una risorsa webhook:
Console
- Apri la console Dialogflow CX.
- Scegli il tuo progetto Google Cloud.
- Seleziona l'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, vedi il metodo create
per il tipo Webhook
.
Per modificare una risorsa webhook (ad eccezione delle impostazioni specifiche dell'ambiente), vedi 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 |
Go | 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, vedi il metodo patch
o update
per il tipo Environment
.
Seleziona un protocollo e una versione per il riferimento sull'ambiente:
Protocollo | V3 | V3beta1 |
---|---|---|
REST | Risorsa di ambiente | Risorsa di ambiente |
RPC | Interfaccia dell'ambiente | Interfaccia dell'ambiente |
C++ | EnvironmentsClient | Non disponibile |
C# | EnvironmentsClient | Non disponibile |
Go | 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 si verifica un errore durante la gestione di una richiesta webhook da parte del servizio webhook, il codice webhook dovrebbe restituire uno dei seguenti codici di stato HTTP:
400
richiesta non valida401
non autorizzato403
Vietato404
non trovato500
Errore del server- Servizio
503
non disponibile
In una qualsiasi delle seguenti situazioni di errore, Dialogflow richiama un errore o un timeout del webhook evento integrato e continua l'elaborazione come di consueto:
- Timeout risposta superato.
- 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'intent,
il campo queryResult.webhookStatuses
nella risposta di rilevamento dell'intent
contiene le informazioni sullo stato del webhook.
Utilizzo di Cloud Functions
Dialogflow si integra con Cloud Functions, per consentirti di creare facilmente un webhook serverless sicuro. Se crei una funzione che risiede nello stesso progetto dell'agente, l'agente può chiamare in modo sicuro il webhook senza bisogno di una configurazione speciale.
Tuttavia, esistono due situazioni in cui devi configurare manualmente questa integrazione:
- Per il progetto dell'agente deve esistere
l'account di servizio
dell'agente di servizio Dialogflow con il seguente indirizzo:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Questo account di servizio speciale e la chiave associata vengono generalmente creati automaticamente quando crei il primo agente per un progetto. Se l'agente è stato creato prima del 1° novembre 2020, puoi attivare la creazione di questo account di servizio speciale:- 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 Invoker di Cloud Functions ruolo IAM all'account di servizio della funzione agente di servizio Dialogflow.
Utilizzo di webhook containerizzati e del framework Go ezcx
Se vuoi implementare un webhook containerizzato utilizzando Go, consulta il framework Go ezcx. Questo framework può semplificare molti dei passaggi necessari durante la creazione di un webhook.
Utilizzo di Service Directory per l'accesso alla rete privata
Dialogflow si integra con l'accesso alla rete privata di Service Directory, per consentire la connessione alle destinazioni dei webhook all'interno della tua rete VPC. In questo modo il traffico all'interno della rete Google Cloud viene mantenuto e vengono applicati IAM e Controlli di servizio VPC.
Per configurare un webhook che abbia come target una rete privata:
Consulta la pagina relativa alla configurazione della rete privata di Service Directory per configurare la tua rete VPC e l'endpoint di Service Directory.
Per il progetto dell'agente deve esistere l'account di servizio dell'agente di servizio Dialogflow con il seguente indirizzo:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Concedi all'account di servizio dell'agente di servizio Dialogflow i seguenti ruoli IAM:servicedirectory.viewer
del progetto Service Directoryservicedirectory.pscAuthorizedService
del progetto di rete
Fornisci il servizio Service Directory insieme all'URL e alle informazioni di autenticazione facoltative durante la creazione del webhook.
Console
API
Controlla 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 Go 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.
Autenticazione agente di servizio
Dialogflow può generare un token ID o un token di accesso utilizzando l'agente di servizio Dialogflow.
Il token viene aggiunto nell'intestazione HTTP di autorizzazione quando Dialogflow chiama un webhook.
Token ID
Un token ID può essere utilizzato per accedere ai servizi Cloud Function e Cloud Run dopo aver concesso il ruolo Invoker a
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.comSe la funzione Cloud Function e i servizi Cloud Run si trovano nello stesso progetto di risorse, non hai bisogno di un'autorizzazione IAM aggiuntiva per chiamarli.
Il segmento di pubblico utilizzato per generare il token ID sarà l'intero URL webhook, tranne i parametri di query. Se utilizzi Cloud Run, assicurati che questo URL sia supportato dai segmenti di pubblico di Cloud Run. Ad esempio, se l'URL webhook è
https://myproject.cloudfunctions.net/my-function/method1?query=value
il seguente URL deve essere in segmenti di pubblico personalizzati.
https://myproject.cloudfunctions.net/my-function/method1
Qualsiasi webhook può anche convalidare il token utilizzando le librerie client di Google o le 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
Esempi e risoluzione dei problemi
Consulta la guida illustrativa del webhook.