Per utilizzare l'evasione degli ordini in un sistema di produzione, devi implementare ed eseguire il deployment di un servizio webhook. Per gestire il fulfillment, il servizio webhook deve accettare richieste JSON e restituiscono risposte JSON come specificato in questa guida. Il flusso di elaborazione dettagliato per fulfillment e webhook è descritto nel documento di panoramica dell'evasione degli ordini.
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.
- Deve gestire le richieste POST con un file JSON.
WebhookRequest
del testo. - Deve rispondere alle richieste
WebhookRequest
con un file JSON.WebhookResponse
del testo.
Autenticazione
È importante proteggere il servizio webhook, in modo che solo tu o il tuo agente Dialogflow siate autorizzati a effettuare richieste. Dialogflow supporta i seguenti meccanismi per l'autenticazione:
Termine | Definizione |
---|---|
Nome utente e password di accesso | 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>" . |
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 . |
Autenticazione integrata di Cloud Functions | Quando usi Cloud Functions, puoi utilizzare l'autenticazione integrata. Per utilizzare questo tipo di autenticazione, non fornire il nome utente, la password di accesso o le intestazioni di autorizzazione. Se fornisci uno di questi campi, questi verranno utilizzati per l'autenticazione anziché per l'autenticazione integrata. |
Token di identità del servizio | Puoi utilizzare i token di identità del servizio per l'autenticazione. Se non fornisci il nome utente, la password di accesso o un'intestazione con una chiave authorization , Dialogflow presuppone automaticamente che si debbano utilizzare token di identità del servizio e aggiunge un'intestazione HTTP di autorizzazione alle richieste webhook. Questa intestazione è nel modulo: "authorization: Bearer <identity token>" . |
Autenticazione TLS reciproca | Consulta la documentazione sull'autenticazione TLS reciproca. |
Richiesta webhook
Quando viene trovata una corrispondenza con un intent configurato per il completamento, Dialogflow invia una richiesta di webhook POST HTTPS al tuo servizio webhook. Il corpo di questa richiesta è un oggetto JSON con informazioni sull'intent abbinato.
Oltre alla query dell'utente finale, molte integrazioni inviano anche
informazioni sull'utente finale. Ad esempio, un ID per identificare in modo univoco
per l'utente. È possibile accedere a queste informazioni tramite il originalDetectIntentRequest
nella richiesta webhook, che conterrà le informazioni inviate dal
completamente gestita.
Consulta le
WebhookRequest
documentazione di riferimento per maggiori dettagli.
Ecco un esempio di richiesta:
{ "responseId": "response-id", "session": "projects/project-id/agent/sessions/session-id", "queryResult": { "queryText": "End-user expression", "parameters": { "param-name": "param-value" }, "allRequiredParamsPresent": true, "fulfillmentText": "Response configured for matched intent", "fulfillmentMessages": [ { "text": { "text": [ "Response configured for matched intent" ] } } ], "outputContexts": [ { "name": "projects/project-id/agent/sessions/session-id/contexts/context-name", "lifespanCount": 5, "parameters": { "param-name": "param-value" } } ], "intent": { "name": "projects/project-id/agent/intents/intent-id", "displayName": "matched-intent-name" }, "intentDetectionConfidence": 1, "diagnosticInfo": {}, "languageCode": "en" }, "originalDetectIntentRequest": {} }
Risposta webhook
Quando il webhook riceve una richiesta, deve inviare una risposta webhook. Il corpo di questa risposta è un oggetto JSON con le seguenti informazioni:
- La risposta che Dialogflow restituisce all'utente finale.
- Aggiornamenti ai contesti attivo per la conversazione.
- Un evento di follow-up per attivare una corrispondenza di intent.
- Un payload personalizzato da inviare all'integrazione o rileva client per intenzione
Alla tua risposta si applicano le seguenti limitazioni:
- La risposta deve verificarsi entro 10 secondi per Assistente Google applicazioni o cinque secondi per tutte le altre applicazioni, altrimenti la richiesta scadrà.
- La risposta deve essere inferiore o uguale a 64 KiB.
Consulta le
WebhookResponse
documentazione di riferimento per maggiori dettagli.
Messaggio di risposta
Esempio per una risposta testuale:
{ "fulfillmentMessages": [ { "text": { "text": [ "Text response from webhook" ] } } ] }
Risposta della scheda
Esempio per una card response:
{ "fulfillmentMessages": [ { "card": { "title": "card title", "subtitle": "card text", "imageUri": "https://example.com/images/example.png", "buttons": [ { "text": "button text", "postback": "https://example.com/path/for/end-user/to/follow" } ] } } ] }
Risposta dell'Assistente Google
Esempio per una Risposta dell'Assistente Google:
{ "payload": { "google": { "expectUserResponse": true, "richResponse": { "items": [ { "simpleResponse": { "textToSpeech": "this is a Google Assistant response" } } ] } } } }
Contesto
Esempio che imposta contesto di output:
{ "fulfillmentMessages": [ { "text": { "text": [ "Text response from webhook" ] } } ], "outputContexts": [ { "name": "projects/project-id/agent/sessions/session-id/contexts/context-name", "lifespanCount": 5, "parameters": { "param-name": "param-value" } } ] }
Evento
Esempio che richiama un evento personalizzato:
{ "followupEventInput": { "name": "event-name", "languageCode": "en-US", "parameters": { "param-name": "param-value" } } }
Entità sessione
Esempio che imposta un session entity:
{ "fulfillmentMessages": [ { "text": { "text": [ "Choose apple or orange" ] } } ], "sessionEntityTypes":[ { "name":"projects/project-id/agent/sessions/session-id/entityTypes/fruit", "entities":[ { "value":"APPLE_KEY", "synonyms":[ "apple", "green apple", "crabapple" ] }, { "value":"ORANGE_KEY", "synonyms":[ "orange" ] } ], "entityOverrideMode":"ENTITY_OVERRIDE_MODE_OVERRIDE" } ] }
Payload personalizzato
Esempio che fornisce un payload personalizzato:
{ "fulfillmentMessages": [ { "payload": { "facebook": { // for Facebook Messenger integration "attachment": { "type": "", "payload": {} } }, "slack": { // for Slack integration "text": "", "attachments": [] }, "richContent": [ // for Dialogflow Messenger integration [ { "type": "image", "rawUrl": "https://example.com/images/logo.png", "accessibilityText": "Example logo" } ] ], // custom integration payload here } } ] }
Abilita e gestisci il fulfillment
Per abilitare e gestire il fulfillment per il tuo agente tramite la console:
- Vai alla console Dialogflow ES.
- Seleziona un agente.
- Seleziona Fulfillment nel menu della barra laterale sinistra.
- Imposta il campo Webhook su Attivato.
- Fornisci i dettagli del servizio webhook nel modulo. Se il webhook non richiede l'autenticazione, lascia vuoti i campi di autenticazione.
- Fai clic su Salva nella parte inferiore della pagina.
Per abilitare e gestire il fulfillment per il tuo agente con l'API,
vedi il
riferimento agente.
I metodi getFulfillment
e updateFulfillment
possono
per gestire le impostazioni di evasione degli ordini.
Per abilitare il completamento per un intent con la console:
- Seleziona Intent nel menu della barra laterale a sinistra.
- Seleziona un intent.
- Scorri verso il basso fino alla sezione Completamento.
- Attiva l'opzione Abilita chiamata webhook per questo intent.
- Fai clic su Salva.
Per abilitare il completamento di un intent con l'API,
vedi il
riferimento agli intent.
Imposta il campo webhookState
su WEBHOOK_STATE_ENABLED
.
Errori webhook
Se il servizio webhook rileva un errore, dovrebbe essere restituito 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 risponde all'utente finale con risposta configurata per l'intent attualmente corrispondente:
- Timeout risposta superato.
- Codice di stato di errore ricevuto.
- La risposta non è valida.
- Il servizio webhook non è disponibile.
Inoltre, se la corrispondenza di intenzione è stata attivata da un
rilevamento della chiamata all'API,
Il campo status
nella risposta di rilevamento dell'intent contiene le informazioni sull'errore del webhook. Ad esempio:
"status": {
"code": 206,
"message": "Webhook call failed. <details of the error...>"
}
Utilizzo di Cloud Functions
Esistono alcuni modi per utilizzare Cloud Functions per il completamento. Dialogflow editor in linea si integra con Cloud Functions. Quando utilizzi l'editor in linea per creare e modificare il codice webhook, Dialogflow stabilisce una connessione sicura alla tua Cloud Function.
Hai anche la possibilità di utilizzare una Cloud Function non creata dall'editor in linea (forse perché vuoi utilizzare un linguaggio diverso da Node.js). Se la Cloud Function risiede nello stesso progetto dell'agente, quest'ultimo può chiamare il webhook senza bisogno di una configurazione speciale.
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:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Questo account di servizio speciale e la chiave associata di solito viene creato automaticamente quando crei il primo agente per un progetto. Se il tuo agente è stato creato prima del 10 maggio 2021, potresti dover attivare la creazione di questo account di servizio speciale con quanto segue:- 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.
Token di identità del servizio
Quando Dialogflow chiama un webhook, fornisce un'interfaccia
Token di identità Google
con la richiesta.
Qualsiasi webhook può, facoltativamente, convalidare il token
utilizzando librerie client di Google o librerie open source,
github.com/googleapis/google-auth-library-nodejs.
Ad esempio, puoi verificare il valore email
del token ID come:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Esempi
I seguenti esempi mostrano come ricevere un WebhookRequest
e invia WebhookResponse
.
Questi esempi fanno riferimento agli intent creati nell'
guida rapida.
Go
Per eseguire l'autenticazione in Dialogflow, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
import ( "encoding/json" "fmt" "log" "net/http" ) type intent struct { DisplayName string `json:"displayName"` } type queryResult struct { Intent intent `json:"intent"` } type text struct { Text []string `json:"text"` } type message struct { Text text `json:"text"` } // webhookRequest is used to unmarshal a WebhookRequest JSON object. Note that // not all members need to be defined--just those that you need to process. // As an alternative, you could use the types provided by // the Dialogflow protocol buffers: // https://godoc.org/google.golang.org/genproto/googleapis/cloud/dialogflow/v2#WebhookRequest type webhookRequest struct { Session string `json:"session"` ResponseID string `json:"responseId"` QueryResult queryResult `json:"queryResult"` } // webhookResponse is used to marshal a WebhookResponse JSON object. Note that // not all members need to be defined--just those that you need to process. // As an alternative, you could use the types provided by // the Dialogflow protocol buffers: // https://godoc.org/google.golang.org/genproto/googleapis/cloud/dialogflow/v2#WebhookResponse type webhookResponse struct { FulfillmentMessages []message `json:"fulfillmentMessages"` } // welcome creates a response for the welcome intent. func welcome(request webhookRequest) (webhookResponse, error) { response := webhookResponse{ FulfillmentMessages: []message{ { Text: text{ Text: []string{"Welcome from Dialogflow Go Webhook"}, }, }, }, } return response, nil } // getAgentName creates a response for the get-agent-name intent. func getAgentName(request webhookRequest) (webhookResponse, error) { response := webhookResponse{ FulfillmentMessages: []message{ { Text: text{ Text: []string{"My name is Dialogflow Go Webhook"}, }, }, }, } return response, nil } // handleError handles internal errors. func handleError(w http.ResponseWriter, err error) { w.WriteHeader(http.StatusInternalServerError) fmt.Fprintf(w, "ERROR: %v", err) } // HandleWebhookRequest handles WebhookRequest and sends the WebhookResponse. func HandleWebhookRequest(w http.ResponseWriter, r *http.Request) { var request webhookRequest var response webhookResponse var err error // Read input JSON if err = json.NewDecoder(r.Body).Decode(&request); err != nil { handleError(w, err) return } log.Printf("Request: %+v", request) // Call intent handler switch intent := request.QueryResult.Intent.DisplayName; intent { case "Default Welcome Intent": response, err = welcome(request) case "get-agent-name": response, err = getAgentName(request) default: err = fmt.Errorf("Unknown intent: %s", intent) } if err != nil { handleError(w, err) return } log.Printf("Response: %+v", response) // Send response if err = json.NewEncoder(w).Encode(&response); err != nil { handleError(w, err) return } }
Java
Per eseguire l'autenticazione in Dialogflow, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Dialogflow, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione in Dialogflow, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.