Transmission des données

Des services Web sont utilisés pour envoyer des données transactionnelles entre le système hôte et Vocollect VoiceCheck. VoiceCheck prend en charge les services Web SOAP et REST. Ces services assurent les fonctions d'importation et d'exportation du système VoiceCheck.

Les services et les formats de messages sont décrits en détail ci-dessous, et les fichiers XML de référence pour les formats WSDL (Web Service Description Language) de services SOAP et WADL (Web Application Description Language) de services REST sont fournis dans le progiciel. Une description des services pouvait auparavant être affichée en entrant http://<hôte>:<port>/VoiceCheck/services/api/swagger.json dans votre navigateur Web. Ce lien remplace l’ancien lien http://<hôte>:<port>/VoiceCheck/services.

Flux de messages des services Web

Configuration et sécurité

Toutes les communications sont effectuées via HTTP ou HTTPS, selon la configuration de VoiceCheck.

Pour l'importation de données, tous les services Web SOAP fournis par VoiceCheck exigent une authentification à l'aide de WS-Security UsernameToken. Tous les services Web REST utilisés pour l’importation exigent une authentification par le protocole d’authentification de base HTTP.

VoiceCheck possède un rôle d'accès, configurable dans l'interface utilisateur, qui détermine les services Web qu'un utilisateur est autorisé à exécuter. Les clients de services Web du système hôte doivent être configurés pour être authentifiés auprès des services Web VoiceCheck en tant qu'utilisateurs détenant ce rôle.

Pour l'exportation de données, VoiceCheck permet d'utiliser l'authentification de base HTTP pour accéder à un service Web SOAP ou REST sur le système hôte. L’authentification est optionnelle mais si elle est utilisée, elle est configurée dans VoiceCheck et le mot de passe est chiffré et stocké dans la base de données VoiceCheck.

VoiceCheck fournit également une méthode pour configurer l’URL du point de terminaison des services fournis par le système hôte. Cette URL du point de terminaison est un paramètre obligatoire dans l’interface utilisateur.

Un seul nom d’utilisateur et un seul mot de passe sont utilisés pour consommer tous les services exposés par le système hôte pour VoiceCheck. Actuellement, un seul service est exposé pour permettre à VoiceCheck de publier les résultats des tâches dans le système hôte.

Les informations de configuration (point de terminaison de service, type de client du service Web, nom d'utilisateur et mot de passe) sont définies au niveau du système dans VoiceCheck. Ces paramètres se trouvent à la page Administration > Configuration du système. La configuration suppose qu’une seule instance de VoiceCheck se connectera à un seul point de terminaison du système hôte.

Schémas et espaces de noms XML

VoiceCheck déclare un espace de noms pour tous les éléments XML utilisés dans les services SOAP et REST, à l’exception de l’élément faultInfo (voir la remarque ci-dessous). Cet espace de noms est :

http://service.web.voicecheck.vocollect.com/

Pour les services SOAP fournis par VoiceCheck pour l'importation de données, vous trouverez l'espace de noms et le schéma dans le fichier WSDL.

Pour les services REST fournis par VoiceCheck pour l'importation de données, vous trouverez l'espace de noms et le schéma dans le fichier WADL. Notez que pour le service Web de création de tâches, la qualification du fichier XML avec l’espace de noms n’est pas exigée pour les clients REST, quoique vivement recommandée.

Pour le service REST consommé par VoiceCheck afin de publier des résultats de tâches vers un système hôte, l'espace de noms et le schéma attendus par le serveur dans le fichier XML sont définis dans l'exemple de fichier WADL fourni dans le progiciel.

L’élément faultInfo n’est pas défini en tant que partie intégrante d’un espace de noms. Pour les services REST, VoiceCheck ne qualifie pas l'élément avec un espace de noms lorsque celui-ci est envoyé dans une réponse d'erreur vers un système hôte. De la même façon, le système hôte ne doit pas qualifier un élément faultInfo avec un espace de noms dans une réponse à VoiceCheck.

Traitement des erreurs pour les données de tâche

Traitement des erreurs REST

En cas d'échec, différents codes d'état HTTP peuvent être renvoyés selon la nature et l'emplacement de l'échec en cours de traitement.VoiceCheck fait appel à l'infrastructure Apache^® CXF pour traiter les demandes de services Web, et cette infrastructure peut renvoyer des erreurs pendant ce traitement telles que « 406 – Not Acceptable » (Non acceptable) ou « 415 – Unsupported Media Type » (Type de support non pris en charge), avant qu'une communication ne soit établie avec la logique métier de VoiceCheck.

Deux codes d’état seulement peuvent être attribués aux erreurs provenant de la logique métier VoiceCheck :

• 400 – Bad Request (Demande incorrecte) : le client a enfreint une règle métier ou une contrainte (en général, données incorrectes). Le renvoi du message sans modifier le contenu engendrera la même erreur.
• 500 – Internal Server Error (Erreur interne du serveur) : une erreur interne du serveur s’est produite pendant le traitement de la demande. Il est alors POSSIBLE de renvoyer le message avec succès.

De même, les erreurs provenant de la logique métier VoiceCheck comprennent un élément XML faultInfo contenant un complément d’information sur l’erreur qui s’est produite. Les propriétés de l’élément faultInfo sont indiquées ci-dessous.

Traitement des erreurs SOAP

Des erreurs SOAP 1.1 sont renvoyées pour toutes les erreurs. Toutes les erreurs contiennent un code d’erreur et une chaîne d’erreur conformes aux spécifications de SOAP 1.1. Deux des principaux codes d'erreur de SOAP 1.1, Client et Serveur, sont indiqués pour la plupart des erreurs. VoiceCheck utilise généralement ces codes selon la méthode décrite dans la spécification SOAP 1.1.

Certaines erreurs susceptibles de se produire lors de l’authentification utilisent des codes d’erreur spécifiés dans WS-Security (Web Services Security). Les interfaces API et implémentations de services Web Java peuvent renvoyer d’autres codes d’erreur.

S’il est impossible d’énumérer tous les codes d’erreur susceptibles de se produire, il existe un certain nombre de règles générales permettant de traiter uniformément les erreurs par les clients de services Web :

• Les codes d’erreur autres que Serveur signifient habituellement qu’il est inutile de renvoyer automatiquement le message. Ils sont envoyés lorsque le client a commis une erreur avant que la transmission ne parvienne à la logique de l’application sur le serveur, par exemple, en cas d’échec d’authentification ou de message formulé incorrectement.
• Pour les codes d’erreur de type Serveur, si l’erreur provient de la logique du serveur de l’application, elle contiendra l’élément détail d’erreur SOAP 1.1. Le format est spécifié dans le fichier WSDL, mais contient les informations décrites dans la section ci-dessous.

Élément d’information sur l’erreur

Les services Web REST et SOAP contiennent les mêmes informations d’erreur lorsque celle-ci provient de la logique du serveur d’application VoiceCheck.

L'implémentation REST du serveur hôte pour la publication des résultats de tâches doit utiliser cet élément d'information sur l'erreur afin d'afficher le message d'erreur dans l'interface utilisateur de VoiceCheck; sinon, l'utilisateur verra un message générique.

Propriété	Type	Définition
errorCode	long	Code numérique représentant l’erreur. Valeurs valides : 3000 = Internal server error (le renvoi de la demande peut aboutir ou pas) 3001 = Bad request (renvoi automatique de la demande non recommandé)
message	chaîne	Message interprétable par l'utilisateur expliquant l'erreur.