Webhooks

Pour vous offrir encore plus de flexibilité dans la création d'actions, vous pouvez déléguer la logique à des 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 dans le traitement :

  • Générer un prompt dynamique en fonction des informations fournies par l'utilisateur.
  • Passer une commande dans un système externe et confirmer sa réussite.
  • Valider des emplacements avec des données de backend.
Figure 1. Les intents d'appel et les scènes peuvent déclencher des webhooks.

Déclencheurs et gestionnaires de webhooks

Vos actions peuvent déclencher un webhook dans des intents d'appel ou des scènes, qui envoie une requête à votre point de terminaison de traitement. Votre traitement contient des gestionnaires de webhooks qui traitent la charge utile JSON de la requête. Vous pouvez déclencher des webhooks dans les cas suivants :

  • Après une correspondance d'intent d'appel
  • Pendant la phase d'entrée d'une scène
  • Une fois qu'une condition est évaluée comme "true" dans la phase de condition d'une scène
  • Pendant la phase de remplissage d'emplacements d'une scène
  • Après une correspondance d'intent dans la phase 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 traitement peut acheminer l'événement vers le gestionnaire approprié pour exécuter la logique et renvoyer une réponse correspondante avec une charge utile JSON.

Charges utiles

Les extraits de code suivants montrent des exemples de requêtes que vos actions envoient au traitement et une réponse que votre traitement renvoie. 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 lors de l'exécution

Les sections suivantes décrivent les tâches courantes que vous pouvez effectuer dans vos gestionnaires de webhooks.

Envoyer des prompts

Vous pouvez créer des prompts avec du texte simple, du texte enrichi, des cartes et même des prompts HTML complets basés sur une application Web avec Interactive Canvas. La documentation sur les prompts fournit des informations complètes sur la création d'un prompt lors de la gestion d'un événement de webhook. Les extraits de code suivants montrent un prompt de carte :

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 met en correspondance un intent, il extrait tous les paramètres définis. La propriété d'origine correspond à ce que l'utilisateur a fourni comme entrée, et la propriété résolue correspond à ce que la NLU a résolu comme entrée en fonction de la spécification de 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"
    ]
  }
}

Lire et écrire dans le stockage

Pour obtenir des informations complètes sur l'utilisation des différentes fonctionnalités de stockage, consultez la documentation sur le 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 offrir 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 Capability documentation de référence.

Remplacements de types d'exécution

Les types d'exécution vous permettent de modifier les spécifications de type lors de l'exécution. Vous pouvez utiliser cette fonctionnalité pour charger des données provenant d'autres sources afin de renseigner les valeurs valides d'un type. Par exemple, vous pouvez utiliser des remplacements de types d'exécution pour ajouter des options dynamiques à une question d'enquête ou pour ajouter un élément quotidien à un menu.

Pour utiliser des types d'exécution, vous déclenchez un webhook à partir de votre action qui appelle un gestionnaire dans votre traitement. À partir de là, vous pouvez 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 existantes ou TYPE_REPLACE pour remplacer les entrées existantes par les remplacements.

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 vocale

La pondération vocale vous permet de spécifier des indices à la 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 faire en sorte que des transitions de scène se produisent lors 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 scène

Lors du remplissage d'emplacements, vous pouvez utiliser le traitement 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

Supposons, par exemple, 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, vous devez utiliser :

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 de fournir 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 Functions for Firebase directement dans la console. Vous pouvez également créer et déployer le traitement sur l'hébergement de votre choix, et enregistrer votre point de terminaison de traitement HTTPS en tant que gestionnaire de webhook.

Éditeur intégré

Pour développer avec l'éditeur Cloud Functions :

  1. Ouvrez votre projet Actions, puis accédez à Develop tab > Webhook > Change fulfillment method (Onglet "Développer" > Webhook > Modifier la méthode de traitement). La fenêtre Fulfillment methods (Méthodes de traitement) s'affiche.
  2. Sélectionnez Inline Cloud Functions (Fonctions Cloud Functions intégrées), 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 pour votre action conversationnelle. 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 :

  1. Téléchargez et installez Node.js.

  2. 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-tools

  3. Authentifiez l'outil Firebase avec votre compte Google :

    firebase login

  4. Démarrez le répertoire du projet dans lequel vous avez enregistré votre projet Actions. Vous serez invité à sélectionner les fonctionnalités de la CLI Firebase que vous souhaitez configurer pour votre projet Actions. Choisissez Functions et d'autres fonctionnalités que vous souhaitez utiliser, comme Firestore, puis appuyez sur Entrée pour confirmer et continuer :

    $ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init

  5. Associez l'outil Firebase à votre projet Actions en le sélectionnant à l'aide des touches fléchées pour parcourir la liste des projets :

  6. Une fois le projet choisi, l'outil Firebase démarre la configuration des fonctions et vous demande la langue que vous souhaitez utiliser. Sélectionnez la langue à l'aide des touches fléchées, 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

  7. 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)

  8. Obtenez les dépendances du projet en saisissant Y dans l'invite :

    ? Do you want to install dependencies with npm now? (Y/n)

    Une fois la configuration terminée, vous verrez un résultat semblable à celui-ci :

    ✔  Firebase initialization complete!

  9. Installez la dépendance @assistant/conversation :

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

  10. Obtenez les dépendances de traitement et déployez la fonction de traitement :

    $ npm install
$ firebase deploy --only functions

    Le déploiement prend quelques minutes. Une fois terminé, vous verrez un résultat semblable à celui-ci. Vous aurez besoin de l'URL de la fonction à 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>

  11. Copiez l'URL de traitement à utiliser dans la section suivante.

Enregistrer le gestionnaire de webhook

Pour enregistrer votre point de terminaison Cloud Functions en tant que gestionnaire de webhook :

  1. Dans la console Actions, cliquez sur Develop > Webhook (Développer > Webhook).
  2. Cliquez sur Change fulfillment method (Modifier la méthode de traitement). La fenêtre Fulfillment methods (Méthodes de traitement) s'affiche.
  3. Sélectionnez Webhook , puis cliquez sur Confirm (Confirmer).
  4. Collez l'URL de votre service Web dans le champ Webhook.
  5. Cliquez sur Save (Enregistrer).