Pub/sub - endpoints - SOAP

Lecture prérequise : Architecture Pub/sub.

Vue d'ensemble

Les messages des sujets pub/sub peuvent être envoyés aux abonnés SOAP. Le contenu ci-dessous décrit comment procéder. Plusieurs étapes sont nécessaires :

  • Création d'une connexion SOAP sortante dans Dashboard, basée sur un fichier WSDL.
  • Création d'un endpoint
  • Création d'un abonnement
  • Création d'un service de hook SOAP

Le serveur SOAP doit exposer un WSDL sur la base duquel Zato crée un pool de clients SOAP pour l'invoquer.

Un service d'accrochage défini par l'utilisateur est nécessaire pour transformer les messages des sujets au format SOAP et pour invoquer le serveur SOAP distant.

Connexions SOAP sortantes

Une définition de connexion pointant vers le serveur SOAP distant est nécessaire pour que Zato sache quel serveur invoquer avec le message pub/sub.

Deux aspects sont importants :

  • Le chemin URL doit être un chemin pointant vers un fichier WSDL.
  • Le type de sérialisation doit être Suds.

Endpoints

En-tête Notes
Name Nom de l'endpoint
Type SOAP
Role Actuellement, doit être toujours Abonné
Topics allowed Une liste de modèles pour les sujets auxquels ce endpoint sera autorisé à s'abonner (c'est-à-dire à recevoir des messages de la part).

Abonnements

En-tête Notes
Type SOAP
Delivery server À partir de quel serveur les messages seront envoyés au serveur SOAP.
Endpoint Un endpoint pub/sub déjà existant au nom duquel les messages seront envoyés au serveur SOAP.
Delivery method Doit être toujours notifié
Delivery batch size Combien de messages au maximum à envoyer en un seul lot
List required Les messages doivent-ils toujours être enveloppés dans un élément de liste, même s'il n'y a qu'un seul message
Delivery max retries Combien de fois faut-il réessayer de livrer un message jusqu'à ce qu'il soit considéré comme non livrable
Sleep on socket error Combien de secondes à passer en veille lors de la réception d'une erreur de socket au niveau TCP dans la communication avec le serveur SOAP
Sleep on error error Comme ci-dessus mais pour les erreurs non liées au socket
Topics Une liste de sujets auxquels s'abonner - seuls les sujets pour lesquels le endpoint choisi a des droits d'abonnement sont affichés.
SOAP outconn Une connexion SOAP sortante permettant d'envoyer des messages.

Services hook SOAP

Étant donné que les messages pub/sub sont le plus souvent envoyés via des endpoints REST en JSON, ou via des fichiers plats, la question se pose de savoir comment faire en sorte que les destinataires SOAP reçoivent des messages formatés en XML.

Cette fonction est remplie par les services hook SOAP attachés facultativement à chaque canal - ils sont invoqués pour chaque lot de messages qui doivent être envoyés aux serveurs SOAP. Leur tâche principale est de transformer les messages du format original en un format attendu par les destinataires SOAP, comme indiqué par le modèle de données dans le WSDL d'un destinataire.

Chaque service a un accès complet aux métadonnées et aux données commerciales sur les messages et les abonnés et le même service hook peut être utilisé pour mettre en œuvre une logique de transformation pour plusieurs sujets ou abonnés.

Les services de crochet ne sont pas limités à la seule transformation. Si cela s'avère nécessaire dans une situation particulière, ils peuvent atteindre d'autres services, d'autres systèmes externes ou peut-être supprimer la publication d'un message donné si des conditions spécifiques l'exigent.

En effet, les services hook ne sont même pas strictement tenus d'invoquer le serveur SOAP - si le service décide que le serveur doit être invoqué, il peut très bien ne pas le faire.

Tant que le service hook ne lève pas d'exception, Zato suppose que le service s'est terminé avec succès et que tous les messages ont été délivrés sans problème. À l'inverse, la levée d'une exception, quelle qu'elle soit, signalera à Zato que la distribution des messages doit être répétée après une courte pause - après autant de secondes que configuré par "Sleep on error error" ci-dessus.

Un service de crochet SOAP sous-classe zato.server.service.PubSubHook et implémente la méthode on_outgoing_soap_invoke, comme ci-dessous :

# -*- coding: utf-8 -*-

# Zato
from zato.server.service import PubSubHook

class MyHook(PubSubHook):
    """ Sample SOAP pub/sub hook.
    """
    def on_outgoing_soap_invoke(self):

        # SOAP hook logic goes here
        pass

Un tel service doit être configuré pour chaque sujet dont les abonnés comprennent des endpoints SOAP - notez que seuls les services qui sous-classent PubSubHook seront affichés dans la liste déroulante HTML.

Chaque service de hook SOAP peut utiliser les attributs suivants, accessibles via self.request.input.ctx, par exemple, self.request.input.ctx.hook_type :

self.request.input.ctx**

Attribut Notes
hook_type Toujours on_topic_outgoing_soap_invoke
outconn_name Nom d'une connexion SOAP sortante à laquelle les données d'entrée doivent être envoyées.
topic Objet décrivant le sujet auquel les données d'entrée ont été envoyées, décrit ci-dessous
msg Contient des données commerciales et des métadonnées sur le(s) message(s) extrait(s) du sujet. Par défaut, il s'agit d'une liste de messages à envoyer à l'extrémité SOAP distante, mais notez que selon la façon dont l'abonnement est configuré (option "list required"), cet élément peut éventuellement être une liste même s'il n'y a qu'un seul message. Chaque message possède une série d'attributs, décrits ci-dessous.

Objet de sujet

Attribut Notes Echantillon
nom Nom du sujet à partir duquel les messages d'entrée sont reçus. Notez qu'il sera également répété avec chaque message. /customer/update/fr

Message object

Attribut Notes Echantillon
msg_id ID du message zpsm20fb970d4014f4d356c50f2a
data Business payload {"acc":"123", "op":"deduct", "amount":"175", "currency":"EUR"}
size Taille des données, en octets (UTF-8) 71
topic_name Sujet auquel ce message a été publié /customer/update/fr
sub_key Clé d'abonnement de l'abonné SOAP zpsk.soap.315383075e2ec2ac2c149c6b
pub_time_iso Date de publication du message, en UTC 2021-07-19T10:13:59.442880
expiration_time_iso Date d'expiration du message, en UTC 2086-08-06T13:28:06.442880
expiration Temps d'expiration en millisecondes depuis pub_time_iso 2147483647000
mime_type Le type MIME des données commerciales text/plain
priority Priorité du message, 1-9 (1=min) 7
delivery_count Combien de tentatives précédentes ont été faites pour délivrer ce message à l'abonné 0
has_gd Le message a-t-il été publié avec la garantie de livraison activée True

Lors de son invocation, un service hook peut transformer chaque message au format attendu par le serveur SOAP et envoyer le résultat, comme ci-dessous.

Notez que l'objet renvoyé par self.outgoing.soap.get est un Suds client SOAP - tout ce que Suds peut faire est également disponible pour le service de hook.

# -*- coding: utf-8 -*-

# Zato
from zato.server.service import PubSubHook

class MyHook(PubSubHook):
    """ Sample SOAP pub/sub hook.
    """
    def on_outgoing_soap_invoke(self):

        # Local aliase
        ctx = self.request.input.ctx

        # Log information that we are about to send out SOAP requests from topic
        self.logger.info('Publishing %d message(s) from topic `%s` to SOAP connection `%s`',
            len(ctx.msg), ctx.topic.name, ctx.outconn_name)

        # Obtain SOAP client from the pool ..
        with self.outgoing.soap.get(ctx.outconn_name).conn.client() as client:

            # .. assume that each business message has this format:
            # {"acc":"123", "op":"deduct", "amount":"157", "currency":"EUR"}

            # .. for each message received from the topic ..
            for item in ctx.msg:

                # .. get a reference to actual business data ..
                data = item.data

                # .. and invoke the SOAP server
                output = client.service.accountDeduct(
                    data['acc'], data['amount'], data['currency'])

                # Log response from the remote SOAP end
                self.logger.info('SOAP status received `%s`', output.StatusCode)

Sujets connexes