Comment utiliser l'adaptateur FTP pour produire et consommer des messages FTP
FTP ( Protocole de transfert de fichiers) est un protocole de réseau permettant de transmettre des fichiers sur des connexions TCP/IP dans un réseau (y compris l'Internet) configuré pour transférer des fichiers via ce protocole. Dans une transaction FTP, un expéditeur de fichiers est appelé hôte local. Un récepteur de fichiers impliqué dans le FTP est un hôte distant, et il s'agit généralement d'un serveur. Bien que de nombreux transferts de fichiers puissent être effectués à l'aide du protocole HTTP (Hypertext Transfer Protocol), le FTP est encore couramment utilisé pour transférer des fichiers en coulisse pour d'autres applications, comme les services bancaires. Par conséquent, nous pouvons dire que FTP est une excellente option pour promouvoir l'interopérabilité basée sur les fichiers entre des systèmes situés dans le même réseau local ou dans l'Internet (un serveur FTP est accessible via l'Internet). Cette interopérabilité peut être enrichie, traitée et orchestrée par le système d'interopérabilité IRIS Interoperability. Pour comprendre comment IRIS peut aider, il est crucial de comprendre la fonctionnalité de l'Architecture d'Interopérabilité IRIS pour FTP, centrée sur les adaptateurs FTP d'entrée et de sortie.
Adaptateur FTP d'entrée
Selon la documentation InterSystems, l'EnsLib.FTP.InboundAdapter permet à InterSystems IRIS de recevoir des fichiers via le protocole FTP. L'adaptateur reçoit une entrée FTP à partir de l'emplacement configuré, la lit et l'envoie sous forme de flux au service métier associé. Le service métier créé et configuré par vos soins utilise ce flux et communique avec le reste de la production. La figure suivante montre le flux global des messages entrants (à l'exclusion des réponses) :
En détail :
- Chaque fois que l'adaptateur rencontre une entrée provenant de sa source de données configurée, il appelle la méthode interne ProcessInput() de la classe de service métier, en passant le flux comme argument d'entrée.
- Celle-ci est exécutée par la méthode interne ProcessInput() de la classe de service métier. Cette méthode effectue des tâches de production de base liées à la gestion des informations internes d'une manière requise par tous les services métier. Il n'est pas nécessaire de personnaliser ou de remplacer la méthode héritée par votre classe de service métier.
- La méthode ProcessInput() appelle ensuite votre méthode OnProcessInput() personnalisée, en transmettant l'objet Stream en tant qu'entrée. Maintenant, avec le Stream, il est possible de développer les règles requises par le métier pour les fichiers reçus.
- Le message de réponse suit le même chemin mais en sens inverse.
Adaptateur FTP de sortie
Selon la documentation d'InterSystems (https://docs.intersystems.com/iris20221/csp/docbook/DocBook.UI.Page.cls?...), l'adaptateur FTP de sortie EnsLib.FTP.OutboundAdapter permet à la production d'envoyer des fichiers via le protocole FTP. Pour utiliser cet adaptateur, vous devez créer et configurer une opération métier spécialement conçue pour ce dernier. Cette opération métier recevra alors un message de la production, recherchera le type de message et exécutera la méthode appropriée. Cette méthode exécute généralement des règles pour générer des fichiers avec le contenu et le format requis par le métier à envoyer à une application.
Scénarios d'utilisation FTP les plus courants pour l'interopérabilité IRIS
Le tableau suivant résume les principaux scénarios d'utilisation de FTP pour l'interopérabilité d'IRIS :
Type d'adaptateur FTP | Scénario |
D'entrée | Réception de lots de données métier dans des fichiers CSV, XML, TXT et JSON. |
De sortie | Envoi des résultats du traitement des données métier par lots en CSV, XML, TXT et JSON à partir des données envoyées précédemment |
D'entrée | Processus ETL (extraction, transformation et chargement) de gros fichiers comme parquet, ORC et avro pour les lacs de données Data Lakes et les dépôts de données Data Marts. |
De sortie | Génération de fichiers parquet, ORC et avro à partir des bases de données IRIS pour les envoyer vers les lacs de données Data Lakes et les dépôts de données Data Marts externes. |
D'entrée | Consommation asynchrone de messages et de fichiers provenant de systèmes externes |
De sortie | Production de messages et de fichiers asynchrones vers des systèmes externes |
De sortie | Envoi/publication des fichiers générés (rapports PDF, fichiers numérisés, images, etc.) vers les dossiers distants de certains organismes. |
Application modèle
Le modèle IRIS-FTP (https://openexchange.intersystems.com/package/iris-ftp-sample) est un exemple d'utilisation de l'adaptateur FTP ( d'entrée et de sortie).
Production
Ce modèle a une production d'interopérabilité vers :
Recevoir des données CSV à l'aide d'un adaptateur FTP d'entrée dans un service mètier LoadCSVFTPBusinessService ; envoyer son contenu à une opération mètier LoadCSVFTPBusinessOperation ; persister le contenu dans une classe persistante à l'aide de CSVgen.
Effectuer un changement de données CDC (Change Data Capture) dans le tableau Paiement en utilisant un adaptateur SQL d'entrée dans une opération métier PaymentSQLBusinessService et envoyer les données du tableau (dans un fichier JSON) à une opération métier SendSQLDataToFTPBusinessOperation pour mettre le fichier JSON dans un serveur FTP.
Vous pouvez voir cette production ici :
Installation du modèle
Pour installer le modèle en utilisant ZPM, suivez les étapes suivantes :
- Ouvrez l'espace de nommage IRIS Namespace avec l'interopérabilité activée.
- Ouvrez le terminal et lancez un appel : USER>zpm "install iris-ftp-sample"
Pour installer le modèle en utilisant Docker, il faut procéder comme suit :
- Clone/git tire le repo dans n'importe quel répertoire local :
$ clone git https://github.com/yurimarx/iris-ftp-sample.git
- Ouvrez le terminal dans ce répertoire et exécuter :
$ compilation de docker-compose
- Lancez le conteneur IRIS avec votre projet :
$ docker-compose up -d
Lancement du modèle
Pour exécuter le modèle, suivez les procédures suivantes :
- Créez les informations d'identification pour accéder au serveur FTP (Allez vers Interopérabilité > Configurer > Informations d'identification) :
- ID : FTPCredentials
- Nom de l'utilisateur : irisuser
- Mot de passe : sys
Voici le résultat :
- Ouvrez la production et lancez-la, comme indiqué dans l'image ci-dessous :
Envoi d'un fichier à l'aide du client FTP et visualisation des données chargées dans un tableau SQL
- Ouvrez un client FTP (j'utilise généralement Filezilla pour le faire) et mettez le fichier input/countries.csv dans le dossier FTP racine :
- Hôte : localhost
- Nom de l'utilisateur : irisuser
- Mot de passe : sys
Ouvrez un client FTP (j'utilise généralement Filezilla pour le faire) et mettez le fichier input/countries.csv dans le dossier FTP racine :
- Accédez à System Explorer > SQL et tapez la sélection du pays, de la latitude, de la longitude et du nom SELECT country, latitude, longitude, name FROM dc_irisftpsample.Country. Consultez l'image ci-dessous pour voir à quoi devraient ressembler les données CSV chargées dans le tableau SQL :
Insertion de données dans un tableau et un fichier avec le contenu inséré dans un fichier sur le serveur FTP
- Accédez à System Explorer > SQL et tapez les valeurs de paiement (montant payeur, destinataire, date de transaction): insert into dc_irisftpsample.Payment(amount payer, receiver, transactiondate) values(100.0,'Yuri','Fabiana', CURRENT_TIMESTAMP). Vous pouvez voir ici la représentation à l'écran du fichier JSON contenant les données insérées dans le serveur FTP :
En coulisses : le code source
Fichiers et dossiers principaux
Dans le dossier iris-ftp-sample nous trouvons les éléments suivants :
Fichier | Description |
Readme.md | Informations sur le modèle et instructions d'installation/utilisation |
Module.xml | Manifeste d'installation de ZPM |
Dockerfile | Commandes Docker pour créer un conteneur IRIS d'InterSystems |
Docker-compose.yml | Commandes pour créer une composition de 2 instances docker : 1 instance docker de serveur FTP et 1 instance docker d'InterSystems IRIS dans le même réseau Docker |
Input/countries.csv | Fichier modèle à utiliser pour tester le chargement des données par FTP et csvgen avec une production FTP modèle. |
src/dc/irisftpsample | Le dossier du code source dans le paquet dc.irisftpsample |
FTPSampleProduction.cls | Le code source de la Production FTP (conteneur permettant d'exécuter des services et des opérations métier à l'aide d'adaptateurs FTP d'entrée et de sortie). |
LoadCSVFTPBusinessService.cls | Classe ObjectScript qui utilise un adaptateur FTP d'entrée pour recevoir des fichiers CSV et envoyer leur contenu à l'opération LoadCSVFTPBusinessOperation.cls. |
LoadCSVFTPBusinessOperation.cls | Reçoit le contenu d'un fichier CSV et charge ses données dans un tableau SQL en utilisant CSVgen |
SendSQLDataToFTPBusinessOperation.cls | Reçoit un fichier JSON avec le contenu du tableau "Paiement" de PaymentSQLBusinessService et envoie ce fichier JSON au serveur FTP. |
Payment.cls | Classe persistante ( tableau SQL "Paiement") pour les données de paiement persistantes à envoyer au serveur FTP. |
Cas d'utilisation modèle 1 : Recevoir un fichier CSV du serveur FTP et charger les données CSV dans un tableau SQL.
Pour ce cas d'utilisation, nous avons la séquence suivante :
- L'adaptateur FTP d'entrée lit le fichier CSV et le supprime du serveur FTP en utilisant ces paramètres :
-
Envoyez le flux d'un fichier CSV à la méthode OnProcessInput du service LoadCSVFTPBusinessService.
-
Envoyez le flux d'un fichier CSV dans un message Ens.StreamContainer dans l'opération LoadCSVFTPBusinessOperation.
Class dc.irisftpsample.LoadCSVFTPBusinessService Extends Ens.BusinessService
{
Parameter ADAPTER = "EnsLib.FTP.InboundAdapter";
Method OnProcessInput(pInput As %Stream.Object, pOutput As %RegisteredObject) As %Status
{
Set tSC = $$$OK,
tSource = pInput.Attributes("Filename"),
tFileLocation = pInput.Attributes("FTPDir"),
pInput=##class(Ens.StreamContainer).%New(pInput)
Set tSC = ..SendRequestSync("LoadCSVFTPBusinessOperation", pInput, .pOutput, -1)
Quit tSC
}
}
- Envoyez le flux d'un fichier CSV dans un message Ens.StreamContainer à la méthode LoadCSVIntoTable. L'adaptateur utilise le mappage XData pour déterminer la méthode à appeler pour chaque type de message dans la classe dc.irisftpsample.LoadCSVFTPBusinessOperation :
XData MessageMap
{
LoadCSVIntoTable
}
- Envoyez le flux comme un fichier CSV temporaire et appelez la méthode Generate pour placer le fichier CSV dans le tableau SQL dc.irisftpsample.Country.
Class dc.irisftpsample.LoadCSVFTPBusinessOperation Extends Ens.BusinessOperation
{
Parameter ADAPTER = "Ens.OutboundAdapter";
Parameter INVOCATION = "Queue";
Property Header As %Boolean [ InitialExpression = 1 ];
Property Delimiter As %String [ InitialExpression = "," ];
Property Classname As %String(MAXLEN = "");
Property Prowtype As %String(MAXLEN = "");
Property GuessTypes As %Boolean [ InitialExpression = 1 ];
Property Append As %Boolean [ InitialExpression = 1 ];
Property UseLoadData As %Boolean [ InitialExpression = 1 ];
Parameter SETTINGS = "Header:Basic,Delimiter:Basic,Classname:Basic,Prowtype:Basic,GuessTypes:Basic,Append:Basic,UseLoadData:Basic";
Method LoadCSVIntoTable(pInput As Ens.StreamContainer, Output pOutput As Ens.StringResponse) As %Status
{
Set tSC = $$$OK
Set pOutput = ##class(Ens.StringResponse).%New()
Try {
Set tSC = ##class(community.csvgen).StreamToFile(pInput.Stream, .pFile)
Set tSC = ##class(community.csvgen).Generate(pFile, ..Delimiter, ..Classname, ..Prowtype, ..GuessTypes, ..Append, ..UseLoadData, ..Header)
Set pOutput.StringValue = "OK"
} Catch err {
Set pOutput.StringValue = $System.Status.GetOneErrorText(tSC, 1)
}
Quit tSC
}
XData MessageMap
{
LoadCSVIntoTable
}
}
- Remarque 1 : Le paramètre Adapter est utilisé pour choisir l'adaptateur à utiliser par la Business Operation.
- Remarque 2 : les paramètres tels que Header, Delimiter, Classname, Prowtype, GuessTypes, Append et UseLoadData sont requis par csvgen et configurés par l'utilisateur de Production car ces paramètres sont référencés dans le paramètre SETTINGS de la section Basic :
Consultez les détails sur les informations requises par CSVgen ici : https://github.com/evshvarov/csvgen.
Cas d'utilisation modèle 2 : Application de la méthode CDC (Change Data Capture) sur le tableau des paiements en utilisant l'adaptateur SQL d'entrée et en envoyant les données du tableau à une opération métier pour les mettre sur le serveur FTP.
Pour ce cas d'utilisation, nous avons la séquence suivante :
- IRIS effectue une opération CDC dans le tableau "Paiement" et génère un fichier JSON avec le contenu du tableau, en supprimant les données lues. L'adaptateur utilise ces paramètres pour déterminer le tableau et les données à lire :
-
Envoyez le flux de données au format JSON au PaymentSQLBusinessService.
-
Envoyer le flux du fichier JSON dans un message Ens.StreamContainer dans l'opération métier SendSQLDataToFTPBusinessOperation.
-
Envoyez le flux du fichier JSON à l'adaptateur FTP de sortie :
Class dc.irisftpsample.SendSQLDataToFTPBusinessOperation Extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.FTP.OutboundAdapter";
Property Filename As %String(MAXLEN = 1000);
Parameter SETTINGS As %String = "Filename";
Method OnMessage(pRequest As Ens.StreamContainer, Output pResponse As %Persistent) As %Status
{
Set tFilename=
..Adapter.CreateTimestamp(##class(%File).GetFilename("/tmp/sqltojson"),..Filename)
Quit ..Adapter.PutStream(tFilename, pRequest.Stream)
}
}
- Remarque 1 : Le paramètre ADAPTER définit que l'opération métier utilisera l'adaptateur FTP de sortie.
- Remarque 2: Le paramètre Filename définit le nom du fichier qui se trouve sur le serveur FTP.
- Placez le fichier JSON dans le dossier FTP racine avec le nom SQLTOJSON_YYYY-MM-DD_HH.mm.ss.zzz.json en utilisant les paramètres suivants :
Pour en savoir plus