Un webhook peut être un webhook standard ou un webhook flexible. Avec un webhook standard, les champs de requête et de réponse sont définis par Dialogflow. Avec un webhook flexible, vous définissez les champs de requête et de réponse.
Webhooks standards
Avec les webhooks standards, vous utilisez les messages de requête et de réponse définis par Dialogflow. Le message de requête fournit de nombreux détails sur la session. Par exemple, la page active actuelle, l'intent mis en correspondance récent, les valeurs de paramètres de session et les réponses définies par l'agent sont tous inclus.
Requête de webhook standard
Lorsqu'un fulfillment avec un webhook est appelé, Dialogflow envoie à votre service de webhook une requête de webhook POST HTTPS.
Le corps de cette requête est un objet JSON WebhookRequest
contenant des informations sur la session.
Certaines intégrations renseignent le champ WebhookRequest.payload
avec des informations supplémentaires.
Par exemple, l'intégration de la passerelle de téléphonie Dialogflow CX fournit l'ID de l'utilisateur final.
Pour en savoir plus, consultez la documentation de référence sur WebhookRequest
(V3) ou WebhookRequest
(V3Beta1).
Réponse webhook standard
Une fois que votre service webhook a reçu une requête de webhook, il doit envoyer une réponse de webhook. Les limites suivantes s'appliquent à votre réponse :
- La réponse doit se produire dans un délai d'expiration que vous configurez lors de la création de la ressource de webhook, sinon la requête expirera.
- La taille de la réponse doit être inférieure ou égale à 64 Kio.
Pour en savoir plus, consultez la documentation de référence sur WebhookResponse
(V3) ou WebhookResponse
(V3Beta1).
Paramètres des ressources de webhook standards
Vous trouverez ci-dessous une description des paramètres des ressources de webhook pour les webhooks standards:
Terme | Définition |
---|---|
Nom à afficher | Nom du webhook affiché dans la console. |
Délai avant expiration du webhook | Lorsque Dialogflow envoie une requête de webhook à votre service de webhook, celui-ci peut expirer en attendant une réponse. Ce paramètre contrôle le délai avant expiration en secondes. En cas d'expiration du délai, Dialogflow appelle un événement webhook.error.timeout. |
Type | Définissez la valeur sur Service directory (Répertoire de service) si vous utilisez l'annuaire de service pour l'accès à un réseau privé. Sinon, définissez-la sur Service Web générique. |
URL du webhook | Indiquez l'adresse URL de votre service de webhook. |
Sous-type | Définie sur Standard |
Webhook spécifique à l'environnement | Vous pouvez fournir des webhooks spécifiques à l'environnement. |
Ratio d'économie d'énergie (EER) | Consultez la section sur l'authentification. |
Certificat CA personnalisé | Ce certificat permet d'importer des certificats CA personnalisés. |
Webhooks flexibles
Avec les webhooks flexibles, vous définissez la méthode HTTP de requête, les paramètres d'URL de requête, ainsi que les champs des messages de requête et de réponse. La requête ne peut fournir que les valeurs de paramètres sélectionnées, et la réponse ne peut fournir que des valeurs de remplacement de paramètres. Cette limitation est en fait utile, car elle simplifie l'interface entre l'agent et le webhook. Il est rarement nécessaire de communiquer autre chose que les valeurs des paramètres de session entre un agent et un webhook. Il simplifie également l'implémentation du webhook, car les messages de requête et de réponse ne contiennent que ce dont vous avez besoin. De plus, vous pouvez fournir des messages de webhook uniques pour divers scénarios.
Requête de webhook flexible
Lors de la création de la ressource de webhook pour votre agent, vous pouvez spécifier les éléments suivants pour les requêtes de webhook:
- Méthode HTTP utilisée pour les requêtes de webhook envoyées au service de webhook.
- Valeurs de paramètre de session que Dialogflow doit envoyer à votre service de webhook à l'aide de l'URL.
- Si vous choisissez la méthode
POST
,PUT
ouPATCH
, vous pouvez spécifier les valeurs des paramètres de session que Dialogflow doit envoyer au service de webhook via le corps JSON de la requête.
Pour envoyer des valeurs de paramètre de session à l'aide de l'URL de requête ou du corps JSON, utilisez des références de paramètres comme vous le feriez normalement. Vous n'avez pas besoin d'échapper la référence du paramètre via une URL, et vous ne l'encapsulez pas entre guillemets. Au moment de l'exécution, Dialogflow échappe l'URL à la valeur du paramètre si nécessaire. Une liste ou une valeur composite sera fournie au format JSON.
Lorsque vous utilisez une référence de paramètre dans le corps JSON, vous devez l'encapsuler entre guillemets, quel que soit le type du paramètre. S'il s'agit d'une valeur numérique scalaire, de liste ou composite, Dialogflow supprime les guillemets lors de l'envoi de la requête au moment de l'exécution afin de préserver le type de données du paramètre. Les types scalaires de chaîne resteront entre guillemets. Si une valeur scalaire, une liste ou une valeur composite numérique est référencée dans une valeur de chaîne (par exemple, "Ceci est un nombre : $session.params.size"), le paramètre est traité comme une chaîne ("Ceci est un nombre : 3").
Par exemple, vous pouvez fournir les valeurs des paramètres de session fruit
et size
à l'URL de la requête comme suit:
https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size
Enfin, dans le corps JSON de la requête, comme ceci:
{
"fruitParameter": "$session.params.fruit",
"sizeParameter": "$session.params.size"
}
Réponse de webhook flexible
Lors de la création de la ressource de webhook pour votre agent, vous pouvez spécifier des paramètres de session que Dialogflow doit définir sur des champs spécifiques de la réponse webhook au moment de l'exécution.
Les limites suivantes s'appliquent à votre réponse :
- La réponse doit se produire dans un délai d'expiration que vous configurez lors de la création de la ressource de webhook, sinon la requête expirera.
- La taille de la réponse doit être inférieure ou égale à 64 Kio.
Utilisez le format suivant pour spécifier un champ scalaire, de liste ou composite:
$.fully.qualified.path.to.field
Prenons l'exemple de la réponse JSON suivante:
{
"routes" : [
{
"legs" : [
{
"distance" : {
"text" : "2,064 mi",
"value" : 3321004
}
}
]
}
]
}
Pour spécifier le champ "value", utilisez ce qui suit:
$.routes[0].legs[0].distance.value
Paramètres des ressources de webhook flexibles
Vous trouverez ci-dessous une description des paramètres des ressources de webhook pour les webhooks flexibles:
Terme | Définition |
---|---|
Nom à afficher | Nom du webhook affiché dans la console. |
Délai avant expiration du webhook | Lorsque Dialogflow envoie une requête de webhook à votre service de webhook, celui-ci peut expirer en attendant une réponse. Ce paramètre contrôle le délai avant expiration en secondes. En cas d'expiration du délai, Dialogflow appelle un événement webhook.error.timeout. |
Type | Définissez la valeur sur Service directory (Répertoire de service) si vous utilisez l'annuaire de service pour l'accès à un réseau privé. Sinon, définissez-la sur Service Web générique. |
URL du webhook | Indiquez l'adresse URL de votre service de webhook, qui peut inclure des références aux paramètres de session. |
Sous-type | Définie sur Flexible |
Méthode | Définissez la méthode HTTP de la requête de webhook. |
Corps de la requête | Fournissez le corps JSON de la requête comme décrit ci-dessus. |
Configuration de la réponse | Indiquez les paramètres de session qui doivent être définis sur les champs de réponse comme décrit ci-dessus. |
Webhook spécifique à l'environnement | Vous pouvez fournir des webhooks spécifiques à l'environnement. |
Ratio d'économie d'énergie (EER) | Consultez la section sur l'authentification. |
Certificat CA personnalisé | Ce certificat permet d'importer des certificats CA personnalisés. |
Conditions requises pour le service de webhook
Votre service de webhook doit remplir les conditions suivantes :
- Il doit gérer les requêtes HTTPS. Le protocole HTTP n'est pas compatible. Si vous hébergez votre service de webhook sur Google Cloud Platform à l'aide d'une solution de calcul ou de calcul sans serveur, consultez la documentation produit pour la diffusion avec HTTPS. Pour connaître les autres options d'hébergement, consultez la page Obtenir un certificat SSL pour votre domaine.
- Son URL pour les requêtes doit être accessible publiquement, sauf si elle est hébergée en tant que fonction Cloud ou en tant que webhook d'annuaire de services.
- Il doit gérer les requêtes et les réponses comme décrit dans la section Webhook standard ou webhook flexible.
- Si votre agent n'intègre pas l'accès au réseau privé de l'annuaire des services, les appels webhook sont considérés comme extérieurs au périmètre de service et sont bloqués lors de l'activation de VPC Service Controls. L'annuaire des services accepte les points de terminaison limités. Pour en savoir plus, consultez l'annuaire des services.
Ratio d'économie d'énergie (EER)
Il est important de sécuriser votre service de webhook, de sorte que vous seul ou votre agent Dialogflow soyez autorisé à effectuer des requêtes. Cette configuration se fait lors de la création d'une ressource webhook. Dialogflow CX est compatible avec les mécanismes d'authentification suivants :
Terme | Définition |
---|---|
En-têtes d'authentification | Pour les paramètres de webhook, vous pouvez spécifier des paires clé/valeur d'en-tête HTTP facultatives. S'ils sont fournis, Dialogflow ajoute ces en-têtes HTTP aux requêtes de webhook. Il est courant de fournir une seule paire avec une clé authorization . Les valeurs d'en-tête sont compatibles avec les références de paramètres de session et l'analyse des fonctions système, comme dans les messages de réponses statiques. |
Authentification de base avec nom d'utilisateur et mot de passe | Pour les paramètres de webhook, vous pouvez spécifier des valeurs de nom d'utilisateur et de mot de passe de connexion facultatives. S'il est fourni, Dialogflow ajoute un en-tête HTTP d'autorisation aux requêtes de webhook. Cet en-tête est au format suivant: "authorization: Basic <base 64 encoding of the string username:password>" . |
OAuth tiers | Vous pouvez spécifier la configuration OAuth tierce de sorte que Dialogflow échange un jeton d'accès provenant du fournisseur OAuth et l'ajoute dans l'en-tête HTTP d'autorisation. Seul le flux d'identifiants client est accepté. |
Jetons d'accès d'agent de service | Vous pouvez sélectionner un jeton d'accès dans "Authentification pour les agents de service" afin d'utiliser les jetons d'accès pour les agents de service pour l'authentification. Elle permet d'accéder à d'autres API Google Cloud. |
Jetons d'ID d'agent de service | Vous pouvez sélectionner un jeton d'ID dans "Authentification pour les agents de service" afin d'utiliser des jetons d'ID d'agent de service pour l'authentification. Permet d'accéder aux services Cloud Functions et Cloud Run. Si aucune autre option d'authentification n'est utilisée, cette option est activée par défaut. |
Authentification TLS mutuelle | Consultez la documentation sur l'authentification TLS mutuelle. |
Validation des certificats HTTPS
Dialogflow utilise par défaut le trust store par défaut de Google pour valider les certificats HTTPS. Si vous avez l'intention d'utiliser des certificats non reconnus par le magasin de confiance par défaut de Google pour votre serveur HTTPS, tels que des certificats autosignés ou des certificats racines personnalisés, consultez la pageCertificats CA personnalisés.
Webhooks spécifiques à l'environnement
Si vous utilisez des environnements pour isoler les systèmes de production des systèmes de développement (recommandé), vous pouvez configurer vos webhooks pour qu'ils soient spécifiques à l'environnement. Pour chaque ressource de webhook que vous définissez, vous pouvez fournir des paramètres d'URL et d'authentification uniques pour chaque environnement que vous avez défini pour l'agent.
Cela vous permet de développer et de tester les mises à jour du code de votre webhook en toute sécurité avant de les déployer en production.
Créer ou modifier des ressources de webhook
Une fois que vous avez un service de webhook en cours d'exécution, vous devez créer une ressource de webhook contenant les informations de connectivité et d'authentification. Après la création, vous pouvez également modifier les paramètres des ressources de webhook à tout moment.
Pour créer ou modifier une ressource de webhook:
Console
- Ouvrez la console Dialogflow CX.
- Choisissez votre projet Google Cloud.
- Sélectionnez votre agent.
- Sélectionnez l'onglet Gérer.
- Cliquez sur Webhooks.
- Cliquez sur Créer ou sur une ressource de webhook de la liste à modifier.
- Saisissez les paramètres de ressources de webhook standards ou les paramètres de ressources de webhook flexibles.
- Cliquez sur Enregistrer.
API
Pour créer une ressource de webhook, consultez la méthode create
correspondant au type Webhook
.
Pour modifier une ressource de webhook (sauf les paramètres spécifiques à l'environnement), consultez la méthode patch
ou update
pour le type Webhook
.
Sélectionnez un protocole et une version pour la référence du webhook :
Protocole | V3 | V3beta1 |
---|---|---|
REST | Ressource de webhook | Ressource de webhook |
RPC | Interface de webhook | Interface de webhook |
C++ | WebhooksClient | Non disponible |
C# | WebhooksClient | Non disponible |
Go | WebhooksClient | Non disponible |
Java | WebhooksClient | WebhooksClient |
Node.js | WebhooksClient | WebhooksClient |
PHP | Non disponible | Non disponible |
Python | WebhooksClient | WebhooksClient |
Ruby | Non disponible | Non disponible |
Pour modifier les paramètres spécifiques à l'environnement d'un webhook, consultez la méthode patch
ou update
pour le type Environment
.
Sélectionnez un protocole et une version pour la référence de l'environnement :
Protocole | V3 | V3beta1 |
---|---|---|
REST | Ressource d'environnement | Ressource d'environnement |
RPC | Interface de l'environnement | Interface de l'environnement |
C++ | EnvironmentsClient | Non disponible |
C# | EnvironmentsClient | Non disponible |
Go | EnvironmentsClient | Non disponible |
Java | EnvironmentsClient | EnvironmentsClient |
Node.js | EnvironmentsClient | EnvironmentsClient |
PHP | Non disponible | Non disponible |
Python | EnvironmentsClient | EnvironmentsClient |
Ruby | Non disponible | Non disponible |
Erreurs de webhook
Si votre service de webhook rencontre une erreur lors du traitement d'une requête de webhook, votre code de webhook doit renvoyer l'un des codes d'état HTTP suivants :
400
Requête incorrecte401
Opération non autorisée403
Interdit404
Introuvable500
Panne du serveur503
Service indisponible
Dans toutes les situations d'erreur suivantes, Dialogflow appelle une erreur de webhook ou un événement intégré, et continue le traitement comme d'habitude :
- Expiration du délai de réponse
- Code d'état d'erreur reçu
- Réponse non valide
- Service de webhook non disponible
En outre, si l'appel de service de webhook a été déclenché par un appel d'API de détection d'intent, le champ queryResult.webhookStatuses
de la réponse de détection d'intent contient les informations d'état du webhook.
Utiliser Cloud Functions
Dialogflow s'intègre à Cloud Functions pour vous permettre de créer facilement un webhook sécurisé sans serveur. Si vous créez une fonction qui réside dans le même projet que votre agent, celui-ci peut appeler en toute sécurité votre webhook sans nécessiter de configuration particulière.
Toutefois, il existe deux situations dans lesquelles vous devez configurer manuellement cette intégration :
- Le compte de service Agent de service Dialogflow avec l'adresse suivante doit exister pour votre projet d'agent :
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Ce compte de service spécial et la clé associée sont normalement créés automatiquement lorsque vous créez le premier agent pour un projet. Si votre agent a été créé avant le 1er novembre 2020, vous pouvez déclencher la création de ce compte de service spécial :- Créez un agent pour le projet.
- exécutez la commande suivante :
gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
- Si votre fonction de webhook se trouve dans un projet différent de celui de l'agent, vous devez fournir le rôle IAM Demandeur Cloud Functions à l'agent de service Dialogflow dans le projet de votre fonction.
Utiliser des webhooks conteneurisés et le framework Go ezcx
Si vous souhaitez implémenter un webhook conteneurisé à l'aide de Go, consultez le framework Go ezcx. Ce framework peut simplifier de nombreuses étapes requises lors de la création d'un webhook.
Utiliser l'Annuaire des services pour l'accès privé au réseau
Dialogflow s'intègre à l'accès au réseau privé de l'Annuaire des services pour pouvoir se connecter aux cibles de webhooks dans votre réseau VPC. Cela permet de conserver le trafic au sein du réseau Google Cloud et d'appliquer IAM et VPC Service Controls.
Pour configurer un webhook ciblant un réseau privé, procédez comme suit :
Suivez la page sur la configuration du réseau privé de l'Annuaire des services pour configurer votre réseau VPC et le point de terminaison de l'Annuaire des services.
Le compte de service Agent de service Dialogflow avec l'adresse suivante doit exister pour votre projet d'agent :
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Attribuez au compte de service Agent de service Dialogflow les rôles IAM suivants:servicedirectory.viewer
du projet de l'Annuaire des servicesservicedirectory.pscAuthorizedService
du projet réseau
Fournissez le service d'annuaire du service avec l'URL et les informations d'authentification facultatives lors de la création du webhook.
Console
API
Consultez le champ
serviceDirectory
pour le typeWebhook
.Sélectionnez un protocole et une version pour la référence du webhook :
Protocole V3 V3beta1 REST Ressource de webhook Ressource de webhook RPC Interface de webhook Interface de webhook C++ WebhooksClient Non disponible C# WebhooksClient Non disponible Go WebhooksClient Non disponible Java WebhooksClient WebhooksClient Node.js WebhooksClient WebhooksClient PHP Non disponible Non disponible Python WebhooksClient WebhooksClient Ruby Non disponible Non disponible
Pour résoudre les problèmes, vous pouvez configurer un test de disponibilité privé afin de vérifier que votre annuaire des services est correctement configuré.
Authentification de l'agent de service
Dialogflow peut générer un jeton d'ID ou un jeton d'accès à l'aide de l'agent de service Dialogflow.
Le jeton est ajouté dans l'en-tête HTTP d'autorisation lorsque Dialogflow appelle un webhook.
Jeton d'ID
Un jeton d'ID peut être utilisé pour accéder aux fonctions Cloud et aux services Cloud Run une fois que vous avez attribué le rôle de demandeur à
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.comSi la fonction Cloud et les services Cloud Run se trouvent dans le même projet de ressources, vous n'avez pas besoin d'autorisations IAM supplémentaires pour les appeler.
L'audience utilisée pour générer le jeton d'ID sera l'intégralité de l'URL de webhook, à l'exception des paramètres de requête. Si vous utilisez Cloud Run, assurez-vous que cette URL est compatible avec les audiences Cloud Run. Par exemple, si l'URL de webhook est
https://myproject.cloudfunctions.net/my-function/method1?query=value
l'URL suivante doit figurer dans les audiences personnalisées.
https://myproject.cloudfunctions.net/my-function/method1
Tout webhook peut également valider le jeton à l'aide de bibliothèques clientes Google ou de bibliothèques Open Source telles que github.com/googleapis/google-auth-library-nodejs.
Jeton d'accès
Un jeton d'accès peut être utilisé pour accéder à d'autres API Google Cloud une fois que vous avez attribué les rôles requis
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Exemples et dépannage
Consultez le guide d'utilisation du webhook.