Services Web

Note : Seuls les utilisateurs avec les droits Administrateur ou Super User peuvent accéder à cette page.

Il est possible de configurer des services web pour y faire appel durant les conversations. Dirigez-vous sur la page Contenus > Web services pour accéder à la page de configuration. Cette page permet de créer un service web REST ou service web SOAP depuis un WSDL. Vous pouvez choisir entre les deux méthodes en cliquant sur le bouton Ajouter puis sélectionnez le type de webservice.

La configuration/modification d'un web service est divisée en plusieurs parties :

• Configuration ;

• Certificat du service web;

• Authentification au service web ;

• Entêtes du service web ;

• Paramètres ;

• Variables de résultat ;

• Boutons d'actions.

Configuration d'un webservice

Note : Une fois le service créé, il n'est pas possible de modifier le type du service web (REST ou SOAP). Cependant, tous les autres champs sont modifiables.

• Le champ Nom permet de configurer le nom du service web, qui sera utilisé pour l'appeler dans la base de connaissances.

• Le champ URL permet de configurer l'URL du service web. Ce doit toujours être une constante.

• Le champ Cache permet de configurer la durée du cache du service web. La valeur 0 supprime le mécanisme de cache.

• Le champ Timeout permet de configurer la durée du timeout du service web. La valeur 0 laisse un timeout standard d'une requête HTTP.

• Le champ Méthode HTTP permet de configurer le type de requête : GET / POST / PUT / DELETE / PATCH. Ceci est surtout utile lors des appels REST.

• Le champ *Type de Réponse vous permet de configurer le type de réponse : XML / plain / Bytes / JSON/ Json params in form .

Configurer un certificat pour un webservice

Une configuration d'un certificat pour un webservice est requise dans le cas où vous voulez assurer la sécurité des communications en ligne entre l'utilisateur/le client et le serveur.

Pour associer un certificat à un web service, vous devez dans un premier temps chiffrer la clé du certificat. Pour cela vous devez aller dans Préférences > Bot > Général. Vous trouverez en bas de page la section " Définir un mot de passe pour chiffrer les certificats des Webservices"

Le mot de passe choisi est définitif. Il ne pourra pas être modifié, ni annulé.

Le format du certificat doit être en PFX (format de fichier permettant de chiffrer le certificat du serveur, les éventuels certificats intermédiaires et la clé privée). Une fois le certificat téléchargé et le mot de passe du certificat renseigné, il est obligatoire de cliquer sur "Enregistrer".

Authentification au service web

Ici, vous pouvez choisir le type d'authentification pour votre service Web (OAUTH_2 / HTTP_BASIC). Une fois sélectionné, vous pouvez remplir les champs Nom d'utilisateur pour l'authentification et Mot de passe pour l'authentification. Toutefois, ces champs peuvent rester vides. Ils ne doivent être configurés que si cela est vraiment nécessaire.

Entêtes du service web

Cette section vous permet d'ajouter des en-têtes HTTP dans l'appel à un service. Ceci est souvent utilisé pour l'authentification.

Paramètres

• Le champ Nom permet de configurer le nom du paramètre.

• Le champ Valeur permet de configurer la valeur du paramètre. Si cette valeur doit être récupérée dans une conversation, il faut indiquer **${capture.**Xxx} avec Xxx qui est le nom de la variable dans la conversation.

• Le champ Valeur de test permet de configurer une valeur pour le paramètre uniquement utilisée lors du test du service web sur la page de configuration (voir les boutons d'actions). Cette valeur n'est pas sauvegardée lorsque vous quittez la page.

Exemple : Dans une connaissance, si la question posée par l’internaute est « Quel temps fait-il à Paris ? » , il est possible de capturer la ville en indiquant dans la connaissance « Quel temps fait-il à ${capture.city} ? ». Des exemples plus complets sont listés sur cette page.

Les paramètres sont encodés en fonction de la méthode HTTP : dans l'URL en GET et dans le corps de la requête en POST / PUT / DELETE.

Variables de résultats

Il est possible de configurer des variables qui pourront être affichées dans une conversation avec l’utilisateur. Cette partie dépendra du champ Type de réponse.

Il est important de noter que :

• les variables récupérées du service web sont structurées comme suit : ${callapi.WebServiceName.variableName};

• les variables récupérées de la boîte de dialogue sont structurées comme suit : ${capture.VariableName}.

Avec une réponse de type XML : il est possible de récupérer des valeurs depuis le résultat en appliquant des fonctions XPath ou XSLT.

Important : les fonctions XPath ou XSLT ne doivent renvoyer que du texte et jamais du XML pour être affichées dans les conversations.

Avec une réponse du type JSON : il est possible de récupérer des valeurs depuis le résultat en exécutant du javascript.

Important : il est nécessaire de créer au moins une fonction javascript nommée « dyduParseJSON » qui renvoie une chaîne de caractères ou un tableau de chaînes de caractères, et qui a pour paramètre le JSON renvoyé par la requête (voir l’exemple REST en bas de page).

Notez que vous pouvez également retourner un message général si le résultat JSON est invalide. La fonction JSON devra alors être :

function dyduParseJSON (json, text) {

return {result: json}

}