Le azioni di conversazione sono state ritirate il 13 giugno 2023. Per ulteriori informazioni, vedi Ritiro di Azioni di conversazione.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Webhook

Per offrirti ancora più flessibilità nella creazione di azioni, puoi delegare la logica a servizi web HTTPS (fulfillment). Le tue Azioni possono attivare webhook che effettuano richieste a un endpoint HTTPS. Alcuni esempi di ciò che puoi fare nell'adempimento includono:

Generazione di un prompt dinamico in base alle informazioni fornite dall'utente.
Effettuare un ordine in un sistema esterno e confermare la riuscita dell'operazione.
Convalida degli slot con i dati di backend.

**Figura 1.** Gli intent di invocazione e le scene possono attivare webhook.

Trigger e gestori webhook

Le tue Azioni possono attivare un webhook all'interno di intent di invocazione o scene, che invia una richiesta all'endpoint di fulfillment. Il tuo fulfillment contiene gestori webhook che elaborano il payload JSON nella richiesta. Puoi attivare webhook nelle seguenti situazioni:

Dopo una corrispondenza dell'intent di invocazione
Durante la fase di ingresso di una scena
Dopo che una condizione restituisce il valore vero nella fase di condizione di una scena
Durante la fase di riempimento degli slot di una scena
Dopo che si verifica una corrispondenza di intent nella fase di input di una scena

Quando attivi un webhook nelle tue Azioni, l'assistente Google invia una richiesta con un payload JSON al tuo fulfillment, che contiene il nome dell'handler da utilizzare per elaborare l'evento. L'endpoint di fulfillment può indirizzare l'evento al gestore appropriato per eseguire la logica e restituire una risposta corrispondente con un payload JSON.

Payload

I seguenti snippet mostrano richieste di esempio che le tue azioni inviano all'evasione e una risposta che l'evasione invia di nuovo. Per ulteriori informazioni, consulta la documentazione di riferimento.

Esempio di richiesta

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "example_session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Esempio di risposta

{
  "session": {
    "id": "example_session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Hello World.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {},
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  }
}

Interazioni runtime

Le sezioni seguenti descrivono le attività comuni che puoi svolgere nei gestori webhook.

Inviare prompt

Puoi creare prompt con testo semplice, testo RTF, schede e persino prompt HTML completi supportati da un'app web con Interactive Canvas. La documentazione relativa ai prompt contiene informazioni complete su come creare un prompt durante la gestione di un evento webhook. I seguenti snippet mostrano un prompt della scheda:

Node.js

app.handle('rich_response', conv => {
  conv.add('This is a card rich response.');
  conv.add(new Card({
    title: 'Card Title',
    subtitle: 'Card Subtitle',
    text: 'Card Content',
    image: new Image({
      url: 'https://developers.google.com/assistant/assistant_96.png',
      alt: 'Google Assistant logo'
    })
  }));
});

JSON di risposta

{
  "session": {
    "id": "example_session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "content": {
      "card": {
        "title": "Card Title",
        "subtitle": "Card Subtitle",
        "text": "Card Content",
        "image": {
          "alt": "Google Assistant logo",
          "height": 0,
          "url": "https://developers.google.com/assistant/assistant_96.png",
          "width": 0
        }
      }
    },
    "firstSimple": {
      "speech": "This is a card rich response.",
      "text": ""
    }
  }
}

Parametri dell'intenzione di lettura

Quando il runtime dell'assistente corrisponde a un intent, estrae tutti i parametri definiti. La proprietà originale è quella fornita dall'utente come input, mentre la proprietà risolta è quella a cui l'elaborazione del linguaggio naturale ha risolto l'input in base alla specifica del tipo.

Node.js

conv.intent.params['param_name'].original
conv.intent.params['param_name'].resolved

Richiesta JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "intent_name",
    "params": {
      "slot_name": {
        "original": "1",
        "resolved": 1
      }
    },
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {},
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Lettura delle impostazioni internazionali dell'utente

Questo valore corrisponde all'impostazione delle impostazioni locali dell'utente per l'Assistente Google.

Node.js

conv.user.locale

JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Lettura e scrittura dello spazio di archiviazione

Consulta la documentazione relativa all'archiviazione per informazioni complete su come utilizzare le varie funzionalità di archiviazione.

Node.js

//read
conv.session.params.key
conv.user.params.key
conv.home.params.key

// write
conv.session.params.key = value
conv.user.params.key = value
conv.home.params.key = value

Richiesta JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {
      "key": "value"
    },
    "typeOverrides": [],
    "languageCode": ""
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED",
      "key": "value"
    }
  },
  "home": {
    "params": {
      "key": "value"
    }
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

JSON di risposta

{
  "session": {
    "id": "session_id",
    "params": {
      "key": "value"
    }
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Hello world.",
      "text": ""
    }
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED",
      "key": "value"
    }
  },
  "home": {
    "params": {
      "key": "value"
    }
  }
}

Controllare le funzionalità del dispositivo

Puoi controllare le funzionalità di un dispositivo per offrire esperienze o flussi di conversazione diversi.

Node.js

const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE");
const supportsLongFormAudio = conv.device.capabilities.includes("LONG_FORM_AUDIO");
const supportsSpeech = conv.device.capabilities.includes("SPEECH");
const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS");

Richiesta JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": [],
    "languageCode": ""
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO",
      "INTERACTIVE_CANVAS"
    ]
  }
}

Per un elenco completo delle funzionalità di Surface, consulta il riferimento Capability.

Override del tipo di runtime

I tipi di runtime consentono di modificare le specifiche dei tipi in fase di runtime. Puoi utilizzare questa funzionalità per caricare dati da altre origini per popolare i valori validi di un tipo. Ad esempio, puoi utilizzare gli override del tipo di runtime per aggiungere opzioni dinamiche a una domanda del sondaggio o per aggiungere un elemento giornaliero a un menu.

Per utilizzare i tipi di runtime, devi attivare un webhook dall'azione che chiama un gestore nell'intent. Da qui, puoi compilare il parametro session.typeOverrides in una risposta alla tua azione. Le modalità disponibili includono TYPE_MERGE per conservare le voci di tipo esistenti o TYPE_REPLACE per sostituire le voci esistenti con gli override.

Node.js

conv.session.typeOverrides = [{
    name: type_name,
    mode: 'TYPE_REPLACE',
    synonym: {
      entries: [
        {
          name: 'ITEM_1',
          synonyms: ['Item 1', 'First item']
        },
        {
          name: 'ITEM_2',
          synonyms: ['Item 2', 'Second item']
       },
       {
          name: 'ITEM_3',
          synonyms: ['Item 3', 'Third item']
        },
        {
          name: 'ITEM_4',
          synonyms: ['Item 4', 'Fourth item']
        },
    ]
  }
}];

JSON di risposta

{
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": [
      {
        "name": "type_name",
        "synonym": {
          "entries": [
            {
              "name": "ITEM_1",
              "synonyms": [
                "Item 1",
                "First item"
              ]
            },
            {
              "name": "ITEM_2",
              "synonyms": [
                "Item 2",
                "Second item"
              ]
            },
            {
              "name": "ITEM_3",
              "synonyms": [
                "Item 3",
                "Third item"
              ]
            },
            {
              "name": "ITEM_4",
              "synonyms": [
                "Item 4",
                "Fourth item"
              ]
            }
          ]
        },
        "typeOverrideMode": "TYPE_REPLACE"
      }
    ]
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": "This is an example prompt."
    }
  }
}

Fornire la distorsione del parlato

Il biasing del parlato ti consente di specificare suggerimenti per l'NLU per migliorare la corrispondenza degli intent. Puoi specificare fino a 1000 voci.

Node.js

conv.expected.speech = ['value_1', 'value_2']
conv.expected.language = 'locale_string'

JSON di risposta

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": "This is an example prompt."
    }
  },
  "expected": {
    "speech": "['value_1', 'value_2']",
    "language": "locale_string"
  }
}

Scene di transizione

Oltre a definire transizioni statiche nel progetto Azioni, puoi fare in modo che le transizioni di scena si verifichino in fase di runtime.

Node.js

app.handle('transition_to_hidden_scene', conv => {
  // Dynamic transition
  conv.scene.next.name = "HiddenScene";
});

JSON di risposta

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {},
    "next": {
      "name": "HiddenScene"
    }
  }
}

Leggi gli slot delle scene

Durante la compilazione dello slot, puoi utilizzare l'evasione per convalidare lo slot o controllare lo stato della compilazione dello slot (SlotFillingStatus).

Node.js

conv.scene.slotFillingStatus  // FINAL means all slots are filled
conv.scene.slots  // Object that contains all the slots
conv.scene.slots['slot_name'].<property_name> // Accessing a specific slot's properties

Ad esempio, supponiamo che tu voglia estrarre il fuso orario da una risposta. In questo esempio, il nome dello slot è datetime1. Per ottenere il fuso orario, devi utilizzare:

conv.scene.slots['datetime1'].value.time_zone.id

Richiesta JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "",
    "params": {
      "slot_name": {
        "original": "1",
        "resolved": 1
      }
    },
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "FINAL",
    "slots": {
      "slot_name": {
        "mode": "REQUIRED",
        "status": "SLOT_UNSPECIFIED",
        "updated": true,
        "value": 1
      }
    },
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  },
  "session": {
    "id": "session_id",
    "params": {
      "slot_name": 1
    },
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Invalidare gli slot delle scene

Puoi invalidare gli slot e fare in modo che l'utente fornisca un nuovo valore.

Node.js

conv.scene.slots['slot_name'].status = 'INVALID'

JSON di risposta

{
  "session": {
    "id": "session_id",
    "params": {
      "slot_name": 1
    }
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {
      "slot_name": {
        "mode": "REQUIRED",
        "status": "INVALID",
        "updated": true,
        "value": 1
      }
    },
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  }
}

Opzioni di sviluppo

Actions Builder fornisce un editor incorporato chiamato editor di Cloud Functions, che ti consente di creare ed eseguire il deployment di una Cloud Function for Firebase direttamente nella console. Puoi anche creare ed eseguire il deployment dell'evasione sull'hosting che preferisci e registrare l'endpoint di evasione HTTPS come gestore webhook.

Editor incorporato

Per sviluppare con l'editor Cloud Functions:

Crea il file sdk/webhooks/ActionsOnGoogleFulfillment.yaml e definisci i gestori per l'azione e la funzione cloud inline utilizzata per il fulfillment.
```
handlers:
- name: questionOnEnterFunc
- name: fruitSlotValidationFunc
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment
    
```

Crea la cartella sdk/webhooks/ActionsOnGoogleFulfillment, e aggiungi un file index.js che implementa i gestori definiti in precedenza e un file package.json che definisce i requisiti npm per il tuo codice.

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

const app = conversation();

app.handle('questionOnEnterFunc', conv => {
  conv.add('questionOnEnterFunc triggered on webhook');
});

app.handle('fruitSlotValidationFunc', conv => {
  conv.add('fruitSlotValidationFunc triggered on webhook');
});

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

// package.json
{
  "name": "ActionsOnGoogleFulfillment",
  "version": "0.1.0",
  "description": "Actions on Google fulfillment",
  "main": "index.js",
  "dependencies": {
    "@assistant/conversation": "^3.0.0",
    "firebase-admin": "^5.4.3",
    "firebase-functions": "^0.7.1"
  }
}

Endpoint HTTPS esterno

Questa sezione descrive come configurare Cloud Functions for Firebase come servizio di evasione per l'azione conversazionale. Tuttavia, puoi eseguire il deployment dell'evasione a un servizio di hosting a tua scelta.

Configura l'ambiente

Ti consigliamo la seguente struttura del progetto quando utilizzi Cloud Functions for Firebase come servizio di evasione:

ProjectFolder        - Root folder for the project
  sdk                - Actions project configuration files
  functions          - Cloud functions for Firebase files

Per configurare l'ambiente:

Scarica e installa Node.js.
Configura e inizializza l'interfaccia a riga di comando di Firebase. Se il seguente comando non va a buon fine e viene visualizzato un errore EACCES, potresti dover modificare le autorizzazioni npm.
```
npm install -g firebase-tools
```
Autentica lo strumento Firebase con il tuo Account Google:
```
firebase login
```
Avvia la directory del progetto in cui hai salvato il tuo progetto Azioni. Ti verrà chiesto di selezionare le funzionalità dell'interfaccia a riga di comando di Firebase che vuoi configurare per il tuo progetto Azioni. Scegli Functions e altre funzionalità che potresti voler utilizzare, come Firestore, poi premi Invio per confermare e continuare:
```
$ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init
```
Associa lo strumento Firebase al tuo progetto Azioni selezionandolo con i tasti freccia per navigare nell'elenco dei progetti:

Nota: puoi saltare questo passaggio selezionando [don't setup a default project], ma dovrai eseguire questa associazione in un secondo momento utilizzando il comando firebase use PROJECT_ID.

Dopo aver scelto il progetto, lo strumento Firebase avvia la configurazione di Functions e ti chiede quale lingua vuoi utilizzare. Seleziona utilizzando i tasti freccia e premi Invio per continuare.

=== Functions Setup
A functions directory will be created in your project with a Node.js
package pre-configured. Functions can be deployed with firebase deploy.

? What language would you like to use to write Cloud Functions? (Use arrow keys)
> JavaScript
TypeScript

Scegli se utilizzare ESLint per rilevare i bug probabili e applicare lo stile digitando Y o N:
```
? Do you want to use ESLint to catch probable bugs and enforce style? (Y/n)
```
Recupera le dipendenze del progetto digitando Y al prompt:
```
? Do you want to install dependencies with npm now? (Y/n)
```
Una volta completata la configurazione, vedrai un output simile al seguente:
```
✔  Firebase initialization complete!
```

Installa la dipendenza @assistant/conversation:

$ cd <ACTIONS_PROJECT_DIRECTORY>/functions
$ npm install @assistant/conversation --save

Recupera le dipendenze di fulfillment ed esegui il deployment della funzione di fulfillment:

$ npm install
$ firebase deploy --only functions

Il deployment richiede alcuni minuti. Una volta completato, vedrai un output simile al seguente. Per inserirlo in Dialogflow, avrai bisogno dell'URL della funzione.

✔  Deploy complete!

Project Console: https://console.firebase.google.com/project/<PROJECT_ID>/overview
Function URL (<FUNCTION_NAME>): https://us-central1-<PROJECT_ID>.cloudfunctions.net/<FUNCTION_NAME>

Copia l'URL di fulfillment da utilizzare nella sezione successiva.

Registra il gestore webhook

Crea il file sdk/webhooks/ActionsOnGoogleFulfillment.yaml e definisci i gestori per l'azione e l'URL per le richieste webhook.

httpsEndpoint:
  baseUrl: https://my.web.hook/ActionsOnGoogleFulfillment
  endpointApiVersion: 2
handlers:
- name: questionOnEnterFunc
- name: fruitSlotValidationFunc

Webhook Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Trigger e gestori webhook

Payload

Esempio di richiesta

Esempio di risposta

Interazioni runtime

Inviare prompt

Node.js

JSON di risposta

Parametri dell'intenzione di lettura

Node.js

Richiesta JSON

Lettura delle impostazioni internazionali dell'utente

Node.js

JSON

Lettura e scrittura dello spazio di archiviazione

Node.js

Richiesta JSON

JSON di risposta

Controllare le funzionalità del dispositivo

Node.js

Richiesta JSON

Override del tipo di runtime

Node.js

JSON di risposta

Fornire la distorsione del parlato

Node.js

JSON di risposta

Scene di transizione

Node.js

JSON di risposta

Leggi gli slot delle scene

Node.js

Richiesta JSON

Invalidare gli slot delle scene

Node.js

JSON di risposta

Opzioni di sviluppo

Editor incorporato

Endpoint HTTPS esterno

Configura l'ambiente

Registra il gestore webhook

Webhook