La libreria client Actions on Google Node.js è il modo consigliato per accedere e interagire con la piattaforma Actions on Google se stai creando un webhook di fulfillment in JavaScript.
Introduzione
La libreria client Node.js è una libreria di distribuzione per Actions on Google che offre le seguenti funzionalità:
- Supporta tutte le funzionalità di Actions on Google, inclusi testo e risposte multimediali, accesso all'account, archiviazione dati, transazioni e altro ancora.
- Fornisce un livello di astrazione idiomatico in JavaScript che esegue il wrapping dell'API webhook HTTP/JSON conversazione.
- Gestisce i dettagli di basso livello della comunicazione tra il fulfillment e la piattaforma Actions on Google.
- Può essere installato utilizzando strumenti di gestione dei pacchetti familiari, come
npm
oyarn
. - Consente di eseguire facilmente il deployment del webhook di fulfillment su piattaforme di serverless computing come Cloud Functions for Firebase o AWS Lambda. Puoi anche ospitare il webhook di fulfillment in un provider di servizi cloud o in un ambiente self-hosted e autogestito.
- È compatibile con Node.js 6.0.0 e versioni successive.
Puoi utilizzare la libreria client in combinazione con l'integrazione Dialogflow per Actions on Google o con l'SDK Actions.
Per visualizzare esempi di codice completi per l'utilizzo della libreria client, puoi visitare la pagina degli esempi.
Visualizza il riferimento API
Il riferimento API è ospitato nella pagina di GitHub della libreria client Node.js di Actions on Google.
Puoi anche generare una copia locale del riferimento eseguendo questo comando dalla directory in cui hai scaricato il codice della libreria client:
yarn docs
I documenti generati saranno disponibili nella cartella docs
della directory
in cui hai scaricato il codice della libreria client.
Scopri come funziona
Prima di utilizzare la libreria client, è utile capire in che modo il webhook di fulfillment utilizza la libreria client per elaborare le richieste degli utenti che Actions on Google invia al tuo fulfillment.
Quando crei un webhook di fulfillment in JavaScript, puoi eseguire il deployment e ospitare il codice in un ambiente di serverless computing come Cloud Functions for Firebase di Google o AWS Lambda. Puoi anche ospitare il codice autonomamente senza attività aggiuntive utilizzando il framework web Express.
Nell'ambiente di runtime, il webhook di fulfillment può chiamare le funzioni nella libreria client per elaborare le richieste degli utenti e inviare le risposte ad Actions on Google per il rendering nell'output utente.
Di seguito sono riepilogate brevemente le attività principali che il webhook di fulfillment gestisce con l'aiuto della libreria client:
- Ricezione delle richieste degli utenti: quando un utente esegue una query all'Assistente Google, la piattaforma Actions on Google invia una richiesta HTTP al webhook di fulfillment; la richiesta include un payload JSON che contiene l'intent e altri dati, come il testo non elaborato dell'input utente e le funzionalità di visualizzazione del dispositivo dell'utente. Per altri esempi di contenuti del payload JSON, consulta le guide relative al formato webhook di Dialogflow e al formato di webhook per conversazione.
- Rilevamento del formato di chiamata del framework: per i framework supportati, la libreria client rileva automaticamente il formato di chiamata del framework (ad esempio, se la richiesta proviene dal framework web Express o da AWS Lambda) e sa come gestire senza problemi la comunicazione con la piattaforma Actions on Google.
- Elaborazione del gestore di servizi: la libreria client rappresenta l'API webhook HTTP/JSON della conversazione per Dialogflow e l'SDK Actions come funzione di servizio. Il webhook di fulfillment utilizza il servizio appropriato per creare un'istanza
app
globale. L'istanzaapp
agisce da gestore per le richieste HTTP e comprende il protocollo specifico del servizio. - Elaborazione della conversazione: la libreria client rappresenta le informazioni per conversazione come un oggetto
Conversation
associato all'istanzaapp
. Il webhook di fulfillment può utilizzare l'oggettoConversation
per recuperare dati o informazioni sullo stato archiviati in più conversazioni, inviare risposte agli utenti o chiudere il microfono. - Elaborazione del middleware: la libreria client consente di creare il tuo middleware dei servizi di conversazione, composto da una o più funzioni definite automaticamente dalla libreria client prima di chiamare il gestore di intent. Il webhook di fulfillment può utilizzare il middleware per aggiungere proprietà o classi helper all'oggetto
Conversation
. - Elaborazione del gestore di intent: la libreria client consente di definire i gestori per gli intent riconosciuti dal webhook di fulfillment. Per Dialogflow, la libreria client instrada la richiesta al gestore di intent corretto eseguendo la mappatura alla stringa esatta del nome dell'intent definito nella console Dialogflow. Per l'SDK Actions, il routing viene eseguito in base alla proprietà
intent
inviata da Actions on Google. - Invio di risposte agli utenti: per creare le risposte, il webhook di fulfillment
chiama la funzione
Conversation#ask()
. La funzioneask()
può essere chiamata più volte per creare la risposta in modo incrementale. La libreria client serializza la risposta in una richiesta HTTP con un payload JSON e la invia ad Actions on Google. La funzioneclose()
ha un comportamento simile aask()
, ma chiude la conversazione.
Configura l'ambiente di sviluppo locale
Prima di implementare il webhook di fulfillment, assicurati di installare la libreria client.
Installa la libreria client
Il modo più semplice per installare la libreria client nell'ambiente di sviluppo locale consiste nell'utilizzare un gestore di pacchetti, come npm
o yarn
.
Per eseguire l'installazione, esegui uno di questi comandi dal terminale:
- Se utilizzi npm:
npm install actions-on-google
- Se si utilizza il filato:
yarn add actions-on-google
Configura le cartelle di progetto
A seconda di dove prevedi di eseguire il deployment del webhook di fulfillment (Cloud Functions for Firebase di Google, AWS Lambda o Express in self-hosted), potrebbe essere necessario creare una struttura di cartelle di progetto specifica per salvare i file.
Ad esempio, se utilizzi Cloud Functions for Firebase, puoi configurare le cartelle di progetto necessarie eseguendo i passaggi descritti in Configurare Node.js e l'interfaccia a riga di comando di Firebase e Inizializzare Firebase per Cloud Functions. Per Cloud Functions for Firebase, in genere scrivi il webhook di fulfillment nel file /functions/index.js
.
Crea un'istanza dell'app
Actions on Google utilizza formati di messaggistica specifici per lo scambio di richieste e risposte con il webhook di fulfillment, a seconda che tu stia creando un'azione conversazionale utilizzando Dialogflow o l'SDK Actions oppure creando un'azione per la smart home.
Per rappresentare questi diversi protocolli di richiesta e risposta, la libreria client fornisce tre funzioni di servizio:
Il protocollo webhook di conversazione viene utilizzato da entrambi i servizi di conversazione (Dialogflow e SDK Actions), ma ogni servizio esegue il wrapping dei messaggi in modo diverso.
Utilizza un servizio per creare un'istanza app
. L'istanza app
incapsula lo stato globale e la logica di fulfillment per il webhook e gestisce la comunicazione tra Actions on Google e il fulfillment utilizzando il protocollo specifico per il servizio.
Puoi configurare le proprietà dell'istanza app
e chiamare i relativi metodi per indirizzare il comportamento del webhook di fulfillment. Puoi anche collegare facilmente l'istanza app
a un ambiente di serverless computing come Cloud Functions for Firebase, che accetta le funzioni JavaScript come gestori delle richieste HTTP.
Per creare un'istanza app
nel webhook di fulfillment:
Richiama la funzione
require()
per importare il modulo "actions-on-google" e caricare il servizio che ti interessa. Ad esempio, lo snippet seguente mostra come caricare il serviziodialogflow
e alcuni elementi utilizzati per creare le risposte e assegnarlo a una costante denominatadialogflow
:// Import the service function and various response classes const { dialogflow, actionssdk, Image, Table, Carousel, } = require('actions-on-google');
In questo caso,
actions-on-google
fa riferimento a una dipendenza specificata in un filepackage.json
nella cartella del progetto (per un esempio, fai riferimento a questo filepackage.json
di esempio).Quando ottieni un'istanza
app
, puoi specificare facoltativamente classi che rappresentano risposte avanzate, intent helper e altre funzionalità di Actions on Google che vuoi utilizzare. Per l'elenco completo delle classi valide che puoi caricare, consulta la documentazione di riferimento per i moduli di risposta alla conversazione e intent helper.Crea un'istanza
app
chiamando il servizio che hai caricato. Ad esempio:const app = dialogflow();
Per configurare l'istanza
app
all'inizializzazione, puoi fornire un oggettooptions
come primo argomento quando chiami il servizio. (Per ulteriori dettagli, visita la paginaDialogflowOptions
). Ad esempio, lo snippet seguente mostra come registrare il payload JSON non elaborato dalla richiesta o dalla risposta dell'utente impostando il flag{ debug: true }
:
const app = dialogflow({ debug: true });
Imposta gestori per gli eventi
Per elaborare gli eventi relativi alle azioni su Google creati dalla libreria client durante il ciclo di vita dell'interazione dell'utente con l'Azione, utilizzerai la libreria client per creare gestori al fine di elaborare le richieste degli utenti e inviare le risposte.
Puoi creare funzioni che fungono da gestori per i seguenti tipi principali di eventi riconosciuti dalla libreria client:
- Eventi di intent: gli intent sono identificatori univoci che Actions on Google invia al tuo fulfillment ogni volta che un utente richiede una funzionalità specifica. Se utilizzi Dialogflow, questo corrisponde a una query utente che corrisponde a un intent nell'agente Dialogflow.
- Eventi di errore: quando si verifica un errore JavaScript o della libreria client, puoi utilizzare la funzione
catch
dell'istanzaapp
per elaborare l'eccezione di errore in modo appropriato. Devi implementare una singola funzionecatch
per gestire tutti gli errori che interessano il tuo fulfillment. - Eventi di riserva: si verifica un evento di riserva quando l'utente invia una query che Actions on Google non è in grado di riconoscere. Puoi utilizzare la funzione
fallback
dell'istanzaapp
per registrare un gestore di fallback generico che verrà attivato se non viene abbinato alcun gestore di intent per la richiesta di evasione degli ordini in entrata. Devi implementare una singola funzionefallback
per gestire tutti gli eventi di fallback. Se utilizzi Dialogflow, quest'ultimo può attivare un intent di riserva specifico quando non viene abbinato nessun altro intent. Devi creare un gestore di intent corrispondente per l'intent di riserva.
Ogni volta che l'utente invia una richiesta all'Azione, l'istanza app
crea un oggetto Conversation
che rappresenta la sessione di conversazione. Questo oggetto è accessibile tramite il nome della variabile conv
passato nella funzione di gestore di intent come primo argomento della funzione. In genere, utilizzerai l'oggetto conv
nei gestori per inviare una risposta all'utente.
Le query degli utenti possono anche includere parametri che l'Azione può estrarre e utilizzare per perfezionare le risposte.
- Se utilizzi l'SDK Actions, definisci i parametri nel pacchetto Action. Per un esempio di come estrarre i parametri dagli intent, vedi l'esempio di codice Eliza.
- Se utilizzi Dialogflow, puoi accedere ai valori dei parametri tramite la variabile
params
. Per esempi sulla gestione di intent con parametri in Dialogflow, vedi Accedere a parametri e contesti.
Imposta gestori per gli intent
Per impostare il gestore per un intent, chiama la funzione intent()
dell'istanza app
. Ad esempio, se utilizzi Dialogflow, questa è la funzione DialogflowApp#intent()
. Negli argomenti, specifica il nome dell'intent e fornisci una funzione gestore.
Se utilizzi Dialogflow, non è necessario impostare gestori per ogni intent nell'agente. Puoi invece sfruttare il gestore delle risposte integrato di Dialogflow per gestire automaticamente gli intent senza implementare le tue funzioni di gestore. Ad esempio, l'intent di benvenuto predefinito può essere delegato a Dialogflow in questo modo.
L'esempio seguente mostra i gestori di intent per gli intent "greeting" e "bye". Le funzioni di gestore anonimo prendono un argomento conv
e inviano una semplice risposta stringa all'utente tramite la funzione conv.ask()
:
app.intent('Default Welcome Intent', (conv) => { conv.ask('How are you?'); }); app.intent('bye', (conv) => { conv.close('See you later!'); });
Tieni presente che la funzione close()
è simile alla funzione ask()
, ma chiude il microfono e la conversazione è terminata.
Per scoprire di più su come creare gestori per gli intent, consulta Creare un gestore di intent.
Imposta gestori per gli eventi di errore
Per impostare i gestori per gli errori, chiama la funzione catch()
dell'istanza app
. Ad esempio, se utilizzi Dialogflow, questa è la funzione DialogflowApp#catch()
.
L'esempio seguente mostra un semplice gestore di errori catch che invia l'errore all'output della console e invia una semplice risposta stringa per richiedere all'utente tramite la funzione conv.ask()
:
app.catch((conv, error) => { console.error(error); conv.ask('I encountered a glitch. Can you say that again?'); });
Imposta gestori per gli eventi di fallback
Per impostare un gestore di riserva generico quando non esiste alcuna corrispondenza di intent per la richiesta in arrivo per il fulfillment, chiama la funzione fallback()
della tua istanza app
. Ad esempio, se utilizzi Dialogflow, questa è la funzione DialogflowApp#fallback()
.
L'esempio seguente mostra un semplice gestore di riserva che invia una semplice risposta stringa per richiedere all'utente tramite la funzione conv.ask()
:
app.fallback((conv) => { conv.ask(`I couldn't understand. Can you say that again?`); });
Creare il gestore di intent
Questa sezione illustra alcuni casi d'uso comuni in cui implementi gestori di intent con la libreria client. Per vedere in che modo la libreria client corrisponde all'intent, consulta la sezione "Elaborazione del gestore di intent" in Comprendere il funzionamento.
Parametri di accesso e contesti
Se utilizzi Dialogflow, puoi definire parametri e contesti nell'agente Dialogflow per mantenere le informazioni sullo stato e controllare il flusso della conversazione.
I parametri sono utili per acquisire parole, frasi o valori importanti nelle query degli utenti. Dialogflow estrae i parametri corrispondenti dalle query degli utenti in fase di runtime e puoi elaborare questi valori parametro nel webhook di fulfillment per determinare come rispondere agli utenti.
Ogni volta che l'utente invia una richiesta all'azione, l'istanza DialogflowApp
crea un oggetto parameters
che rappresenta i valori parametro che Dialogflow ha estratto dalla richiesta. Questo oggetto è accessibile tramite il nome della variabile params
.
Lo snippet seguente mostra come accedere alla proprietà name
dall'oggetto params
quando l'utente invia una richiesta:
app.intent('Default Welcome Intent', (conv, params) => { conv.ask(`How are you, ${params.name}?`); });
Di seguito è riportato uno snippet alternativo che ha lo stesso comportamento. Le parentesi graffe
({}
) eseguono la distruzione JavaScript
per prendere la proprietà name
dall'oggetto parameters
e utilizzarla come variabile
locale:
app.intent('Default Welcome Intent', (conv, {name}) => { conv.ask(`How are you, ${name}?`); });
Nello snippet seguente, il nome del parametro è full-name
ma è
destrutturato e assegnato a una variabile locale denominata name
:
app.intent('Default Welcome Intent', (conv, {'full-name': name}) => { conv.ask(`How are you, ${name}?`); });
I contesti sono una funzionalità avanzata di Dialogflow. Puoi utilizzare i contesti per gestire lo stato, il flusso e
il branching della conversazione. La libreria client fornisce l'accesso a un contesto tramite l'oggetto DialogflowConversation#contexts
. Lo snippet seguente mostra come impostare un contesto in modo programmatico nel webhook di fulfillment e come recuperare l'oggetto di contesto:
app.intent('intent1', (conv) => { const lifespan = 5; const contextParameters = { color: 'red', }; conv.contexts.set('context1', lifespan, contextParameters); // ... conv.ask('...'); }); app.intent('intent2', (conv) => { const context1 = conv.contexts.get('context1'); const contextParameters = context1.parameters; // ... conv.ask('...'); }); app.intent('intent3', (conv) => { conv.contexts.delete('context1'); // ... conv.ask('...'); });
Accedi ai risultati dell'intent helper
Per praticità, la libreria client fornisce classi di intent helper che aggregano tipi comuni di dati utente richiesti di frequente dalle Azioni. tra cui classi che rappresentano i risultati dei vari intent helper di Actions on Google. Puoi utilizzare intent helper quando vuoi che l'Assistente Google gestisca parti della conversazione in cui l'utente deve fornire input per continuare la conversazione.
Esempio: risultati dell'helper per la conferma
L'intent helper conferma ti consente di chiedere una conferma sì/no da parte dell'utente e ottenere la risposta risultante.
Lo snippet seguente mostra in che modo il webhook può personalizzare la risposta in base ai risultati restituiti dall'intent helper di conferma. Per un esempio più completo, consulta la documentazione di riferimento della classe Confirmation
.
// Create Dialogflow intent with `actions_intent_CONFIRMATION` event app.intent('get_confirmation', (conv, input, confirmation) => { if (confirmation) { conv.close(`Great! I'm glad you want to do it!`); } else { conv.close(`That's okay. Let's not do it now.`); } });
Esempio: risultati relativi a carosello
Lo snippet seguente mostra in che modo il webhook di fulfillment può personalizzare la propria risposta in base all'input dell'utente per un carosello. Il componente Carousel consente all'Azione
di presentare una selezione di opzioni. Per un esempio più completo, consulta la documentazione di riferimento della classe Carousel
.
app.intent('carousel', (conv) => { conv.ask('Which of these looks good?'); conv.ask(new Carousel({ items: { car: { title: 'Car', description: 'A four wheel vehicle', synonyms: ['automobile', 'vehicle'], }, plane: { title: 'Plane', description: 'A flying machine', synonyms: ['aeroplane', 'jet'], } } })); }); // Create Dialogflow intent with `actions_intent_OPTION` event app.intent('get_carousel_option', (conv, input, option) => { if (option === 'one') { conv.close(`Number one is a great choice!`); } else { conv.close(`Number ${option} is a great choice!`); } });
Configura oggetti risposta conversazione
La libreria client fornisce classi di risposta alle conversazioni che rappresentano risposte avanzate o elementi multimediali che l'Azione può inviare. In genere, invii queste risposte o questi elementi quando gli utenti non devono dare alcun input per continuare la conversazione.
Esempio: immagine
Lo snippet seguente mostra in che modo il webhook di fulfillment può inviare un elemento Image
in una risposta che verrà allegata automaticamente a una risposta BasicCard
dalla libreria:
app.intent('Default Welcome Intent', (conv) => { conv.ask('Hi, how is it going?'); conv.ask(`Here's a picture of a cat`); conv.ask(new Image({ url: '/web/fundamentals/accessibility/semantics-builtin/imgs/160204193356-01-cat-500.jpg', alt: 'A cat', })); });
Effettuare chiamate di funzioni asincrone
La libreria client Node.js di Actions on Google è progettata per la programmazione asincrona. Il gestore di intent può restituire una promessa che si risolve quando il webhook di fulfillment genera una risposta.
Lo snippet seguente mostra come effettuare una chiamata di funzione asincrona per restituire un oggetto promessa e quindi rispondere con un messaggio se il webhook di fulfillment riceve l'intent di saluto. In questo snippet, la promessa garantisce che il webhook di fulfillment restituisca una risposta conversazionale solo dopo la risoluzione della promessa relativa alla chiamata API esterna.
In questo esempio, utilizziamo un'API falsa per recuperare i dati meteo.
/** * Make an external API call to get weather data. * @return {Promise<string>} */ const forecast = () => { // ... }; app.intent('Default Welcome Intent', (conv) => { return forecast().then((weather) => { conv.ask('How are you?'); conv.ask(`Today's weather is ${weather}.`); }); });
Il seguente snippet di codice semplificato ha lo stesso effetto, ma utilizza la funzionalità async
await
introdotta in ECMA 2017 (Node.js versione 8). Per utilizzare questo codice con Cloud Functions for Firebase, assicurati di utilizzare la versione corretta di firebase-tools e di avere la configurazione corretta.
app.intent('Default Welcome Intent', async (conv) => { const weather = await forecast(); conv.ask('How are you?'); conv.ask(`Today's weather is ${weather}.`); });
Archivia dati conversazionali
La libreria client consente al webhook di fulfillment di salvare i dati nelle conversazioni per utilizzarli in futuro. Gli oggetti chiave che puoi utilizzare per l'archiviazione dei dati includono:
DialogflowConversation#data
oActionsSdkConversation#data
: salva i dati in formato JSON per la durata di una singola sessione di conversazione tra l'utente e l'Azione.Conversation#user.storage
: salva i dati in formato JSON in più sessioni di conversazione.
Lo snippet seguente mostra in che modo il webhook di fulfillment può archiviare i dati in una proprietà arbitraria che hai definito (someProperty
) e collegarli all'oggetto Conversation#user.storage
. Per un esempio più completo, consulta la documentazione di riferimento della classe Conversation#user.storage
.
app.intent('Default Welcome Intent', (conv) => { conv.user.storage.someProperty = 'someValue'; conv.ask('...'); });
Puoi utilizzare l'oggetto Conversation#user
per ottenere informazioni sull'utente, inclusi un identificatore di stringa e informazioni personali. Determinati campi, come conv.user.name.display
e conv.user.email
, richiedono, rispettivamente, la richiesta di conv.ask(new Permission)
per NAME e conv.ask(new SignIn)
per Accedi con Google.
const {Permission} = require('actions-on-google'); app.intent('Default Welcome Intent', (conv) => { if (conv.user.last.seen) { conv.ask('Welcome back! How are you?'); } else { conv.ask('Nice to meet you! How are you doing?'); } }); app.intent('permission', (conv) => { conv.ask(new Permission({ context: 'To greet you personally', permissions: 'NAME', })); }); // Create Dialogflow intent with `actions_intent_PERMISSION` event app.intent('get_permission', (conv, input, granted) => { if (granted) { conv.close(`Hi ${conv.user.name.display}!`); } else { // User did not grant permission conv.close(`Hello!`); } });
Scalabilità con il middleware
Puoi estendere la libreria client tramite il middleware.
Il livello middleware è costituito da una o più funzioni definite da te, che la libreria client esegue automaticamente prima di chiamare il gestore di intent. L'utilizzo di un livello middleware consente di modificare l'istanza Conversation
e aggiungere funzionalità aggiuntive.
I servizi Dialogflow e Actions SDK espongono una funzione app.middleware()
che ti consente di aggiungere proprietà o classi helper all'istanza Conversation
.
Lo snippet seguente mostra un esempio di come utilizzare il middleware:
class Helper { constructor(conv) { this.conv = conv; } func1() { this.conv.ask(`What's up?`); } } app.middleware((conv) => { conv.helper = new Helper(conv); }); app.intent('Default Welcome Intent', (conv) => { conv.helper.func1(); });
Esporta l'app
Per esporre il webhook di fulfillment per un framework web o una piattaforma di serverless computing, devi esportare l'oggetto app
come webhook accessibile pubblicamente. La libreria client supporta subito il deployment in diversi ambienti.
I seguenti snippet mostrano come esportare app
in diversi runtime:
Esempio: Cloud Functions for Firebase
const functions = require('firebase-functions'); // ... app code here exports.fulfillment = functions.https.onRequest(app);
Esempio: editor incorporato Dialogflow
const functions = require('firebase-functions'); // ... app code here // Exported function name must be 'dialogflowFirebaseFulfillment' exports.dialogflowFirebaseFulfillment = functions.https.onRequest(app);
Esempio: server Express self-hosted (semplice)
const express = require('express'); const bodyParser = require('body-parser'); // ... app code here express().use(bodyParser.json(), app).listen(3000);
Esempio: server Express self-hosted (più percorsi)
const express = require('express'); const bodyParser = require('body-parser'); // ... app code here const expressApp = express().use(bodyParser.json()); expressApp.post('/fulfillment', app); expressApp.listen(3000);
Esempio: gateway API AWS Lambda
// ... app code here exports.fulfillment = app;