Pour encore plus de flexibilité dans la création d'actions, vous pouvez déléguer la logique aux services Web HTTPS (traitement). Vos actions peuvent déclencher des webhooks qui envoient des requêtes à un point de terminaison HTTPS. Voici quelques exemples de ce que vous pouvez faire avec le traitement:
- Générer une invite dynamique en fonction des informations fournies par l'utilisateur
- Commander sur un système externe et confirmer la réussite.
- Valider des emplacements avec des données backend
Déclencheurs et gestionnaires de webhooks
Vos actions peuvent déclencher un webhook dans des intents d'appel ou des scènes, ce qui envoie une requête à votre point de terminaison de fulfillment. Votre traitement contient des gestionnaires de webhooks qui traitent la charge utile JSON dans la requête. Vous pouvez déclencher des webhooks dans les situations suivantes:
- Après une correspondance d'intent d'appel
- Pendant l'étape d'entrée d'une scène
- Lorsqu'une condition est définie sur "true" dans l'étape de condition d'une scène
- Durant la phase de remplissage d'emplacements d'une scène
- Après une correspondance d'intent lors de l'étape d'entrée d'une scène
Lorsque vous déclenchez un webhook dans vos actions, l'Assistant Google envoie une requête avec une charge utile JSON à votre traitement, qui contient le nom du gestionnaire à utiliser pour traiter l'événement. Votre point de terminaison de fulfillment peut acheminer l'événement vers le gestionnaire approprié pour exécuter la logique et renvoyer une réponse avec une charge utile JSON.
Charges utiles
Les extraits de code suivants montrent des exemples de requêtes que vos actions envoient au traitement, ainsi qu'une réponse renvoyée par votre traitement. Pour en savoir plus, consultez la documentation de référence.
Exemple de requête
{
"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"
]
}
}
Exemple de réponse
{
"session": {
"id": "example_session_id",
"params": {}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "Hello World.",
"text": ""
}
},
"scene": {
"name": "SceneName",
"slots": {},
"next": {
"name": "actions.scene.END_CONVERSATION"
}
}
}
Interactions d'exécution
Les sections suivantes décrivent les tâches courantes que vous pouvez effectuer dans vos gestionnaires de webhooks.
Envoyer des invites
Vous pouvez créer des invites avec du texte simple, du texte enrichi, des fiches et même des invites HTML complètes à l'aide d'une application Web avec le Canevas interactif. La documentation sur les invites contient des informations complètes sur la création d'une invite lors de la gestion d'un événement webhook. Les extraits suivants présentent une invite de fiche:
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'
})
}));
});
Réponse JSON
{
"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": ""
}
}
}
Lire les paramètres d'intent
Lorsque l'environnement d'exécution de l'Assistant correspond à un intent, il extrait tous les paramètres définis. La propriété d'origine correspondait à la valeur saisie par l'utilisateur, tandis que la propriété résolue correspond à celle à laquelle la NLU a résolu l'entrée en fonction de la spécification du type.
Node.js
conv.intent.params['param_name'].original
conv.intent.params['param_name'].resolved
Requête 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"
]
}
}
Lire les paramètres régionaux de l'utilisateur
Cette valeur correspond au paramètre régional de l'utilisateur pour l'Assistant 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"
]
}
}
Stockage en lecture et écriture
Consultez la documentation sur le stockage pour découvrir comment utiliser différentes fonctionnalités de stockage.
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
Requête 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"
]
}
}
Réponse JSON
{
"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"
}
}
}
Vérifier les fonctionnalités de l'appareil
Vous pouvez vérifier les fonctionnalités d'un appareil pour proposer différentes expériences ou différents flux de conversation.
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");
Requête 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"
]
}
}
Pour obtenir la liste complète des fonctionnalités de surface, consultez la documentation de référence sur Capability.
Remplacements de type d'exécution
Les types d'exécution vous permettent de modifier les spécifications de type au moment de l'exécution. Vous pouvez utiliser cette fonctionnalité pour charger des données à partir d'autres sources afin de renseigner les valeurs valides d'un type. Par exemple, vous pouvez utiliser des remplacements de type d'exécution pour ajouter des options dynamiques à une question d'enquête ou pour ajouter un élément quotidien à un menu.
Pour utiliser les types d'exécution, vous déclenchez un webhook qui appelle un gestionnaire dans votre traitement à partir de votre action. Vous pouvez alors renseigner le paramètre session.typeOverrides dans une réponse à votre action. Les modes disponibles incluent TYPE_MERGE pour conserver les entrées de type existant ou TYPE_REPLACE pour remplacer les entrées existantes par les valeurs de remplacement.
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']
},
]
}
}];
Réponse JSON
{
"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."
}
}
}
Fournir une pondération de la parole
La pondération de la voix vous permet de spécifier des indices de niveau NLU pour améliorer la mise en correspondance des intents. Vous pouvez spécifier jusqu'à 1 000 entrées.
Node.js
conv.expected.speech = ['value_1', 'value_2']
conv.expected.language = 'locale_string'
Réponse JSON
{
"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"
}
}
Scènes de transition
En plus de définir des transitions statiques dans votre projet Actions, vous pouvez provoquer des transitions de scène au moment de l'exécution.
Node.js
app.handle('transition_to_hidden_scene', conv => {
// Dynamic transition
conv.scene.next.name = "HiddenScene";
});
Réponse JSON
{
"session": {
"id": "session_id",
"params": {}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "This is an example prompt.",
"text": ""
}
},
"scene": {
"name": "SceneName",
"slots": {},
"next": {
"name": "HiddenScene"
}
}
}
Lire les emplacements de la scène
Pendant le remplissage d'emplacements, vous pouvez utiliser le fulfillment pour valider l'emplacement ou vérifier l'état du remplissage d'emplacements (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
Par exemple, supposons que vous souhaitiez extraire le fuseau horaire d'une réponse. Dans cet exemple, le nom de l'emplacement est datetime1. Pour obtenir le fuseau horaire, utilisez:
conv.scene.slots['datetime1'].value.time_zone.id
Requête 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"
]
}
}
Invalider les emplacements de scène
Vous pouvez invalider des emplacements et demander à l'utilisateur d'indiquer une nouvelle valeur.
Node.js
conv.scene.slots['slot_name'].status = 'INVALID'
Réponse JSON
{
"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"
}
}
}
Options de développement
Actions Builder fournit un éditeur intégré appelé éditeur Cloud Functions, qui vous permet de créer et de déployer une fonction Cloud pour Firebase directement dans la console. Vous pouvez également créer et déployer le fulfillment sur l'hébergement de votre choix, puis enregistrer votre point de terminaison de traitement HTTPS en tant que gestionnaire de webhooks.
Éditeur intégré
Pour développer avec l'éditeur Cloud Functions:
- Ouvrez votre projet Actions et accédez à l'onglet Develop > Webhook > Change fulfillment method (Développer > Webhook > Modifier la méthode de traitement). La fenêtre Modes de traitement s'affiche.
- Sélectionnez Inline Cloud Functions, puis cliquez sur Confirm (Confirmer).
Point de terminaison HTTPS externe
Cette section explique comment configurer Cloud Functions for Firebase en tant que service de traitement de vos actions de conversation. Toutefois, vous pouvez déployer le traitement sur le service d'hébergement de votre choix.
Configurer l'environnement
Pour configurer votre environnement, procédez comme suit :
- Téléchargez et installez Node.js.
Configurez et initialisez la CLI Firebase. Si la commande suivante échoue avec une erreur
EACCES, vous devrez peut-être modifier les autorisations npm.npm install -g firebase-toolsAuthentifiez l'outil Firebase avec votre compte Google:
firebase loginDémarrez le répertoire dans lequel vous avez enregistré votre projet Actions. Vous êtes invité à sélectionner les fonctionnalités de la CLI Firebase que vous souhaitez configurer pour votre projet Actions. Choisissez
Functionset d'autres fonctionnalités que vous pouvez utiliser, comme Firestore, puis appuyez sur Entrée pour confirmer et continuer:$ cd <ACTIONS_PROJECT_DIRECTORY> $ firebase initAssociez l'outil Firebase à votre projet Actions en le sélectionnant à l'aide des touches fléchées pour parcourir la liste des projets:
Une fois le projet sélectionné, l'outil Firebase lance la configuration de Functions et vous demande le langage que vous souhaitez utiliser. Sélectionnez les touches à l'aide des flèches, puis appuyez sur Entrée pour continuer.
=== 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
Indiquez si vous souhaitez utiliser ESLint pour détecter les bugs potentiels et appliquer le style en saisissant Y ou N:
? Do you want to use ESLint to catch probable bugs and enforce style? (Y/n)
Pour obtenir les dépendances du projet, saisissez Y dans l'invite:
? Do you want to install dependencies with npm now? (Y/n)
Une fois la configuration terminée, un résultat semblable aux lignes suivantes doit s'afficher:
✔ Firebase initialization complete!Installez la dépendance @assistant/conversation:
$ cd <ACTIONS_PROJECT_DIRECTORY>/functions $ npm install @assistant/conversation --saveRécupérez les dépendances de traitement et déployez la fonction de traitement:
$ npm install $ firebase deploy --only functionsLe déploiement prend quelques minutes. Une fois l'opération terminée, un résultat semblable aux lignes suivantes doit s'afficher. Vous aurez besoin de l'URL de la fonction pour la saisir dans Dialogflow.
✔ 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>Copiez l'URL de traitement à utiliser dans la section suivante.
Enregistrer le gestionnaire de webhooks
Pour enregistrer votre point de terminaison Cloud Functions en tant que gestionnaire de webhooks:
- Dans la console Actions, cliquez sur Develop > Webhook (Développer > Webhook).
- Cliquez sur Modifier la méthode de traitement. La fenêtre Fulfillment Methods (Méthodes de traitement) s'affiche.
- Sélectionnez Webhook et cliquez sur Confirmer.
- Collez l'URL de votre service Web dans le champ Webhook.
- Cliquez sur Enregistrer.