Creare azioni per l'Assistente Google utilizzando l'SDK Actions (livello 1)

1. Panoramica

Avviso: le azioni conversazionali sono state ritirate il 13 giugno 2023. Per ulteriori informazioni, vedi Ritiro delle azioni conversazionali.

La piattaforma per sviluppatori Assistente Google ti consente di creare software per estendere la funzionalità dell'Assistente Google, un assistente personale virtuale, su più di un miliardo di dispositivi, tra cui smart speaker, telefoni, auto, TV, cuffie e altro ancora. Gli utenti interagiscono con l'assistente nella conversazione per svolgere attività, ad esempio fare la spesa o prenotare una corsa. In qualità di sviluppatore, puoi utilizzare la piattaforma per sviluppatori dell'assistente per creare e gestire facilmente esperienze di conversazione piacevoli ed efficaci tra gli utenti e il tuo servizio di distribuzione di terze parti.

Questo codelab tratta concetti di livello principiante per lo sviluppo con l'SDK Actions per l'Assistente Google. non è necessaria alcuna esperienza pregressa con la piattaforma per completarla. In questo codelab, creerai un'azione semplice per l'Assistente Google che racconta agli utenti la loro fortuna mentre iniziano la loro avventura nel mitico paese di Gryffinberg. Nel codelab di livello 2 dell'SDK Actions, crei ulteriormente questa azione per personalizzare ulteriormente la fortuna dell'utente in base al suo input.

Cosa creerai

In questo codelab, creerai un'azione semplice con le seguenti funzioni:

• Risponde agli utenti con un messaggio di benvenuto
• Pone agli utenti una domanda e risponde in modo appropriato alla selezione dell'utente
• Fornisce chip di suggerimenti su cui gli utenti possono fare clic per fornire input
• Modifica il messaggio di benvenuto dell'utente a seconda che si tratti o meno di un utente di ritorno.

Al termine di questo codelab, l'azione completata avrà il seguente flusso conversazionale (il testo accanto al microfono rappresenta l'input dell'utente, mentre il testo accanto a chi parla rappresenta la risposta dell'azione):

Cosa imparerai a fare

• Come creare un progetto nella console di Actions
• Come utilizzare lo strumento gactions per eseguire il push e il pull del tuo progetto di azione tra la console di Actions e il tuo file system locale
• Come inviare una richiesta all'utente dopo che ha richiamato l'azione
• Come elaborare l'input di un utente e restituire una risposta
• Come testare l'azione nel simulatore di Actions
• Come implementare il completamento utilizzando l'editor Cloud Functions

Che cosa ti serve

Nel tuo ambiente devono essere presenti i seguenti strumenti:

• Un IDE o un editor di testo a tua scelta
• Un terminale per eseguire i comandi shell per Node.js e npm
• Un browser web, ad esempio Google Chrome.

Se preferisci lavorare con più strumenti visivi per creare azioni, segui invece il codelab della creazione di azioni per l'Assistente Google utilizzando il codelab Actions Builder (livello 1), che crea la stessa azione usando l'IDE di Actions Builder nella console.

2. Configura

Le seguenti sezioni descrivono come configurare l'ambiente di sviluppo e creare il progetto Actions.

Verifica le impostazioni delle autorizzazioni Google

Per testare l'azione creata in questo codelab, devi abilitare le autorizzazioni necessarie affinché il simulatore possa accedere all'azione.

Per attivare le autorizzazioni, procedi nel seguente modo:

1. Accedi a Gestione attività.
2. Se non l'hai ancora fatto, accedi con il tuo Account Google.
3. Attiva le seguenti autorizzazioni:

• Attività web e app
• In Web & Attività app, seleziona la casella di controllo Includi la cronologia di Chrome e le attività svolte su siti, app e dispositivi che usano i servizi Google**.**

crea un progetto Actions

Il progetto Actions è un contenitore per l'azione.

Per creare il tuo progetto Actions per questo codelab, segui questi passaggi:

1. Apri la console di Actions.
2. Fai clic su Nuovo progetto.
3. Inserisci un Nome progetto, ad esempio actions-codelab. Il nome è solo per riferimento interno. Successivamente, potrai impostare un nome esterno per il progetto.

4. Fai clic su Crea progetto.
5. Nella schermata Che tipo di azione vuoi creare?, seleziona la scheda Personalizzata.
6. Fai clic su Avanti.
7. Nella schermata Come vuoi crearlo?, seleziona la scheda Progetto vuoto.
8. Fai clic su Inizia a creare.

Salva l'ID progetto per l'azione

L'ID progetto è un identificatore univoco dell'Azione. L'ID progetto è necessario per diversi passaggi di questo codelab.

Per recuperare l'ID progetto:

1. Nella console Azioni, fai clic sui tre puntini verticali (inserisci qui l'icona).
2. Fai clic su Impostazioni progetto.

3. Copia l'ID progetto**.**

Associa un account di fatturazione

Se non hai ancora un account di fatturazione, devi crearne uno e associarlo al tuo progetto in Google Cloud per eseguire il deployment del fulfillment in un secondo momento con Cloud Functions.

Per associare un account di fatturazione al progetto:

1. Vai alla pagina Fatturazione Google Cloud.
2. Fai clic su Aggiungi account di fatturazione o Crea account.
3. Inserisci i dati di pagamento.
4. Fai clic su Inizia la mia prova senza costi o Invia e abilita fatturazione.
5. Vai alla pagina Fatturazione Google Cloud.
6. Fai clic sulla scheda I miei progetti.
7. Fai clic sui tre puntini sotto Azioni accanto al progetto Actions per il codelab.
8. Fai clic su Modifica fatturazione.
9. Nel menu a discesa, seleziona l'account di fatturazione che hai configurato.
10. Fai clic su Imposta account.

Per evitare addebiti, segui i passaggi nella sezione Pulisci il tuo progetto alla fine di questo codelab.

Installa l'interfaccia a riga di comando di gactions

In questo codelab, utilizzerai lo strumento dell'interfaccia a riga di comando (CLI) di gactions per sincronizzare il tuo progetto Actions tra la console Actions e il tuo file system locale.

Termine chiave:

• Interfaccia a riga di comando gactions: uno strumento che consente di inizializzare i file di progetto di azione, eseguire il push degli aggiornamenti alla console di Actions, eseguire il deployment di progetti Actions e altro ancora.

Per installare l'interfaccia a riga di comando gactions, segui le istruzioni riportate in Installare lo strumento a riga di comando gactions.

Scaricare il progetto Actions

Per iniziare a sviluppare l'azione, scarica il progetto Actions dalla console Actions.

Per scaricare il progetto Actions, segui questi passaggi:

1. Per creare una nuova directory e passare a quella directory, esegui questi comandi:

mkdir myproject
cd myproject

2. Per copiare la configurazione del progetto Actions nel file system locale, esegui questo comando:

gactions pull --project-id <projectID>

Comprendere la struttura dei file

Il progetto Actions scaricato dalla console Actions è rappresentato in una struttura di file YAML. L'immagine seguente mostra una rappresentazione generale della struttura dei file:

La struttura dei file è costituita da quanto segue:

• actions/: rappresenta il progetto Actions. Il sistema chiama actions.yaml quando l'Azione viene richiamata, quindi chiama il file custom/global/actions.intent.MAIN.yaml.
• custom/: la directory da utilizzare per modificare l'azione.
• global/: questa directory contiene gli intent di sistema che la piattaforma aggiunge automaticamente al tuo progetto. Scoprirai di più sugli intent di sistema più avanti in questo codelab.
• manifest.yaml: un file che contiene informazioni trasportabili o non specifiche di un determinato progetto e che può essere spostato da un progetto all'altro.
• settings/: rappresenta le impostazioni di un progetto Actions, ad esempio il nome visualizzato, le impostazioni internazionali predefinite e la categoria.

3. Avviare una conversazione

Gli utenti avviano la conversazione con l'azione mediante una chiamata. Ad esempio, se hai un'azione denominata MovieTime, gli utenti possono richiamare l'azione dicendo una frase come "Hey Google, parla con MovieTime", dove MovieTime è il nome visualizzato. L'azione deve avere un nome visualizzato se vuoi eseguirne il deployment in produzione. Tuttavia, per testare l'azione, non è necessario definire il nome visualizzato. Invece, puoi utilizzare la frase "Parla con la mia app di prova" nel simulatore per richiamare l'azione. Scoprirai di più sul simulatore più avanti in questa sezione.

Devi modificare la chiamata principale per definire cosa succede dopo che un utente richiama l'azione.

Termine chiave:

• Chiamata principale: un punto di ingresso da cui gli utenti possono avviare conversazioni con l'Azione. Quando gli utenti pronunciano una frase simile a "Hey Google, parla con <nome visualizzato>", la chiamata principale viene attivata e risponde all'utente.

Per impostazione predefinita, quando viene attivata la chiamata, l'Azione fornisce un prompt generico ("Inizia a creare l'Azione definendo la chiamata principale").

Termine chiave:

• Prompt: definisce ciò che l'azione invia agli utenti in risposta. I prompt possono essere semplici risposte di testo e vocali o messaggi avanzati, come schede e immagini.

Puoi utilizzare un prompt speciale, Canvas, per restituire all'utente immagini a schermo intero. Per scoprire di più su Canvas, consulta la documentazione di Interactive Canvas.

Nella sezione successiva personalizzerai il prompt per la chiamata principale nel file custom/global/actions.intent.MAIN.yaml.

Configura la chiamata principale

Puoi modificare il prompt di chiamata principale nel file actions.intent.MAIN.yaml.

Per modificare la richiesta che l'Azione rimanda all'utente quando richiama l'Azione, procedi nel seguente modo:

1. Apri custom/global/actions.intent.MAIN.yaml nell'editor di testo.
2. Sostituisci il testo nel campo speech (Start building your action...) con il seguente messaggio di benvenuto: A wondrous greeting, adventurer! Welcome to the mythical land of Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you're on your way to an epic journey.

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: A wondrous greeting, adventurer! Welcome to the mythical land of 
                Gryffinberg! Based on your clothes, you are not from around these lands. 
                It looks like you're on your way to an epic journey.
transitionToScene: actions.scene.END_CONVERSATION

3. Salva il file.

Testa la chiamata principale nel simulatore

La console di Actions fornisce uno strumento web per testare l'azione chiamato simulatore. L'interfaccia simula i dispositivi hardware e le relative impostazioni, in modo da poter conversare con l'azione come se fosse in esecuzione su uno smart display, uno smartphone, un altoparlante o KaiOS.

Per le informazioni più recenti sull'utilizzo del simulatore della console Actions o in caso di problemi nei passaggi successivi, consulta la pagina Simulator.

Quando richiami l'Azione, questa dovrebbe rispondere con il prompt personalizzato che hai aggiunto ("Un saluto meraviglioso, avventuriero!...").

Puoi usare il comando gactions deploy preview per testare l'azione nella console senza aggiornare la versione del progetto Actions. Quando esegui questo comando, nessuna delle modifiche apportate nel file system locale viene propagata alle versioni di cui è stato eseguito il deployment del progetto Actions, ma puoi testarle in una versione di anteprima.

Per testare la chiamata principale dell'azione nel simulatore:

1. Per eseguire il deployment del progetto nella console Actions per i test, esegui questo comando nel terminale:

gactions deploy preview

Quando esegui questo comando, potresti ricevere una notifica relativa a problemi di convalida. Finché i file sono stati trasmessi, puoi ignorare questo avviso.

Dovresti ricevere un output simile al seguente:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copia l'URL fornito e incollalo in un browser.
3. Per richiamare l'azione nel simulatore, digita Talk to my test app nel campo Input e premi Enter.

Suggerimento:puoi anche fare clic sul chip di suggerimento Parla con la mia app di prova in Suggerimenti, che viene elaborato allo stesso modo dell'input utente pronunciato o digitato.

In alternativa, puoi fare clic sull'icona del microfono e dire "Parla con la mia app di prova" per richiamare l'azione.

Quando attivi la chiamata principale dell'Azione, l'assistente risponde con il tuo messaggio di benvenuto personalizzato. A questo punto, la conversazione termina dopo che l'assistente ha risposto con un saluto. Nella sezione successiva modificherai l'Azione in modo che la conversazione prosegua.

Visualizza log eventi

Nella scheda Test della console Actions, il riquadro mostra i log eventi, che visualizzano la cronologia delle conversazioni come log eventi. Ogni log eventi mostra gli eventi che si sono verificati durante il turno della conversazione.

Al momento l'Azione ha un log eventi che mostra sia l'input dell'utente ("Parla con la mia app di prova") sia la risposta dell'Azione. Il seguente screenshot mostra il log eventi dell'azione:

Se fai clic sulla freccia verso il basso accanto a Talk to my test app nel log eventi, puoi vedere gli eventi, organizzati cronologicamente, che si sono verificati in quel turno della conversazione:

• userInput: corrisponde all'input dell'utente ("Parla con la mia app di prova")
• interactionMatch: corrisponde alla risposta di chiamata principale dell'Azione, che è stata attivata dall'input dell'utente. Se espandi questa riga facendo clic sulla freccia, puoi vedere il prompt che hai aggiunto per la chiamata principale (A wondrous greeting, adventurer!...)
• endConversation: corrisponde alla transizione selezionata nell'intent Main invocation, che al momento termina la conversazione. Scopri di più sulle transizioni nella sezione successiva di questo codelab.

I log eventi offrono visibilità sul funzionamento dell'azione e sono strumenti utili per eseguire il debug dell'azione in caso di problemi. Per vedere i dettagli di un evento, fai clic sulla freccia accanto al nome dell'evento, come mostrato nello screenshot seguente:

4. Crea la conversazione dell'Azione

Ora che hai definito cosa succede dopo che un utente richiama l'azione, puoi creare il resto della conversazione dell'azione. Prima di continuare con questo codelab, familiarizza con i seguenti termini per comprendere come funziona la conversazione dell'azione:

Termini chiave:

• Scena: un componente di base dell'azione che elabora l'input dell'utente e in genere genera una risposta all'utente. Gli intent personalizzati spesso attivano altre scene, ma le scene possono essere attivate anche in altri modi.
• Personalizzato per intenzione: definisce l'input dell'utente che l'azione è in grado di comprendere. Sei tu a definire le frasi di addestramento per questi intent. Quando gli utenti dicono qualcosa che corrisponde o è simile a una frase di addestramento, viene abbinata l'intenzione corrispondente.
• Frasi di addestramento: esempi di ciò che un utente potrebbe dire per soddisfare un'intenzione. Il motore di comprensione del linguaggio naturale (NLU) dell'assistente espande naturalmente queste frasi di addestramento in modo da includere altre frasi simili.
• Transizione: definisce la scena a cui passare una volta soddisfatta la condizione.

L'azione può includere una o più scene e devi attivare ciascuna scena prima di eseguirla. L'azione che crei in questo codelab ha una sola scena chiamata Start. Il modo più comune per attivare una scena è configurare l'azione in modo che, quando l'input dell'utente corrisponde a un intent all'interno di una scena, quest'ultimo attivi la transizione a un'altra scena e la attivi.

Ad esempio, immagina un'azione ipotetica che fornisca all'utente fatti sugli animali. Quando l'utente richiama questa azione, viene abbinata l'intent Main invocation e attiva la transizione a una scena denominata Facts.. Questa transizione attiva la scena Facts, che invia all'utente la seguente richiesta: Would you like to hear a fact about cats or dogs? All'interno della scena Facts c'è un intent personalizzato chiamato Cat, che contiene frasi di addestramento che l'utente potrebbe dire per ascoltare un fatto relativo ai gatti, ad esempio "Voglio sentire un fatto gatto" o "gatto". Quando l'utente chiede di ascoltare una storia sui gatti, l'intent Cat viene abbinato e attiva una transizione a una scena chiamata Cat fact.. La scena Cat fact si attiva e invia all'utente un messaggio che include una curiosità.

Figura 1. Il flusso di una tipica svolta conversazionale in un'azione creata con l'SDK Actions.

Insieme, scene, intent e transizioni costituiscono la logica della conversazione e definiscono i vari percorsi che l'utente può intraprendere nella conversazione dell'Azione. Nella sezione seguente, creerai una scena e definirai in che modo viene attivata dopo che un utente ha richiamato l'azione.

Transizione dalla chiamata principale alla scena

In questa sezione creerai una nuova scena chiamata Start, che invia un prompt all'utente per chiedere se vuole che la sua fortuna venga raccontata. Aggiungi anche una transizione dalla chiamata principale alla nuova scena Start.

Per creare questa scena e aggiungere una transizione, segui questi passaggi:

1. Apri custom/global/actions.intent.MAIN.yaml nell'editor di testo.
2. Sostituisci il testo nel campo transitionToScene (actions.scene.END_CONVERSATION) con il seguente: transitionToScene: Start

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Welcome to the mythical land of  Gryffinberg! Based on your clothes,
              you are not from around these lands. It looks like you're on your way
              to an epic journey.
transitionToScene: Start

Questo indica all'azione di passare dalla chiamata principale alla scena Start.

3. Salva il file.
4. Nel terminale, crea una nuova directory scenes nella directory custom:

mkdir custom/scenes 

5. Crea un nuovo file denominato Start.yaml nella directory scenes, che rappresenta la scena start nella tua azione:

touch custom/scenes/Start.yaml 

6. Apri Start.yaml nell'editor di testo.
7. Incolla il seguente codice nel file Start.yaml:

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?

Nel codice del file Start.yaml è presente un campo chiamato onEnter, che è la prima fase in esecuzione nel ciclo di vita di una scena.

Termini chiave:

• OnEnter: lo stage che si attiva quando si attiva una scena. OnEnter definisce cosa succede quando l'utente entra nella scena.

In questo caso, il prompt (Before you continue on your quest...) viene aggiunto alla coda dei prompt quando l'utente accede per la prima volta alla scena Start.

Termini chiave:

• Coda di prompt: i prompt vengono aggiunti l'uno all'altro in una coda di prompt. Prima che l'utente possa rispondere, l'assistente presenta tutte le richieste nella coda delle richieste.

Aggiungere chip di suggerimenti

I chip di suggerimento offrono all'utente suggerimenti cliccabili che l'Azione elabora come input dell'utente. In questa sezione, aggiungerai i chip di suggerimento Yes e No che vengono visualizzati sotto il prompt appena configurato (Before you continue on your quest, would you like your fortune told?) per supportare gli utenti su dispositivi con schermo.

Per aggiungere chip di suggerimento al prompt della scena Start, segui questi passaggi:

1. Aggiorna il codice in Start.yaml in modo che corrisponda al seguente snippet di codice, che include il codice per configurare i chip di suggerimento:

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?
        suggestions:
        - title: "Yes"
        - title: "No"

2. Salva il file.

Testa l'azione nel simulatore

A questo punto, l'azione dovrebbe passare dalla chiamata principale alla scena Start e chiedere all'utente se vuole che la sua fortuna venga raccontata. Nel display simulato dovrebbero apparire anche i chip di suggerimenti.

Per testare l'azione nel simulatore:

1. Nel terminale, esegui questo comando:

gactions deploy preview

Dovresti ricevere un output simile al seguente:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copia l'URL fornito e incollalo in un browser.
3. Fai clic su Test per accedere al simulatore.
4. Digita Talk to my test app nel campo Immissione e premi Enter. L'azione dovrebbe rispondere con il prompt Main invocation e il prompt della scena Start aggiunto, "Prima di continuare la missione, vuoi che la fortuna ti venga preparata?", con i chip di suggerimento visualizzati.

Il seguente screenshot mostra questa interazione:

I log eventi registrano tutte le interazioni con il simulatore nella sessione corrente, pertanto il log eventi dei test precedenti in questo codelab verrà visualizzato come primo log eventi. Per cancellare i log eventi, fai clic su Reimposta test.

5. Fai clic sul chip di suggerimento Sì o No per rispondere alla richiesta. Puoi anche dire "Sì" o "No" o inserire Yes o No nel campo Immissione.

Quando rispondi al prompt, l'azione risponde con un messaggio che indica che non è in grado di comprendere l'input: "Non ho capito. Puoi riprovare?" Poiché non hai ancora configurato l'Azione in modo da comprendere e rispondere all'input "Sì" o "No", l'Azione associa l'input a un intent NO_MATCH.

Termini chiave:

• NO_MATCH: un intent generico che viene abbinato quando l'utente dice qualcosa che non può essere abbinato a un altro intent nell'azione.
• Intent di sistema: un intent configurato per impostazione predefinita che gestisce eventi di sistema comuni, ad esempio quando un utente non fornisce alcun input. NO_MATCH e l'intent associato alla chiamata principale sono esempi di intent di sistema.

Per impostazione predefinita, l'intent di sistema NO_MATCH fornisce risposte generiche, ma puoi personalizzarle per indicare all'utente che non hai compreso l'input. L'assistente termina la conversazione dell'utente con l'azione dopo che non è in grado di trovare una corrispondenza per tre volte con l'input dell'utente.

Aggiungi intent yes e no

Ora che gli utenti possono rispondere alla domanda che pone l'azione, puoi configurarla per comprendere il comportamento degli utenti ("Sì" o "No"). Nelle sezioni seguenti, creerai intent personalizzati che vengono associati quando l'utente dice "Sì" o "No" e aggiungerai questi intent alla scena Start.

Crea intent yes

Per creare l'intent yes:

1. Nel terminale, crea una nuova directory denominata intents nella directory custom:

mkdir custom/intents 

2. Crea un nuovo file denominato yes.yaml nella directory intents:

touch custom/intents/yes.yaml

3. Apri yes.yaml nell'editor di testo.
4. Incolla in yes.yaml il seguente snippet di codice contenente le frasi di addestramento:

yes.yaml

trainingPhrases:
- of course
- let's do it
- ok
- sure
- "y"
- "yes"

5. Salva il file.

Aggiungi l'intent yes a Start scena

Ora l'Azione è in grado di capire quando un utente esprime un intento "sì". Puoi aggiungere l'intent personalizzato yes alla scena Start, dato che l'utente sta rispondendo al prompt di Start ("Prima di continuare la missione, vuoi sapere la tua fortuna?").

Per aggiungere questo intent personalizzato alla scena Start, segui questi passaggi:

1. Apri custom/scenes/Start.yaml nell'editor di testo.
2. Aggiungi i gestori intentEvents e yes alla fine del file Start.yaml:

Start.yaml

intentEvents:
- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: Your future depends on the item you choose to use for your quest. Choose wisely! Farewell, stranger.
  intent: "yes"
  transitionToScene: actions.scene.END_CONVERSATION

Quando viene trovato l'intent yes, alla coda dei prompt viene aggiunto il messaggio "Il futuro dipende dall'elemento che scegli di utilizzare per la missione...". La scena Start passa quindi alla scena del sistema actions.scene.END_CONVERSATION, che fornisce i prompt nella coda dei prompt e termina la conversazione.

Testa yes intent nel simulatore

A questo punto, l'azione capisce quando l'utente vuole ascoltare il suo destino e restituisce la risposta appropriata.

Per testare questo intent nel simulatore:

1. Nel terminale, esegui questo comando:

gactions deploy preview

Dovresti ricevere un output simile al seguente:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copia l'URL fornito e incollalo in un browser.
3. Fai clic su Test per accedere al simulatore.
4. Per testare l'Azione nel simulatore, digita Talk to my test app nel campo Input e premi Enter.
5. Digita Yes nel campo Immissione e premi Enter. In alternativa, fai clic sul chip di suggerimento Sì.

L'Azione risponde all'utente comunicandogli che la fortuna dipende dall'aiuto scelto. L'Azione termina quindi la sessione perché hai configurato la transizione End conversation per l'intent yes.

Crea intent no

Ora puoi creare l'intent no in modo che l'azione possa comprendere e rispondere all'utente quando non vuole ascoltare la sua fortuna.

Per creare questo intent:

1. Nel terminale, crea un nuovo file denominato no.yaml nella directory intents:

touch custom/intents/no.yaml

2. Apri no.yaml nell'editor di testo.
3. Incolla le seguenti frasi di addestramento nel file no.yaml:

no.yaml

trainingPhrases:
- nope
- I don't want
- "n"
- "no"
- nah
- no thanks

4. Salva il file.

Aggiungi l'intent no a Start scena

Ora l'azione è in grado di capire quando un utente esprime "no" o qualcosa di simile a "no", ad esempio "no". Devi aggiungere l'intent personalizzato no alla scena Start perché l'utente sta rispondendo al prompt di Start ("Prima di continuare la missione, vuoi sapere il futuro?").

Per aggiungere questo intent per la scena Start:

1. Apri custom/scenes/Start.yaml nell'editor di testo.
2. Aggiungi il seguente gestore no sotto il gestore yes in Start.yaml:

Start.yaml

- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: I understand, stranger. Best of luck on your quest! Farewell.
  intent: "no"
  transitionToScene: actions.scene.END_CONVERSATION

3. Salva il file.

Testa no intent nel simulatore

A questo punto, l'azione capisce quando l'utente non vuole ascoltare il suo destino e restituisce la risposta appropriata.

Per testare questo intent nel simulatore:

1. Nel terminale, esegui questo comando:

gactions deploy preview

Dovresti ricevere un output simile al seguente:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copia l'URL fornito e incollalo in un browser.
3. Fai clic su Test per accedere al simulatore.
4. Digita Talk to my test app nel campo Immissione e premi Enter.
5. Digita No nel campo Immissione e premi Enter. In alternativa, fai clic sul chip di suggerimento No.

Invece di destinare all'utente la sua fortuna, l'Azione gli augura buona fortuna nel percorso. L'Azione termina quindi la sessione perché hai configurato la transizione End conversation per l'intent no.

5. Implementa il fulfillment

Al momento, le risposte dell'Azione sono statiche; Quando viene attivata una scena contenente un prompt, l'Azione invia la stessa richiesta ogni volta. In questa sezione, implementerai fulfillment, che contiene la logica per creare una risposta conversazionale dinamica.

Termine chiave:

• Fulfillment: il codice che contiene la logica dell'Azione. Un webhook attiva le chiamate al fulfillment in base agli eventi che si verificano all'interno delle Azioni.

Il completamento identifica se l'utente è un utente di ritorno o un nuovo utente e modifica il messaggio di benvenuto dell'azione per gli utenti di ritorno. Il messaggio di benvenuto viene abbreviato per gli utenti di ritorno e riconosce il suo ritorno: "Un saluto meraviglioso, avventuriero! Rieccoci nella terra mistica di Gryffinberg!"

Per questo codelab, utilizzerai l'editor Cloud Functions per modificare il codice di fulfillment ed eseguirne il deployment.

Termine chiave:

• Editor Cloud Functions: un editor integrato per i progetti Actions, che puoi utilizzare per modificare ed eseguire il deployment del codice di fulfillment utilizzando Cloud Functions for Firebase.

L'azione può attivare webhook che notificano il completamento di un evento che si verifica durante una chiamata o in parti specifiche dell'esecuzione di una scena. Quando viene attivato un webhook, l'azione invia una richiesta con un payload JSON al tuo fulfillment insieme al nome del gestore da utilizzare per elaborare l'evento. Questo gestore esegue una logica e restituisce una risposta JSON corrispondente.

Crea il tuo fulfillment

In questa sezione modificherai il fulfillment per generare prompt diversi per gli utenti di ritorno e per i nuovi utenti quando richiamano l'Azione.

Per aggiungere questa logica al fulfillment:

1. Nel terminale, assicurati di trovarti nella directory root del tuo progetto e crea una nuova directory webhooks:

mkdir webhooks 

2. Crea un nuovo file denominato ActionsOnGoogleFulfillment.yaml nella directory webhooks:

touch webhooks/ActionsOnGoogleFulfillment.yaml

3. Apri ActionsOnGoogleFulfillment.yaml nell'editor di testo.
4. Aggiungi il gestore greeting e i contenuti inlineCloudFunction al file ActionsOnGoogleFulfillment.yaml:

ActionsOnGoogleFulfillment.yaml

handlers:
- name: greeting
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment

Il file ActionsOnGoogleFulfillment.yaml definisce i gestori webhook (come il gestore greeting) e indica all'azione di utilizzare Cloud Functions come endpoint webhook.

5. Crea una nuova directory ActionsOnGoogleFulfillment nella directory webhooks:

mkdir webhooks/ActionsOnGoogleFulfillment

6. Crea un nuovo file denominato index.js nella directory ActionsOnGoogleFulfillment:

touch webhooks/ActionsOnGoogleFulfillment/index.js

7. Apri index.js nell'editor di testo.
8. Aggiungi il codice seguente a index.js:

index.js

const { conversation } = require('@assistant/conversation');
const functions = require('firebase-functions');

const app = conversation({debug: true});

app.handle('greeting', conv => {
 let message = 'A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!';
 if (!conv.user.lastSeenTime) {
   message = 'Welcome to the mythical land of  Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you\'re on your way to an epic journey.';
 }
 conv.add(message);
});


exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

Questo codice definisce il gestore greeting, che invia il saluto appropriato al

utente.

9. Salva il file.
10. Crea un nuovo file denominato package.json nella directory ActionsOnGoogleFulfillment:

touch webhooks/ActionsOnGoogleFulfillment/package.json

Il file package.json specifica le dipendenze e altri metadati per il webhook.

11. Apri package.json nell'editor di testo.
12. Copia il codice da questo repository GitHub e incollalo nel file package.json.
13. Salva il file.

comprendi il codice

Il tuo fulfillment, che utilizza la libreria Actions on Google Fulfillment per Node.js, risponde alle richieste HTTP dell'Assistente Google.

Nello snippet di codice precedente, definisci il gestore greeting, che verifica se l'utente ha già visitato l'azione con la proprietà lastSeenTime. Se la proprietà lastSeenTime non è definita, l'utente è nuovo e riceve il saluto destinato ai nuovi utenti. In caso contrario, il messaggio conferma il ritorno dell'utente e genera un saluto modificato.

Aggiorna la chiamata principale per attivare un webhook

Ora che hai definito la funzione greeting, puoi configurare il gestore di eventi greeting nel tuo intent di chiamata principale, in modo che l'Azione chiami questa funzione quando l'utente richiama l'azione.

Per configurare l'Azione in modo che chiami il nuovo gestore greeting:

1. Apri custom/global/actions.intent.MAIN.yaml nell'editor di testo.
2. Sostituisci il codice in actions.intent.MAIN.yaml con il seguente codice:

actions.intent.MAIN.yaml

handler:
  webhookHandler: greeting
transitionToScene: Start

3. Salva il file.

Ora, quando viene trovata una corrispondenza con l'intent di chiamata principale, viene chiamato il gestore webhook greeting.

Testa la chiamata principale aggiornata nel simulatore

Per testare l'azione nel simulatore:

1. Nel terminale, esegui questo comando:

Poiché questo comando esegue il deployment del webhook e installa le dipendenze, potrebbe richiedere più tempo rispetto ai comandi precedenti.

gactions deploy preview

Se viene visualizzato un errore 403 relativo all'API Cloud Build o un errore 403 relativo all'associazione dell'account di fatturazione, consulta Abilitare, disabilitare o modificare la fatturazione per un progetto. Per eseguire il deployment con Cloud Functions, devi associare un account di fatturazione al tuo progetto in Google Cloud. Dopo aver associato un account di fatturazione, esegui di nuovo gactions deploy preview. Per evitare addebiti, segui i passaggi nella sezione Pulisci il tuo progetto alla fine di questo codelab.

Dovresti ricevere un output simile al seguente:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copia l'URL fornito e incollalo in un browser.
3. Per testare l'Azione nel simulatore, digita Talk to my test app nel campo Input e premi Enter.

Poiché hai già testato l'azione in precedenza in questo codelab, non sei un nuovo utente, quindi riceverai il seguente breve saluto: "Un saluto meraviglioso, avventuriero! Rieccoci nella mitica terra di Gryffinberg!"

6. Visualizza l'azione con Actions Builder

L'SDK Actions è compatibile con un IDE basato sul web chiamato Azioni Builder integrato nella console di Actions. Puoi eseguire il push del tuo file system locale alla bozza dell'azione nella console con il comando gactions push. A differenza di gactions deploy preview, che ti consente solo di testare l'azione nel simulatore, gactions push sposta tutti i contenuti dai file locali ad Actions Builder.

La console di Actions fornisce una rappresentazione visiva della configurazione dell'Azione. Visualizzare l'azione mappata visivamente può essere utile durante lo sviluppo e non influisce sulla versione dell'azione pubblicata per il test.

L'esecuzione di gactions push sostituisce la bozza corrente del progetto Azioni se lavori in modo collaborativo.

Per eseguire il push del progetto Actions e visualizzarlo nella console Actions, segui questi passaggi:

1. Nel terminale, esegui questo comando per eseguire il push del progetto alla console Actions:

gactions push

Dovresti ricevere un output simile al seguente:

✔ Done. Files were pushed to Actions Console, and you can now view your project with this URL: https://console.actions.google.com/project/{project-id}/overview. If you want to test your changes, run "gactions deploy preview", or navigate to the Test section in the Console.

2. Copia l'URL fornito e incollalo in un browser.
3. Nella console di Actions, fai clic su Develop nella barra di navigazione in alto.
4. Fai clic sulla freccia menu a discesa accanto a Scene e fai clic su Avvia. Dovresti vedere una rappresentazione visiva della scena Start dell'azione, come mostrato nello screenshot seguente:

Pulisci il progetto [consigliato]

Attenzione: il codelab di livello 2, Build Actions for Google Assistant using Actions SDK (Livello 2), si basa sul progetto che hai creato in questo codelab. Se hai intenzione di eseguire il codelab del livello 2, non eliminare il progetto; puoi eliminarlo nella sezione "Esegui la pulizia del progetto" alla fine del codelab del livello 2.

Per evitare possibili addebiti, ti consigliamo di rimuovere i progetti che non intendi utilizzare. Per eliminare i progetti creati in questo codelab:

1. Per eliminare il progetto Cloud e le risorse, completa i passaggi elencati nella sezione Arresto (eliminazione) dei progetti.

Assicurati di selezionare il progetto corretto per l'eliminazione nella pagina Impostazioni della piattaforma Google Cloud.

2. (Facoltativo) Per rimuovere immediatamente il progetto dalla console di Actions, completa i passaggi elencati nella sezione Eliminare un progetto. Se non completi questo passaggio, il progetto viene rimosso automaticamente dopo circa 30 giorni.

7. Complimenti!

Conosci le nozioni di base della creazione di Actions per l'Assistente Google con l'SDK Actions.

Argomenti trattati

• Come configurare un progetto Actions nella console Actions
• Come utilizzare l'SDK Actions per creare il tuo progetto Actions sul tuo file system locale
• Come aggiungere un prompt alla chiamata principale in modo che gli utenti possano avviare una conversazione con l'azione
• Come creare un'interfaccia di conversazione con scene, intent, transizioni, chip di suggerimenti e completamento
• Come testare l'azione con il simulatore di Actions

Scopri di più

Esplora le seguenti risorse per saperne di più sulla creazione di Actions per l'Assistente Google:

• Il sito della documentazione ufficiale per lo sviluppo di Actions for Google Assistant
• Pagina GitHub di Actions on Google per codice campione e librerie
• La community ufficiale di Reddit per gli sviluppatori che lavorano con l'assistente

Segui @ActionsOnGoogle su Twitter per gli ultimi annunci e twitta con #AoGDevs per condividere ciò che crei.

Sondaggio di opinione

Prima di andare, compila un breve sondaggio sulla tua esperienza.