Tutoriel - partie 1/2

Introduction

Veuillez lire ceci high-level overview si vous ne l'avez pas déjà fait pour une introduction sur la façon dont Zato et Python aident à l'intégration des systèmes complexes et avancés.

Ce tutoriel de programmation Zato vous guidera à travers le processus de création d'un service API du monde réel qui, avec Python, intégrera trois applications en utilisant REST et AMQP. Le résultat sera une solution prête à être utilisée en production.

Mais d'abord, voici quelques exemples concrets de ce à quoi Zato peut servir :

• Une plateforme pour le traitement des paiements provenant des appareils des consommateurs

• Un système pour un opérateur de télécommunication intégrant les systèmes CRM, ERP, de facturation et autres ainsi que les applications des partenaires externes de l'opérateur.

• Un système de data science pour le traitement des informations relatives aux transactions sur titres (FIX)

• Une plateforme pour les systèmes d’administration publique, permettant de réaliser l'interopérabilité des données de santé par l'intégration de sources de données indépendantes, de bases de données et d'échanges d'informations sur la santé (HIE)

• Une plateforme globale plateforme IoT intégrant des dispositifs médicaux.

• Une plateforme de traitement des événements produits par les systèmes d'alerte précoce

• Des systèmes backend e-commerce gérant plusieurs fournisseurs, places de marché et flux de processus.

• Des plateformes B2B pour accepter et traiter des commandes multicanaux en coopération avec des systèmes backend ERP et CRM.

• Plateformes intégrant des applications immobilières, collectant des données à partir de sources de données indépendantes pour présenter des API unifiées aux applications internes et externes.

• Un système pour la gestion des ressources matérielles d'un fournisseur d’entreprise cloud

• Sites d'enchères en ligne

• Plateforme d'apprentissage en ligne

Ce qu'ils ont tous en commun, c'est le niveau de complexité des processus d'intégration. Il est typique pour de tels environnements d'avoir au moins plusieurs, voire plusieurs dizaines ou plusieurs centaines d'applications indépendantes échangeant des messages, chacune utilisant éventuellement une technologie et un format de données différents.

Il est à noter que Zato est une plateforme et les échantillons couvrent plusieurs industries et domaines distincts. La plate-forme peut-être utilisée dans toutes sortes de scénarios qui nécessitent l'intégration de systèmes distribués.

Services API

Si Zato est une plate-forme pour les services API, qu'est-ce qu'un service ?

Par essence, un service est un élément de fonctionnalité côté serveur qui exécute une action commerciale utile et intéressante pour les applications qui souhaitent l'utiliser. Il s'agit d'une définition de haut niveau et c'est la bonne façon d'y penser.

Tout cela découle du fait que vous devez penser aux systèmes et aux applications qui composent votre architecture en termes de consommateurs et de fournisseurs de services. Chaque partie de l'architecture offre des services aux autres parties et, inversement, chaque partie consomme des services offerts par d'autres éléments de l'architecture. Pris ensemble, les services forment des processus de niveau supérieur répondant aux besoins de l'entreprise définis avant l'architecture informatique.

Zato est une plate-forme multi-protocoles et les services ne sont souvent pas liés à un protocole spécifique. Cela signifie qu'il est possible de concevoir des services qui peuvent être invoqués via REST, mais qui peuvent également écouter des données provenant de files d'attente AMQP, IBM MQ ou des bases de données SQL. Ils peuvent également accepter des messages HL7 MLLP, SOAP, WebSocket, SFTP, FTP, e-mail, JSON-RPC et ZeroMQ.

Naturellement, REST est omniprésent et c'est généralement de cette manière que la plupart des API sont exposées, mais il existe d'autres moyens et, dans divers scénarios, d'autres moyens de communication sont utilisés.

Zato est livré avec des connecteurs et des adaptateurs pour REST, AWS S3, AMQP, MongoDB, Redis, HL7, Odoo, SAP, IBM MQ, SQL, SOAP, FTP, SFTP, LDAP, Cassandra, Dropbox, Twilio, IMAP, SMTP, ElasticSearch, Solr, Swift, Slack, Telegram, WebSockets et ZeroMQ. Étant donné qu'il est écrit en Python, vous avez accès à de nombreuses bibliothèques tierces qui fournissent une connectivité à d'autres types de systèmes.

Les plateformes d'API nécessitant souvent des tableaux de bord, il est également possible d'utiliser des modèles Django avec Zato pour produire des interfaces utilisateur.

Les options de sécurité intégrées comprennent les API keys, Authentification Basique, JWT, NTLM, OAuth, RBAC, SSL/TLS, Vault, WS-Security et XPath. Il est toujours possible de sécuriser les services en utilisant d'autres moyens, non intégrés.

En termes de mise en œuvre, un service Zato individuel est une classe Python mettant en œuvre une méthode spécifique appelée self.handle. Le service reçoit des données, les traite en fonction de ses besoins, ce qui peut impliquer de communiquer avec d'autres systèmes, applications ou services et produit ensuite des résultats. Notez que les entrées et sorties sont toutes deux facultatives, par exemple, un service d'arrière-plan transférant des fichiers entre des applications n'en aura généralement pas, alors qu'un service CRUD typique aura les deux.

Comme un service n'est qu'une simple classe Python, il consomme très peu de ressources et il est possible de déployer des centaines ou des milliers de services sur un seul serveur Zato. Et comme Zato peut utiliser plusieurs CPU et plusieurs instances Linux, il évolue sans limites, tant horizontalement que verticalement.

Les services acceptent leurs entrées par le biais de canaux - un canal indique à Zato qu'il doit mettre un service particulier à la disposition du monde extérieur en utilisant tel ou tel protocole, format de données et définition de sécurité. Par exemple, un service peut être monté sur des canaux REST indépendants, parfois à l'aide de clés API et parfois à l'aide de Basic Auth. En outre, chaque type de canal possède ses propres éléments de configuration spécifiques, tels que la mise en cache, les délais d'attente ou d'autres options.

Les services peuvent également invoquer d'autres services Zato - il s'agit simplement d'un appel de méthode Python ordinaire, au sein du même processus Python. Cela signifie qu'il est très efficace de les invoquer - c'est simplement comme invoquer une autre méthode Python.

Les services sont déployés à chaud sur les serveurs Zato sans redémarrage du serveur et un service peut être mis à la disposition de ses consommateurs immédiatement après le déploiement.

Il existe des plugins pour Visual Studio Code et PyCharm qui déploient automatiquement votre service chaque fois que vous l'enregistrez dans votre IDE. D'autres éditeurs de code ou IDE peuvent également être utilisés.

Pendant le développement, le tableau de bord intégré de l'administrateur Web est généralement utilisé pour créer et gérer les canaux ou d'autres objets Zato. Dès qu'une solution est prête pour l'automatisation DevOps, la configuration d'une solution peut être déployée automatiquement depuis la ligne de commande ou directement depuis un clone git, ce qui facilite l'utilisation de Zato avec des outils tels que Terraform, Ansible ou Puppet.

Quel sera le but du tutoriel, exactement ?

Après avoir terminé le tutoriel, nous aurons :

• Un environnement d'intégration complet
• Un service API offert via REST et JSON.
• Le service invoquera deux points endpoints REST pour collecter des données.
• Le service enverra des notifications à un AMQP broker.

Flux de messages

Nous allons mettre en œuvre un processus d'intégration d'API typique des banques et autres institutions financières.

• Une application cliente souhaite obtenir des informations sur un client à partir de son identifiant.
• Les données du client sont stockées dans un CRM
• L'historique des paiements est stocké dans une autre application
• Pour certains types de clients, il est nécessaire qu'un système de détection des fraudes soit informé de toute opération concernant ces clients et nous envoyons des notifications au système en conséquence.

L'application client est un bloc de construction que nous ne développerons pas dans ce tutoriel - c'est là que Django, React, Vue, Flutter, ASP.NET et d'autres frameworks peuvent être utilisés dans des projets réels.

D'autre part, n'oubliez pas que d'autres systèmes backend peuvent également invoquer le service - c'est crucial, ce dernier peut être mis à la disposition de nombreuses applications, chacune avec son propre canal d'accès, même si dans le tutoriel nous supposerons qu'il n'y a qu'un seul client API.

Installation de Zato

La façon la plus simple pour commencer à utiliser Zato est de l'installer avec Docker ou Vagrant. Non seulement vous installerez Zato mais le programme d'installation configurera automatiquement un cluster de démarrage rapide pour vous. Vous pouvez utiliser cette méthode d'installation partout, sur Windows, Mac ou Linux.

• Docker
• Vagrant

Sinon, vous pouvez installer un paquet Zato pour la distribution Linux de votre choix et configurer vous-même un cluster de démarrage rapide - cela prendra environ 2 minutes supplémentaires.

• Ubuntu (assurez-vous que vous avez une version LTS).
• RHEL
• Suse
• Debian

Vous pouvez créer des services Zato avec n'importe quel éditeur de code et vous pouvez également installer un plugin pour votre IDE afin de déployer automatiquement vos services lors de l'enregistrement d'un fichier.

• Visual Studio Code
• PyCharm

Référez-vous aux chapitres ci-dessous, en fonction de la méthode d'installation et de l'IDE que vous avez choisis.

Si vous avez installé Zato sous Docker ou Vagrant

Après avoir installé Zato à l'aide de Docker ou de Vagrant, vous disposez d'un conteneur / VM avec un cluster de démarrage rapide et quelques ports TCP mappés à votre hôte ainsi qu'un port non mappé.

Avant d'utiliser l'environnement, nous aurons besoin de mots de passe pour nous y connecter.

Exécutez la commande ci-dessous pour les extraire du conteneur ou de la VM. Notez que si vous utilisez Docker, les mots de passe seront régénérés à chaque fois que vous démarrez un nouveau conteneur.

# Docker
$ docker exec zato /opt/zato/get-credentials

# Vagrant
$ cd ~/directory/with/zato/Vagrantfile
$ vagrant ssh -c 'cat  /opt/zato/get-credentials'

Le résultat sera le même dans les deux cas :

$

SSH: oaWMFmbt5Faq6
IDE: LWdasXlqVrO8Gur00Y3ncGjmHWNLZvr
Dashboard: YUm7ufehorVEw

$

Vous pouvez maintenant vous rendre sur le tableau de bord à l'adresse https://localhost:8183 et vous connecter avec l'utilisateur 'admin' et le mot de passe affiché à l'écran ci-dessus.

Nous pouvons également vérifier si le serveur est en cours d'exécution en lançant la commande curl ci-dessous - elle invoquera un service intégré pour confirmer que le serveur a démarré.

$ curl localhost:11223/zato/ping ; echo
{"pong":"zato","zato_env":{"result":"ZATO_OK","cid":"a5060e06b675cb20017a357d","details":""}
$

La section suivante détaille comment installer Zato à partir d'un paquetage Linux et comment créer manuellement un cluster de démarrage rapide. Vous pouvez maintenant faire défiler la page pour savoir comment configurer votre IDE ou éditeur.

Si vous avez installé Zato à partir d'un package Linux

Après avoir installé Zato à partir d'un .deb ou d'un .rpm, un nouvel utilisateur appelé 'zato' a été créé et tous les binaires de la plate-forme se trouvent dans /opt/zato.

Pour créer un environnement de démarrage rapide, vous devez d'abord installer Redis, par exemple.

$ sudo apt install redis-server

À partir de maintenant, avec le paquet Zato et Redis installés, toutes les commandes peuvent être exécutées en tant qu'utilisateur zato - les pouvoirs de root ne sont jamais nécessaires pour gérer les environnements Zato.

Créons un nouvel environnement dans le répertoire ~/env/qs-1.

$ sudo su - zato
$ mkdir -p ~/env/qs-1
$ zato quickstart create ~/env/qs1
[1/8] Certificate authority created
[2/8] ODB schema created
[3/8] ODB initial data created
[4/8] server1 created
[5/8] Load-balancer created
Superuser created successfully.
[6/8] Dashboard created
[7/8] Scheduler created
[8/8] Management scripts created
Quickstart cluster quickstart-904765 created
Dashboard user:[admin], password:[F7qCOiabas5ToQ7EWupLrHOn9iVHzyBv]
Visit https://zato.io/support for more information and support options
$

Observez la ligne surlignée aves les droits d'accès au tableau de bord. Si vous avez besoin de le modifier, exécutez cette commande: zato update password ~/env/qs-1/web-admin admin.

Démarrons tous les composants maintenant - notez le flag '--fg' lors du démarrage du serveur, cela le fera démarrer en avant-plan, grâce auquel nous pourrons l'arrêter avec Ctrl/Cmd-C.

$ zato start ~/env/qs-1/load-balancer
OK
$

$ zato start ~/env/qs-1/web-admin
OK
$

$ zato start ~/env/qs-1/scheduler
OK
$

$ zato start ~/env/qs-1/server1 --fg
INFO - Starting Zato 3.2+rev.da807efbc-py3.8.9
INFO - Listening at: http://0.0.0.0:17010 (19475)
[...]

Visitez http://localhost:8183, saisissez les informations d'identification imprimées ci-dessus et naviguez pour vous faire une idée de l'aspect du tableau de bord.

Dans une autre fenêtre de terminal, confirmez que l'environnement est prêt à accepter les demandes d'API.

$ curl localhost:11223/zato/ping ; echo
{"pong":"zato","zato_env":{"result":"ZATO_OK","cid":"2fd7536d956b17fcbed24122","details":""}
$

L'étape suivante consiste à configurer votre IDE ou éditeur de code.

Si vous avez Visual Studio Code ou PyCharm

Pour installer un plugin IDE, vous devez d'abord disposer d'informations d'identification pour l'utilisateur IDE avec lequel vous vous connectez à Zato.

• Nom d'utilisateur : ide_publisher
• Mot de passe : Auto-généré, lisez ci-dessous comment l'obtenir.

Si vous êtes sous Docker ou Vagrant, exécutez la commande ci-dessous pour obtenir le mot de passe de l'ide_publisher (il sera différent dans chaque installation) :

$ cat /opt/zato/get-credentials

SSH: oaWMFmbt5Faq6
IDE: LWdasXlqVrO8Gur00Y3ncGjmHWNLZvr
Dashboard: YUm7ufehorVEw

$

Si vous avez créé le conteneur quickstart vous-même, le mot de passe de l'ide_publisher a été généré automatiquement. Il n'est donc pas possible de le lire et vous pouvez le réinitialiser avec la commande ci-dessous. Cela fonctionnera également si vous vous connectez directement au conteneur / VM et l'exécutez depuis la ligne de commande.

$ zato set-ide-password ~/env/qs-1/server1
aSiieQXgo6M4OS1Qv83cpHjhGR0emXN8
$

Maintenant, vous pouvez consulter les instructions d'installation de l'IDE sélectionné.

• Visual Studio Code
• PyCharm

Introduction au déploiement à chaud

Le déploiement à chaud est un concept clé de Zato. Ce terme désigne le processus de transfert de votre service vers un cluster. Il est considéré comme "chaud" parce qu'ensuite, il ne nécessite pas de redémarrage du serveur, c'est-à-dire que vous déployez un service à chaud et il est immédiatement disponible sur tous les serveurs.

S'il y a plus d'un serveur dans le cluster, il suffit de déployer à chaud le service sur un seul d'entre eux et il se synchronisera avec les autres nœuds du cluster.

Il existe plusieurs façons de déployer à chaud des services. Les deux premières seront utilisées dans ce tutoriel, mais nous allons décrire chacune d'entre elles pour vous permettre de comprendre quelles sont les options et quand les utiliser.

• Depuis votre IDE

Couramment utilisé pendant le développement - une fois que vous avez installé un plugin pour l'IDE, chaque fois que vous appuyez sur Ctrl/Cmd-S pour enregistrer un service sur le disque, il sera automatiquement déployé sur votre cluster et rendu disponible pour une utilisation immédiate.

• Ligne de commande

Ceci est utilisé pour l'automatisation du déploiement ou si vous avez un IDE ou un éditeur sans plugin Zato.

Chaque serveur Zato surveille un répertoire spécifique, appelé répertoire de déploiement à chaud, et chaque fois que des fichiers Python contenant vos services y sont enregistrés, ce serveur les récupère et les déploie à chaud dans le cluster.

Dans le cluster quickstart de ce tutoriel, le répertoire est ~/env/qs-1/server1/pickup/incoming/services.

Pendant le développement, vous pouvez enregistrer vos fichiers avec les services Zato directement dans ce répertoire et ensuite, lorsque vous appuyez sur Ctrl/Cmd-S, le fichier sera déployé sur le cluster. Vous pouvez également cloner votre dépôt git directement dans ce répertoire.

Une autre façon de l'utiliser pendant le développement est de le faire pointer vers un clone git résidant dans un autre répertoire et encore, chaque fois que vous enregistrez un fichier, son contenu est envoyé à tous les serveurs.

Cette méthode est également utilisée pour l'automatisation - il suffit d'utiliser cp pour copier les fichiers dans le répertoire et tous les services de ces fichiers seront déployés.

• Tableau de bord

Lorsque vous vous connectez au Tableau de Bord et que vous naviguez vers les services, vous remarquerez un bouton intitulé "Upload services". Cela vous permettra de déployer des fichiers locaux sur un serveur distant. Ceci est utile lorsqu'il n'y a pas de connexion directe au serveur, par exemple, il est impossible d'y accéder par ssh.

• Fichier de configuration local

Cette méthode est généralement utilisée pour les déploiements automatisés uniquement - elle vous permet de diriger un serveur de départ vers les fichiers du système de fichiers qu'il doit déployer.

La différence entre ce répertoire et un répertoire de déploiement à chaud est que ce dernier nécessite que le serveur soit déjà en fonctionnement alors que celui-ci indique au serveur ce qu'il doit faire pendant qu'il est encore en train de démarrer.

Cette option est le plus souvent employée lorsque l'on construit ses propres images Docker ou que l'on utilise Terraform, Packer et des outils similaires.

• Transfert de fichiers à distance

Cette méthode d'automatisation utilise le `file transfer </en/blog/file-transfer.html)_ pour laisser les serveurs écouter les changements dans les répertoires des serveurs distants.

Par exemple, vous pouvez avoir un clone git central d'un dépôt pour plusieurs environnements et les serveurs Zato s'y connecteront via SFTP, téléchargeront les nouveautés ou les modifications et les déploieront localement.

En termes de résultat final, il n'y a pas de différence entre les méthodes, elles aboutissent exactement au même résultat.

Il s'agit en fait d'un bon exemple de la manière dont Zato est conçu autour de services réutilisables. Toutes ces méthodes de déploiement, tous ces canaux, mènent en fin de compte aux mêmes services qui déploient votre code, seule la manière d'y accéder diffère.

Déploiement à chaud de votre premier service

Nous pouvons maintenant créer le premier service et le déployer à chaud. Créez un nouveau fichier appelé api.py avec le contenu ci-dessous. Il s'agit d'une base du service que nous compléterons plus tard avec des détails.

# -*- coding: utf-8 -*-
# zato: ide-deploy=True

from zato.server.service import Service

class GetUserDetails(Service):
    """ Returns details of a user by the person's ID.
    """
    name = 'api.user.get-details'

    def handle(self):

        # For now, return static data only
        self.response.payload = {
            'user_name': 'John Doe',
            'user_type': 'SRT'
        }

Si vous avez configuré un plugin pour PyCharm ou Visual Studio Code, notez la ligne surlignée - il s'agit d'un marqueur spécial qui permet au plugin de savoir que l'enregistrement de ce fichier devrait entraîner le déploiement de l'IDE sur votre cluster.

Sans plugin, vous devez enregistrer le fichier dans le répertoire ~/env/qs-1/server1/pickup/incoming/services du serveur. Si vous utilisez Docker et Vagrant mais que vous ne disposez pas du plugin, vous devez d'abord mapper ce répertoire avec celui du système hôte et enregistrer le fichier dans ce dernier.

Et si vous voulez le déployer sur un serveur Zato à partir de votre navigateur, connectez-vous à Dashboard, allez dans Services et cliquez sur Upload package.

L'adresse du Dashboard est http://localhost:8183, le nom d'utilisateur est admin et si vous devez réinitialiser le mot de passe, voici la commande :

$ zato update password ~/env/qs-1/web-admin admin

Après avoir déployé le code, nous pouvons confirmer dans le Dashboard que le service est là.

Une fois que vous vous êtes connecté au tableau de bord, naviguez vers Services -> Entrez "get-details" dans la boîte de recherche -> Show services -> Click View et cela affichera des informations de base sur le service déployé. Vous pouvez cliquer sur Source code pour confirmer qu'il s'agit du même service.

Nous avons un service et nous pouvons maintenant créer un canal REST pour celui-ci.

Créer votre première canal

Nous voulons invoquer notre service API en utilisant REST mais nous voulons également nous assurer que l'accès à ce service est sécurisé. Nous allons donc d'abord créer une définition de sécurité pour notre client API.

Dans Dashboard, allez à Security -> Basic Auth -> Cliquez sur "Create a new definition" et entrez :

• Name: API Credentials
• Username: api
• Domain: API

En cliquant sur OK, la définition sera créée avec le mot de passe de l'utilisateur automatiquement fixé à un uuid4 aléatoire. Nous devons donc le réinitialiser en cliquant sur "Change password" et en fournissant un nouveau mot de passe - c'est à vous de décider de ce qu'il doit être.

Maintenant, nous pouvons créer un canal REST en allant dans Connections -> Channels -> REST, comme ci-dessous :

Cliquez sur le lien Create a new REST channel :

Remplissez le formulaire comme ici, les champs dont les valeurs sont à fournir sont :

• Name
• URL path
• Data format
• Service
• Security definition

En cliquant sur OK, le canal sera créé et nous serons maintenant en mesure d'invoquer le service API.

Invoquer votre premier service

Nous allons utiliser curl pour invoquer le service - nous y accéderons via le port 11223 du load-balancer, comme ci-dessous. Notez que vous devez également entrer le mot de passe du client API.

$ curl http://api:<password-here>@localhost:11223/api/v1/user ; echo
{"user_name":"John Doe","user_type":"SRT"}
$

Tout fonctionne comme prévu : vous venez de créer et d'invoquer votre premier service API ! Maintenant, essayez de voir ce qui se passe si vous fournissez un mot de passe invalide ou un chemin d'accès URL - vos demandes ne seront pas autorisées.

Ceci conclut la première partie du tutoriel et la prochaine verra le service s'intégrer avec des systèmes externes pour transformer et enrichir leurs réponses avant de produire la réponse finale au client API.

Mais d'abord, il y a une observation à faire - le cluster quickstart que vous avez créé est un environnement réel, entièrement fonctionnel. Si vous deviez le créer à partir de zéro, en ajoutant chaque composant individuellement, Dashboard, server, load-balancer et scheduler, le résultat serait exactement le même.

En d'autres termes, les clusters quickstart sont une méthode pratique pour créer de nouveaux environnements et ils peuvent être très bien utilisés non seulement pour le développement mais aussi pour les tests et la production.

Maintenant, nous sommes prêts à passer à la deuxième partie du tutoriel.