Un webhook può essere un web webhook standard o un webhook flessibile. Con un webhook standard, i campi di richiesta e risposta sono definiti da Dialogflow. Con un webhook flessibile, devi definire i campi di richiesta e risposta.
Webhook standard
Con i webhook standard, utilizzi messaggi di richiesta e risposta definiti da Dialogflow. Il messaggio di richiesta fornisce molti dettagli sulla sessione. Ad esempio, pagina attiva corrente, intenzione corrispondente recente, sono inclusi i valori dei parametri di sessione e le risposte definite dall'agente.
Richiesta webhook standard
Quando
fulfillment
con un webhook,
Dialogflow invia una richiesta di webhook POST HTTPS al tuo servizio webhook.
Il corpo di questa richiesta è un oggetto JSON WebhookRequest
con informazioni sulla sessione.
Alcune
integrazioni
compila il campo WebhookRequest.payload
con informazioni aggiuntive.
Ad esempio,
Integrazione del gateway telefonico Dialogflow CX
fornisce l'ID chiamante dell'utente finale.
Consulta le
WebhookRequest
(V3)
o
WebhookRequest
(V3Beta1)
documentazione di riferimento per maggiori dettagli.
Risposta webhook standard
Quando il servizio webhook riceve una richiesta, deve inviare una risposta webhook. Alla tua risposta si applicano le seguenti limitazioni:
- La risposta deve avvenire entro un timeout che configuri durante la creazione della risorsa webhook, altrimenti la richiesta scadrà.
- La risposta deve essere inferiore o uguale a 64 KiB.
Consulta le
WebhookResponse
(V3)
o
WebhookResponse
(V3Beta1)
documentazione di riferimento per maggiori dettagli.
Impostazioni delle risorse webhook standard
Di seguito vengono descritte le impostazioni delle risorse webhook per i webhook standard:
Termine | Definizione |
---|---|
Nome visualizzato | Il nome visualizzato nella console per il webhook. |
Timeout webhook | Quando Dialogflow invia una richiesta webhook al tuo servizio webhook, questa potrebbe scadere in attesa di una risposta. Questa impostazione controlla il timeout in secondi. Se si verifica un timeout, Dialogflow richiama un evento webhook.error.timeout. |
Tipo | Imposta Service directory (Directory dei servizi) se utilizzi la directory dei servizi per l'accesso alla rete privata, altrimenti impostalo su 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 | Questo viene utilizzato per caricare i certificati CA personalizzati. |
Webhook flessibili
Con i webhook flessibili, devi 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 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 da i valori dei parametri di sessione tra un agente e un webhook. Semplifica inoltre l'implementazione del webhook, perché i messaggi di richiesta e risposta contengono solo ciò che e puoi 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 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 deve essere inviato 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 riferimenti ai parametri come faresti normalmente. Non è necessario eseguire l'escape dell'URL del riferimento al parametro, senza aggregare il riferimento tra virgolette. In fase di runtime, Dialogflow esegue l'URL di escape del valore parametro in base alle esigenze. Un elenco o un valore composito verrà fornito in formato JSON.
Quando utilizzi un riferimento a un parametro nel corpo JSON, devi racchiudere il riferimento tra virgolette, a prescindere dal tipo di parametro. Se il parametro è in realtà un valore scalare, di elenco o composto numerico, Dialogflow rimuoverà i preventivi durante l'invio della richiesta in fase di runtime per conservare il tipo di dati del parametro. I tipi scalari delle stringhe rimarranno tra virgolette. Se si fa riferimento a un valore scalare, elenco o composto numerico all'interno di un valore di stringa (ad esempio: "Questo è un numero: $session.params.size"), il parametro viene considerato come una stringa ("Questo è un numero: 3").
Ad esempio:
puoi fornire i valori dei parametri di sessione fruit
e size
all'URL della richiesta nel seguente modo:
https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size
E al corpo JSON della richiesta in questo modo:
{
"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 a campi specifici della risposta webhook in fase di runtime.
Alla tua risposta si applicano le seguenti limitazioni:
- La risposta deve avvenire entro un timeout che configuri durante la creazione della risorsa webhook, altrimenti la richiesta scadrà.
- La risposta deve essere inferiore o uguale a 64 KiB.
Utilizza il seguente formato per specificare un campo scalare, elenco o composto:
$.fully.qualified.path.to.field
Ad esempio: considera la seguente risposta JSON:
{
"routes" : [
{
"legs" : [
{
"distance" : {
"text" : "2,064 mi",
"value" : 3321004
}
}
]
}
]
}
Specificare il "valore" campo, utilizza quanto segue:
$.routes[0].legs[0].distance.value
Impostazioni delle risorse webhook flessibili
Di seguito vengono descritte le impostazioni delle risorse per i webhook flessibili:
Termine | Definizione |
---|---|
Nome visualizzato | Il nome visualizzato nella console per il webhook. |
Timeout webhook | Quando Dialogflow invia una richiesta webhook al tuo servizio webhook, questa potrebbe scadere in attesa di una risposta. Questa impostazione controlla il timeout in secondi. Se si verifica un timeout, Dialogflow richiama un evento webhook.error.timeout. |
Tipo | Imposta Service directory (Directory dei servizi) se utilizzi la directory dei servizi per l'accesso alla rete privata, altrimenti impostalo su Servizio web generico. |
URL webhook | Fornisci l'indirizzo URL per il 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 nei 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 | Questo viene utilizzato per caricare i certificati CA personalizzati. |
Utilizza un modello personalizzato predefinito
Dialogflow offre modelli personalizzati predefiniti che puoi utilizzare di integrare webhook flessibili con il CRM di Salesforce.
Nella scheda Gestisci, fai clic su Webhook, quindi 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 API. Il modello compila automaticamente il modulo webhook in base al nome dell'API che scegliere.
Puoi configurare manualmente i seguenti campi, se applicabile, in base a i parametri:
- URL webhook
- Metodo
- JSON del corpo della richiesta
- Configurazione della risposta
I campi OAuth obbligatori verranno evidenziati nella sezione Autenticazione. .
Fai clic su Salva per creare il webhook.
Requisiti del 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 un Computing o Serverless computing consulta la documentazione del prodotto per la pubblicazione con HTTPS. Per altre opzioni di hosting, consulta Ottieni 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 sia accessibile come webhook di Service Directory.
- Deve gestire le richieste e le risposte come descritto nei una sezione per un webhook standard o un webhook flessibile.
- Se l'agente non si integra con Accesso alla rete privata di Service Directory, le chiamate webhook sono considerate al di fuori del perimetro di servizio e sono bloccate quando abiliti i Controlli di servizio VPC. Service Directory supporta endpoint limitati. consulta le Service Directory per maggiori 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 dell'autenticazione | Per le impostazioni del webhook, puoi specificare coppie chiave-valore facoltative dell'intestazione HTTP. Se fornite, Dialogflow aggiunge queste intestazioni HTTP alle richieste webhook. È comune fornire una singola coppia con una chiave authorization . I valori di intestazione supportano i riferimenti dei 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 webhook, puoi specificare valori facoltativi per nome utente e password di accesso. Se fornita, Dialogflow aggiunge un'intestazione HTTP di autorizzazione alle richieste webhook. Questa intestazione è nel modulo: "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 di 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. 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 dell'agente di servizio per l'autenticazione. Può essere utilizzato per accedere alle funzioni di Cloud Run e ai servizi Cloud Run. |
Autenticazione TLS reciproca | Consulta la documentazione sull'autenticazione TLS reciproca. |
Verifica del certificato HTTPS
Dialogflow utilizza per impostazione predefinita l'archivio di attendibilità predefinito di Google per verificare il protocollo HTTPS certificati. Se intendi utilizzare certificati non riconosciuti da Google archivio di attendibilità predefinito per il server HTTPS, come i certificati autofirmati o certificati radice personalizzati, fai riferimento 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 dell'ambiente. Per ogni risorsa webhook che definisci, puoi fornire impostazioni di autenticazione e URL univoci per ogni ambiente che hai definito per l'agente.
Ciò ti consente di sviluppare e testare in modo sicuro gli aggiornamenti del codice dei webhook prima di eseguirne il deployment in produzione.
Crea o modifica risorse webhook
Quando un servizio webhook è in esecuzione, devi creare una risorsa webhook nel tuo agente che contiene informazioni di connettività e autenticazione. Dopo la creazione, puoi anche modificare le impostazioni delle risorse webhook in qualsiasi momento.
Per creare o modificare una risorsa webhook:
Console
- Apri la console Dialogflow CX.
- Scegli il progetto Google Cloud.
- Seleziona l'agente.
- Seleziona la scheda Gestisci.
- Fai clic su Webhook.
- Fai clic su Crea o fai clic su una risorsa webhook nell'elenco da modificare.
- Inserisci le impostazioni delle risorse webhook standard o 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),
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 |
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,
vedi il metodo patch
o update
per il tipo Environment
.
Seleziona un protocollo e una versione per il riferimento Ambiente:
Protocollo | V3 | V3beta1 |
---|---|---|
REST | Risorsa dell'ambiente | Risorsa dell'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 mentre gestisce una richiesta webhook il codice webhook deve restituire uno dei seguenti codici di stato HTTP:
400
Richiesta non valida401
non autorizzato403
Vietato404
non trovato500
Errore del server503
Servizio non disponibile
In una 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 di servizio webhook
è stato attivato da una chiamata API di rilevamento dell'intent,
Il campo queryResult.webhookStatuses
nella risposta di rilevamento dell'intent
contiene le informazioni sullo stato del webhook.
Utilizzo delle funzioni di Cloud Run
Dialogflow si integra con Funzioni di Cloud Run, per poter creare facilmente un webhook serverless e sicuro. Se crei una funzione che risiede nello stesso progetto del tuo agente, devi solo selezionare Service Agent Auth -> (Autenticazione agente di servizio) -> token ID nella configurazione di autenticazione, l'agente potrà quindi chiamare il webhook in modo sicuro.
Tuttavia, esistono due situazioni in cui devi configurare manualmente questa integrazione:
- L'agente di servizio Dialogflow
account di servizio
con il seguente indirizzo deve esistere per il tuo progetto agente:
Questo account di servizio speciale e la chiave associata di solito viene creato 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: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 l'invoker di Cloud Functions Ruolo IAM all'account di servizio dell'agente di servizio Dialogflow nel progetto della funzione.
- Seleziona Autorizzazione agente di servizio -> Token ID nella sezione di configurazione dell'autenticazione.
Utilizzo di webhook containerizzati e del framework Go ezcx
Se vuoi implementare un webhook containerizzato utilizzando Go, consulta Framework Go ezcx. Questo framework può semplificare molti dei passaggi necessari per creare un webhook.
Utilizzo delle funzioni di Cloud Run con traffico solo interno
Le funzioni di Cloud Run sono configurate per accettare il traffico interno dalle reti VPC nello stesso o lo stesso perimetro SC VPC può essere usato come webhook, purché nello stesso progetto o nello stesso perimetro SC VPC.
Utilizzo di Service Directory per l'accesso alla rete privata
Dialogflow si integra con Accesso alla rete privata di Service Directory, in modo che possa connettersi alle destinazioni webhook all'interno della tua rete VPC. In questo modo il traffico all'interno della rete Google Cloud applica in modo forzato IAM Controlli di servizio VPC.
Per impostare un webhook che abbia come target una rete privata:
Segui Configurazione della rete privata di Service Directory per configurare la rete VPC e l'endpoint di Service Directory.
L'agente di servizio Dialogflow account di servizio con il seguente indirizzo deve esistere per il tuo progetto agente:
Concedi all'account di servizio dell'agente di servizio Dialogflow 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 Service Directory insieme all'URL e 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 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 controllo di uptime privato per verificare che Service Directory sia configurato correttamente.
Autorizzazione agente di servizio
Dialogflow può generare token ID o token di accesso utilizzando 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 alle funzioni e ai servizi Cloud Run di 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 webhook, tranne eventuali parametri di ricerca. Se utilizzi Cloud Run, assicurati che questo URL sia supportato dai segmenti di pubblico Cloud Run. Ad esempio, se l'URL webhook è
https://myproject.cloudfunctions.net/my-function/method1?query=value
il seguente URL deve trovarsi in segmenti di pubblico personalizzati.
https://myproject.cloudfunctions.net/my-function/method1
Qualsiasi webhook può anche convalidare il token utilizzando librerie client di Google o librerie open source, 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
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Esempi e risoluzione dei problemi
Consulta le guida illustrativa sul webhook.