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 saperne di più, consulta Ritiro di Azioni conversazionali.

La piattaforma per sviluppatori dell'Assistente Google ti consente di creare software per estendere la funzionalità dell'Assistente Google, un assistente personale virtuale, su oltre 1 miliardo di dispositivi, tra cui smart speaker, smartphone, auto, TV, cuffie e altro ancora. Gli utenti interagiscono con l'assistente per svolgere attività come acquistare generi alimentari o prenotare una corsa. In qualità di sviluppatore, puoi utilizzare la piattaforma per sviluppatori dell'assistente per creare e gestire facilmente esperienze conversazionali efficaci e piacevoli tra gli utenti e il tuo servizio di evasione ordini di terze parti.

Questo codelab tratta concetti di livello principiante per lo sviluppo con Actions SDK per l'Assistente Google; non è necessaria alcuna esperienza precedente con la piattaforma per completarlo. In questo codelab, creerai un'Azione semplice per l'Assistente Google che dice agli utenti la loro fortuna mentre iniziano la loro avventura nella terra mitica di Gryffinberg. Nel codelab di livello 2 dell'SDK Actions, sviluppi ulteriormente questa azione per personalizzare 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 saluto
• Pone una domanda agli utenti e risponde in modo appropriato alla selezione dell'utente
• Fornisce chip di suggerimento su cui gli utenti possono fare clic per fornire input
• Modifica il messaggio di saluto all'utente in base al fatto che sia 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 all'altoparlante rappresenta la risposta dell'azione):

Obiettivi didattici

• Come creare un progetto nella console Actions
• Come utilizzare lo strumento gactions per eseguire il push e il pull del progetto Azione tra la console Azioni e il file system locale
• Come inviare un prompt 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 l'evasione utilizzando l'editor di 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 comandi shell per Node.js e npm
• Un browser web, ad esempio Google Chrome

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

2. Configura

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

Verifica le impostazioni delle autorizzazioni Google

Per testare l'azione che crei in questo codelab, devi abilitare le autorizzazioni necessarie in modo che il simulatore possa accedere all'azione.

Per attivare le autorizzazioni:

1. Vai 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 Attività web e 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 progetto Azioni per questo codelab:

1. Apri la console Azioni.
2. Fai clic su Nuovo progetto.
3. Inserisci un Nome progetto, ad esempio actions-codelab. Il nome è per riferimento interno. In un secondo momento, 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 della tua 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 l'icona qui).
2. Fai clic su Impostazioni progetto.

3. Copia l'ID progetto.

Associare 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 tuo progetto:

1. Vai alla pagina di fatturazione di Google Cloud Platform.
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 attiva la fatturazione.
5. Vai alla pagina di fatturazione di Google Cloud Platform.
6. Fai clic sulla scheda I miei progetti.
7. Fai clic sui tre puntini sotto Azioni accanto al progetto Azioni 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 descritti nella sezione Pulisci il progetto alla fine di questo codelab.

Installare l'interfaccia a riga di comando gactions

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

Termine chiave:

• gactions CLI: uno strumento che ti consente di inizializzare i file di progetto di Actions, eseguire il push degli aggiornamenti nella console di Actions, eseguire il deployment dei progetti di Actions e altro ancora.

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

Scaricare il progetto Actions

Inizia a sviluppare la tua azione scaricando il progetto Actions dalla console di Actions.

Per scaricare il progetto Azioni, segui questi passaggi:

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

mkdir myproject
cd myproject

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

gactions pull --project-id <projectID>

Informazioni sulla struttura dei file

Il progetto Azioni che scarichi dalla console Azioni è rappresentato in una struttura di file YAML. L'immagine seguente mostra una rappresentazione di alto livello della struttura dei file:

La struttura del file è costituita da quanto segue:

• actions/: rappresenta il tuo progetto Azioni. Il sistema chiama actions.yaml quando viene richiamata l'azione, che a sua volta chiama il file custom/global/actions.intent.MAIN.yaml.
• custom/: la directory in cui lavorerai 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 possono essere spostate tra i progetti.
• settings/: Rappresenta le impostazioni di un progetto Azioni, come il nome visualizzato, le impostazioni internazionali predefinite e la categoria.

3. Avvia una conversazione

Gli utenti avviano la conversazione con la tua Azione tramite l'invocazione. Ad esempio, se hai un'azione denominata MovieTime, gli utenti possono invocarla dicendo una frase come "Hey Google, parla con MovieTime", dove MovieTime è il nome visualizzato. La tua Azione deve avere un nome visualizzato se vuoi eseguirne il deployment in produzione. Tuttavia, per testarla, non è necessario definire il nome visualizzato. In alternativa, 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 l'invocazione principale per definire cosa succede dopo che un utente invoca la tua azione.

Termine chiave:

• Invocation principale: un punto di accesso per gli utenti per avviare conversazioni con la tua Azione. Quando gli utenti pronunciano una frase simile a "Hey Google, parla con <nome visualizzato>", l'invocazione principale si attiva e risponde all'utente.

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

Termine chiave:

• Prompt: definisce ciò che l'azione invia agli utenti come 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 saperne 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.

Configurare la chiamata principale

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

Per modificare il prompt che l'azione invia all'utente quando la richiama, segui questi passaggi:

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.

Testare la chiamata principale nel simulatore

La console Azioni 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 la tua Azione come se fosse in esecuzione su uno smart display, uno smartphone, uno speaker o KaiOS.

Per le informazioni più recenti sull'utilizzo del simulatore della console di Actions o se riscontri problemi nei passaggi seguenti, consulta la pagina Simulatore.

Quando invochi l'azione, ora dovrebbe rispondere con il prompt personalizzato che hai aggiunto ("Un saluto meraviglioso, avventuriero…").

Puoi utilizzare il comando gactions deploy preview per testare l'azione nella console senza aggiornare la versione del progetto Azioni. Quando esegui questo comando, nessuna delle modifiche apportate al file system locale viene propagata alle versioni di deployment del progetto Azioni, ma puoi testarle su una versione di anteprima.

Per testare la chiamata principale dell'azione nel simulatore:

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

gactions deploy preview

Quando esegui questo comando, potresti ricevere una notifica relativa a problemi di convalida. Se i tuoi file sono stati caricati, 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 test in Suggerimenti, che viene elaborato allo stesso modo dell'input utente vocale o digitato.

In alternativa, puoi fare clic sull'icona del microfono e dire "Parla alla mia app di test" 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 risponde con un saluto. Nella sezione successiva, modifichi l'azione in modo che la conversazione continui.

Visualizzare i log eventi

Quando ti trovi nella scheda Test nella console Azioni, il riquadro mostra i log eventi, che visualizzano la cronologia delle conversazioni come log eventi. Ogni log degli eventi mostra gli eventi che si verificano durante il turno della conversazione.

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

Se fai clic sulla freccia giù accanto a Talk to my test app nel log eventi, puoi visualizzare gli eventi, disposti in ordine cronologico, che si sono verificati in quel turno della conversazione:

• userInput: corrisponde all'input dell'utente ("Talk to my test app")
• interactionMatch: corrisponde alla risposta principale di invocazione dell'azione, attivata dall'input dell'utente. Se espandi questa riga facendo clic sulla freccia, puoi visualizzare il prompt che hai aggiunto per la chiamata principale (A wondrous greeting, adventurer!...).
• endConversation: corrisponde alla transizione selezionata nell'intent Main invocation, che attualmente termina la conversazione. Scoprirai di più sulle transizioni nella sezione successiva di questo codelab.

I log degli eventi forniscono visibilità sul funzionamento dell'azione e sono strumenti utili per il debug dell'azione in caso di problemi. Per visualizzare 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, acquisisci familiarità con i seguenti termini per capire come funziona la conversazione dell'azione:

Termini chiave:

• Scena: un blocco predefinito per l'azione che elabora l'input utente e in genere genera la risposta all'utente. Gli intent personalizzati spesso attivano altre scene, ma le scene possono essere attivate anche in altri modi.
• Intento personalizzato: definisce l'input dell'utente che l'azione può comprendere. Definisci le frasi di addestramento per questi intent. Quando gli utenti dicono qualcosa che corrisponde o è simile a una frase di addestramento, viene abbinato l'intent corrispondente.
• Frasi di addestramento: esempi di ciò che un utente potrebbe dire per trovare una corrispondenza con un intent. Il motore di comprensione del linguaggio naturale (NLU) dell'assistente espande naturalmente queste frasi di addestramento per includere altre frasi simili.
• Transizione: definisce a quale scena passare una volta soddisfatta la condizione.

L'azione può avere una o più scene e devi attivare ogni scena prima che possa essere eseguita. L'azione che crei in questo codelab ha una sola scena intitolata 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, questo intent attivi la transizione a un'altra scena e la attivi.

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

Figura 1. Il flusso di un tipico turno 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ò seguire nella conversazione dell'Azione. Nella sezione seguente, crei una scena e definisci come viene attivata dopo che un utente richiama la tua azione.

Transizione dalla chiamata principale alla scena

In questa sezione, crea una nuova scena chiamata Start, che invia un prompt all'utente chiedendogli se vuole che gli venga predetto il futuro. Aggiungi anche una transizione dall'invocazione 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 quanto segue: 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

In questo modo, l'azione passa dall'invocazione 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 nell'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 denominato onEnter, che è la prima fase eseguita nel ciclo di vita di una scena.

Termini chiave:

• OnEnter: la fase che viene eseguita quando una scena si attiva. 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 entra per la prima volta nella scena Start.

Termini chiave:

• Coda di prompt:i prompt vengono aggiunti uno dopo l'altro in una coda di prompt. Prima che l'utente possa rispondere, l'assistente gli presenta tutti i prompt nella coda.

Aggiungere chip di suggerimenti

I chip di suggerimento offrono suggerimenti su cui l'utente può fare clic e che l'azione elabora come input dell'utente. In questa sezione, aggiungi 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 sui dispositivi con schermi.

Per aggiungere chip di suggerimento al prompt della scena Start:

1. Aggiorna il codice in Start.yaml in modo che corrisponda al seguente snippet di codice, che include il codice per la configurazione dei 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.

Testare l'azione nel simulatore

A questo punto, l'azione deve passare dall'invocazione principale alla scena Start e chiedere all'utente se vuole che gli venga predetto il futuro. I chip di suggerimento dovrebbero essere visualizzati anche nel display simulato.

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 Testa per accedere al simulatore.
4. Digita Talk to my test app nel campo Input e premi Enter. L'azione deve rispondere con il prompt Main invocation e il prompt della scena aggiunto Start, "Prima di continuare la tua missione, vuoi che ti venga predetto il futuro?", con i chip di suggerimento visualizzati.

Il seguente screenshot mostra questa interazione:

I log eventi registrano ogni interazione del simulatore nella sessione corrente, quindi il log eventi del test precedente in questo codelab viene visualizzato come primo log eventi. Per cancellare i log degli 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" oppure inserire Yes o No nel campo Input.

Quando rispondi al prompt, l'Azione risponde con un messaggio che indica che non riesce a capire il tuo input: "Mi dispiace, non ho capito. Puoi riprovare?" Poiché non hai ancora configurato l'azione in modo che comprenda e risponda all'input "Sì" o "No", l'azione associa il tuo 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 e che gestisce eventi di sistema comuni, ad esempio quando un utente non fornisce input. NO_MATCH e l'intent associato all'invocazione 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 il suo input. L'assistente termina la conversazione dell'utente con la tua azione dopo che non riesce a trovare una corrispondenza per l'input dell'utente per tre volte.

Aggiungere intent yes e no

Ora che gli utenti possono rispondere alla domanda posta dall'azione, puoi configurarla in modo che comprenda le risposte degli utenti ("Sì" o "No"). Nelle sezioni seguenti, creerai intent personalizzati che vengono abbinati 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 il seguente snippet di codice contenente le frasi di addestramento in yes.yaml:

yes.yaml

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

5. Salva il file.

Aggiungi l'intento yes alla scena Start

Ora l'azione può comprendere quando un utente esprime l'intenzione di rispondere "sì". Puoi aggiungere l'intent personalizzato yes alla scena Start, poiché l'utente sta rispondendo al prompt Start ("Prima di continuare la tua missione, vuoi conoscere il tuo futuro?").

Per aggiungere questo intent personalizzato alla scena Start:

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 trovata una corrispondenza con l'intent yes, alla coda dei prompt viene aggiunto il prompt "Il tuo futuro dipende dall'oggetto che scegli di usare per la tua 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.

Test dell'intent yes nel simulatore

A questo punto, l'azione capisce quando l'utente vuole ascoltare la sua fortuna 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 Testa 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 Input e premi Enter. In alternativa, fai clic sul chip di suggerimento Sì.

L'azione risponde all'utente e gli dice che la sua fortuna dipende dall'aiuto che sceglie. 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, segui questi passaggi:

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'intento no alla scena Start

Ora, l'azione può capire quando un utente esprime un "no" o qualcosa di simile a "no", come "no". Devi aggiungere l'intent personalizzato no alla scena Start perché l'utente sta rispondendo al prompt Start ("Prima di continuare la tua missione, vuoi conoscere il tuo futuro?").

Per aggiungere questo intent per la scena Start, segui questi passaggi:

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.

Test dell'intent no nel simulatore

A questo punto, l'azione capisce quando l'utente non vuole ascoltare la sua fortuna 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 Testa per accedere al simulatore.
4. Digita Talk to my test app nel campo Input e premi Enter.
5. Digita No nel campo Input e premi Enter. In alternativa, fai clic sul chip di suggerimento No.

Invece di rivelare il futuro dell'utente, l'azione gli augura buona fortuna per il suo viaggio. L'azione termina quindi la sessione perché hai configurato la transizione End conversation per l'intent no.

5. Implementare l'evasione

Al momento, le risposte dell'Azione sono statiche: quando viene attivata una scena contenente un prompt, l'Azione invia lo stesso prompt ogni volta. In questa sezione, implementerai il fulfillment che contiene la logica per costruire 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 tue azioni.

L'intent di fulfillment identifica se l'utente è un utente di ritorno o un nuovo utente e modifica il messaggio di saluto dell'azione per gli utenti di ritorno. Il messaggio di saluto viene abbreviato per gli utenti di ritorno e riconosce il ritorno dell'utente: "Un saluto meraviglioso, avventuriero! Bentornato nella terra mitica di Gryffinberg."

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

Termine chiave:

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

La tua azione può attivare webhook che notificano l'adempimento di un evento che si verifica durante un'invocazione o parti specifiche dell'esecuzione di una scena. Quando viene attivato un webhook, l'azione invia una richiesta con un payload JSON al 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, modifichi il fulfillment per generare prompt diversi per gli utenti di ritorno e per i nuovi utenti quando richiamano l'azione.

Per aggiungere questa logica all'evasione, segui questi passaggi:

1. Nel terminale, assicurati di trovarti nella directory root del 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 fulfillment, che utilizza la libreria di fulfillment di Azioni su Google per Node.js, risponde alle richieste HTTP dell'Assistente Google.

Nel precedente snippet di codice, 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 riconosce 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 nell'intent di chiamata principale in modo che l'azione sappia di dover chiamare questa funzione quando l'utente la richiama.

Per configurare l'azione in modo che chiami il nuovo gestore greeting, segui questi passaggi:

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 per l'intent di invocazione 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 ricevi un errore 403 relativo all'API Cloud Build o un errore 403 relativo all'associazione del tuo account di fatturazione, consulta Attivare, disattivare o modificare la fatturazione per un progetto. Per eseguire il deployment utilizzando 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 descritti nella sezione Pulisci il 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 testato l'azione in precedenza in questo codelab, non sei un nuovo utente, quindi ricevi il seguente saluto abbreviato: "Un saluto meraviglioso, avventuriero! Bentornato nella terra mitica di Gryffinberg…"

6. Visualizzare l'azione con Actions Builder

L'SDK Actions è interoperabile con un IDE basato sul web chiamato Actions Builder, integrato nella console Actions. Puoi eseguire il push del file system locale nella 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 Azioni fornisce una rappresentazione visiva della configurazione dell'azione. Visualizzare la tua Azione in modo schematico può essere utile durante lo sviluppo e non influisce sulla versione dell'Azione utilizzata per i test.

L'esecuzione di gactions push esegue l'override della bozza corrente del progetto Azioni se stai lavorando in collaborazione.

Per eseguire il push del progetto Azioni e visualizzarlo nella console Azioni:

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

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 Sviluppa nella barra di navigazione in alto.
4. Fai clic sulla Freccia menu a discesa accanto a Scene e poi su Avvia. Dovresti visualizzare una rappresentazione visiva della scena Start dell'azione, come mostrato nello screenshot seguente:

Pulire il progetto [consigliato]

Attenzione: il codelab di livello 2, Build Actions for Google Assistant using Actions SDK (Level 2), si basa sul progetto creato in questo codelab. Se prevedi di svolgere il codelab di livello 2, non eliminare il progetto. Puoi eliminarlo nella sezione "Pulisci il progetto" alla fine del codelab di livello 2.

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

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

Assicurati di selezionare il progetto corretto da eliminare nella pagina Impostazioni di Google Cloud Platform.

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 tuo progetto viene rimosso automaticamente dopo circa 30 giorni.

7. Complimenti!

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

Argomenti trattati

• Come configurare un progetto Actions nella console Actions
• Come utilizzare l'SDK Actions per creare il progetto Azioni sul file system locale
• Come aggiungere un prompt all'invocazione principale in modo che gli utenti possano avviare una conversazione con la tua Azione
• Come creare un'interfaccia conversazionale con scene, intent, transizioni, chip di suggerimento e completamento
• Come testare l'azione con il simulatore di Actions

Scopri di più

Esplora le seguenti risorse per scoprire di più sulla creazione di Azioni per l'Assistente Google:

• Il sito di documentazione ufficiale per lo sviluppo di Azioni per l'Assistente Google
• Pagina GitHub di Azioni su Google per esempi di codice e librerie
• La community ufficiale di Reddit per gli sviluppatori che lavorano con l'assistente

Segui @ActionsOnGoogle su Twitter per gli ultimi annunci e usa l'hashtag #AoGDevs per condividere le tue creazioni.

Sondaggio di opinione

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