Transmission de données

Les 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 fournissent les fonctions d'importation et d'exportation pour le système VoiceCheck.

Les services et les formats de message sont décrits en détail ci-dessous, ainsi que le XML de référence pour le langage de description WSDL du service Web SOAP et le langage de description WADL du service Web REST, sont fournis dans le package du produit. Il était auparavant possible d'afficher les descriptions des services en entrant http://<hôte>:<port>/VoiceCheck/services/api/swagger.json dans le navigateur Web. Ce lien remplace le lien http://<hôte>:<port>/VoiceCheck/services utilisé précédemment.

Flux de messages des services Web

Configuration et sécurité

Toutes les communications sont réalisées en 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 via WS-Security UsernameToken. Pour l'importation, tous les services Web REST exigent une authentification utilisant l'authentification de base HTTP.

VoiceCheck a un rôle d'accès, configurable dans l'interface utilisateur, qui détermine les autorisations d'un utilisateur pour l'exécution des services Web. Les clients des services Web du système hôte doivent être configurés pour s'authentifier auprès des services Web VoiceCheck en tant qu'utilisateur possédant ce rôle.

Pour l'exportation de données, VoiceCheck prend en charge l'authentification de base HTTP pour accéder à un service Web SOAP ou REST sur le système hôte. L'authentification est facultative mais, si elle est utilisée, elle est configurée dans VoiceCheck. 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 de point de terminaison du service pour les services fournis par le système hôte. Cette URL est un paramètre obligatoire dans l'interface utilisateur graphique.

Un seul nom d'utilisateur et mot de passe uniques sont utilisés pour exploiter tous les services que le système hôte expose pour VoiceCheck. Actuellement, un seul service est exposé pour VoiceCheck afin d'afficher les résultats de la tâche sur le système hôte.

Les informations de configuration (point de terminaison du 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 dans la page Administration > Configuration système. La configuration suppose qu'une instance de VoiceCheck se connecte à un seul point de terminaison du système hôte.

Schémas XML et espaces de noms

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 note ci-dessous). L'espace de noms est le suivant :

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

Pour les services SOAP que VoiceCheck fournit pour l'importation de données, trouvez l'espace de noms et le schéma en WSDL.

Pour les services REST que VoiceCheck fournit pour l'importation de données, trouvez l'espace de noms et le schéma en WADL. Notez que pour le service Web Créer une tâche, les clients REST n'ont pas à qualifier le XML avec l'espace de noms ; cependant, cette procédure est fortement recommandée.

Pour le service REST que VoiceCheck exploite afin d'afficher les résultats de tâche sur un système hôte, l'espace de noms et le schéma que le serveur s'attend à voir dans le XML sont définis dans l'exemple de WADL fourni dans le profil du produit.

L'élément faultInfo n'est pas défini comme faisant partie d'un espace de noms. Pour les services REST, VoiceCheck ne qualifie pas l'élément à l'aide d'un espace de noms lorsqu'il est envoyé dans une réponse d'erreur à un système hôte. De même, le système hôte ne doit pas qualifier un élément faultInfo à l'aide d'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 de statut HTTP peuvent être renvoyés en fonction de l'échec et de l'emplacement où l'échec s'est produit pendant le traitement. VoiceCheck utilise le framework Apache^® CXF pour le traitement des demandes de services Web et ce cadre peut renvoyer des erreurs pendant le traitement (par exemple 406 - Non acceptable ou 415 - Type de média non pris en charge), avant que la logique métier de VoiceCheck ne soit atteinte.

Les erreurs provenant de la logique métier de VoiceCheck ne possèdent qu'un seul des deux codes de statut :

• 400 - Demande incorrecte : le client a enfreint une règle ou une contrainte métier (généralement des données incorrectes). Le fait de renvoyer le message sans en modifier le contenu entraîne la même erreur.
• 500 - Erreur de serveur interne : une erreur de serveur interne s'est produite lors du traitement de la demande. La réitération du message PEUT aboutir à un succès.

De plus, les erreurs provenant de la logique métier de VoiceCheck comprennent un élément XML faultInfo qui contient des informations supplémentaires 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

Les erreurs SOAP 1.1 sont renvoyées pour toutes les erreurs. Toutes les erreurs contiennent un code d'erreur et une chaîne d'erreurs comme spécifié dans SOAP 1.1. Deux des principaux codes d'erreur SOAP 1.1, Client et Serveur, sont spécifiés pour la plupart des erreurs. VoiceCheck utilise généralement ces codes de la manière décrite dans la spécification SOAP 1.1.

Ces erreurs peuvent se produire lors de l'authentification si des codes d'erreur spécifiés dans WS-Security (services Web de sécurité). Les API des services Web Java et les implémentations peuvent renvoyer d'autres codes d'erreur.

Bien qu'il ne soit pas possible de lister tous les codes d'erreur susceptibles de se produire, il existe des règles générales qui peuvent permettre un traitement cohérent des erreurs par les clients des services Web :

• Les codes d'erreur autres que ceux du serveur signifient généralement qu'il ne sert à rien de renvoyer automatiquement le message. Ils sont envoyés lorsque le client a fait une mauvaise manipulation avant que la transmission n'atteigne la logique d'application sur le serveur, comme des échecs d'authentification ou des messages mal formés.
• Lorsque le code d'erreur est Serveur, si l'erreur provient de la logique du serveur d'applications, il comprend l'élément de détail d'erreur SOAP 1.1. Le format est spécifié en WSDL, mais contient les informations de la section ci-dessous.

Élément d'information sur l'erreur

Les services Web REST et SOAP comprennent tous deux les mêmes informations d'erreur lorsqu'une erreur provient de la logique du serveur d'applications VoiceCheck.

L'implémentation REST du serveur hôte pour les résultats post-tâche doit utiliser cet élément d'information sur l'erreur afin d'afficher le message d'erreur dans l'interface utilisateur graphique de VoiceCheck. Sinon, l'utilisateur voit un message générique.

Propriété	Type	Définition
errorCode	long	Code numérique représentant l'erreur. Valeurs valides : 3000 = Erreur interne du serveur (la demande peut ou non aboutir lors d'une nouvelle tentative) 3001 = Demande incorrecte (il n'est pas recommandé de réessayer la demande automatisée)
message	chaîne	Message lisible par l'utilisateur expliquant l'erreur.