Créer la requête de service WEB externe
Quels sont les différents éléments d’une requête http ?
L’exécution d’une requête http dans Diapason peut être symbolisée avec le schéma suivant :
Les différents éléments pris en compte pour l’exécution d’une requête http peuvent être rangés en deux catégories.
Ceux qui interviennent pour la définition de la demande appelée « Requête » :
URL (détermine en réalité l’URI qui permet d’identifier la ressource sur un réseau)
Query Parameters (détermine la suite de paramètres passés à la suite de l’URL)
Les Headers (déterminent une liste de Headers sous la forme CLE / VALEUR)
Le verbe (détermine le verbe de la demande GET POST PUT PATCH DELETE)
Le Body (détermine le contenu principal de la demande. Il peut être au format JSON, XML, TEXTE).
L’exécution de la requête donnera lieu à une « réponse » qui permettra de récupérer les éléments suivants :
Le Code retour (Permet de recevoir le code de retour en cas d’erreur du serveur distant)
Les Headers (Possibilité de récupérer la valeur d’un Header de retour à partir de sa CLE)
Le Body (Permet de récupérer et de traiter le contenu du body de la réponse à la requête)
Comment rédiger la requête ?
Définition de la demande qui interroge le WEB SERVICE
Au début de la requête, on va utiliser la fonction DIALOG SW-REQUETE-HTTP, qui va gérer l’ensemble des fonctionnalités spécifiques à l’exécution d’une requête HTTP!
Comme pour la plupart de fonctions DIALOG 🙂 il conviendra de tester pour chaque utilisation la valeur de retour pour s’assurer qu’il n’y a pas eu d’erreur. Vous pouvez alors répercuter cette erreur dans Diapason sous la forme souhaitée (un LC-ERREUR par exemple).
Dans la requête, on va pouvoir utiliser cette fonction plusieurs fois, de manière successive, pour y entrer toutes les caractéristiques nécessaires, qui seront mémorisées au fur- à- mesure.
On purge de fonction Comme la fonction SW-REQUETE-HTTP mémorise les informations qu’on lui donne au fur à mesure, si on veut exécuter plusieurs requêtes HTTP dans la même requête DIALOG, on commence par utiliser l’action REINIT pour purger les caractéristiques précédemment utilisées dans une même requête DIALOG : | VLO.RetourFonction = SW-REQUETE-HTTP( ACTION= REINIT ) SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO."Erreur de réinitialisation :" + " " + VLO.RetourFonction FIN_BLOC |
On rentre les Query Parameters Les « Query Parameters » ou « Query string » sont des paramètres passés dans la chaine de caractère de l’URL. Ils sont placés à la fin de l’URL sous la forme suivante :  Dans DIAPASON, les Query Parameters peuvent techniquement être donnés avec l’url au moment de l’exécution de la requête http. Il est toutefois fortement conseillé d’utiliser l’action « PUT-PARAM » de la fonction SW-REQUETE-http pour passer ces paramètres car elle va gérer la transformation éventuelle des caractères interdits. Elle devra être utilisée plusieurs fois si vous voulez définir plusieurs paramètres. | COMMENTAIRE : "Exemple d'ajout de paramètre à une requête HTTP" VLO.RetourFonction = SW-REQUETE-HTTP( ACTION= PUT-PARAM , CLE-PARAM= CLO."access_key" , VAL-PARAM= CLO."Ma_Cle_Perso" ) SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO."Erreur sur le paramètre" + " " + CLO."access_key" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC |
On remplit l’URL et le verbe, et on exécute la demande: Après avoir défini les paramètres d’envoi de la requête http comme spécifié dans l’API que vous souhaitez utiliser, vous pouvez exécuter votre demande avec l’action EXE-REQUETE de la fonction SW-REQUETE-http, en remplissant :
Le verbe va permettre de spécifier la méthode d’accès à la ressource. Diapason permet d’utiliser les méthodes les plus courantes : GET PUT POST PATCH DELETE. Vous devez donc valoriser le paramètre « METHODE » comme il vous sera spécifié dans la documentation de l’API que vous voulez utiliser.
Le paramètre « URL » va permettre de spécifier comment accéder à la ressource. Là encore, vous trouverez cette information dans la documentation de l’API que vous voulez utiliser. Ces informations sont obligatoires ! | COMMENTAIRE : "........On part du principe que vous avez défini les paramètres d'envoi de la requête http comme spécifié dans l'API que vous souhaitez utiliser." COMMENTAIRE : " Exemple d'utilisation de l'action EXE-REQUETE avec la méthode GET" VLO.URL = CLO."https://geo.api.gouv.fr/departements/64/communes" VLO.RetourFonction = SW-REQUETE-HTTP(ACTION= EXE-REQUETE , METHODE= GET , URL= VLO.URL) SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO." Erreur d'exécution de la requête :" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC |
On remplit les Headers (si nécessaire ) Les headers forment un ensemble de paramètres sous la forme Clé / Valeur. L’action « PUT-HEADER » devra être utilisée plusieurs fois si vous voulez définir plusieurs headers. | COMMENTAIRE : "Exemple d'ajout du header 'Content-Type' avec la valeur 'application/json'" VLO.RetourFonction = SW-REQUETE-HTTP( ACTION= PUT-HEADER , CLE-HEADER= CLO."Content-Type" , VAL-HEADER= CLO."application/json" ) SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO."Erreur d'ajout du Header" + " " + CLO."Content-Type" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC Les headers spécifiques d’authentification seront gérés avec une action dédiée comme indiqué dans le paragraphe ci-dessous. |
On remplit les paramètres d’authentification (si nécessaire ) L’authentification des requêtes http passe généralement par des headers avec un format spécifique. Il est donc conseillé d’utiliser l’une des deux actions spécifiques d’authentification :
| Exemple d’utilisation de l’action PUT-BASICAUTH : COMMENTAIRE : "Exemple d'authentification du type BasicAuth pour une requête HTTP" VLO.RetourFonction = SW-REQUETE-HTTP( ACTION= PUT-BASICAUTH , LOGIN= CLO."MonLogin" , PASSWORD= CLO."Mot2Passe" ) SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO."Erreur d'authentification" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC Exemple d’utilisation de l’action PUT-BEARERAUTH : COMMENTAIRE : "Exemple d'authentification du type Bearer pour une requête HTTP" VLO.RetourFonction = SW-REQUETE-HTTP( ACTION= PUT-BEARERAUTH , PASSWORD= CLO."486a7bb7212252de1a938c230a10f977" ) SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO."Erreur d'authentification" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC |
On récupère le Body du JSON envoyé Le body va contenir l’information principale du message envoyé. Le volume de cette information est très souvent trop important pour être stocké dans une variable. Le format JSON est certainement le plus utilisé mais le format XML est aussi utilisé dans certains cas. Afin de faciliter au maximum le paramétrage, Diapason permet d’alimenter le body directement à partir des structures de description XML, Texte ou la nouvelle liste de description JSON. Afin de couvrir un maximum de cas, il sera aussi possible d’alimenter le body à partir d’un fichier libre. | Voici les quatre formats possibles : Format JSON Voici un exemple d’alimentation du body à partir de la liste WFSWListeJSON. La manipulation des données au format JSON sera présentée dans un paragraphe spécifique de ce document. COMMENTAIRE : "Exemple d'alimentation du body avec un format JSON" COMMENTAIRE : "Alimentation de la liste WFSWListeJSON à partir d'un fichier 'Modèle'." VLO.RetourFonction = SW-OUTILS-JSON( ACTION= IMPORTER-FICHIER , PATH-FIC= CLO."/tmp/FichierModele.json" , OPTION= CLO."" ) COMMENTAIRE : "On remplace certaines valeurs par les valeurs souhaitées." POUR CHAQUE LST WFSWListeJSON AVEC WFSWListeJSON.ValeurCarElement = CLO."$A_REMPLACER$" : PRENDRE WFSWListeJSON ValeurCarElement = CLO."ISSWDG_SOR" FIN_BLOC COMMENTAIRE : "Alimentation du body à partir de la liste WFSWListeJSON." VLO.RetourFonction = SW-REQUETE-HTTP( ACTION= PUT-BODY , FORMAT= JSON ) SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO."Erreur d'alimentation du Body :" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC Format XML Voici un exemple d’alimentation du body à partir de la liste WFEIAXmlMes. L’utilisation des outils de manipulation des données au format XML existants (correspondance, lecture de fichier…) permet d’alimenter la liste WFEIAXmlMes. Par la suite, il suffit d’utiliser l’action PUT-BODY avec le FORMAT XML pour alimenter le body avec le contenu XML de cette description. COMMENTAIRE : "........On part du principe que la liste WFEIAXmlMes est alimentée avec une structure XML valide" COMMENTAIRE : "Alimentation du body à partir de la liste WFEIAXmlMes." VLO.RetourFonction = SW-REQUETE-HTTP(ACTION= PUT-BODY , FORMAT= XML , CLE= CLO."CLEXML") SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO."Erreur d'alimentation du Body :" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC Format TEXTE Voici un exemple d’alimentation du body à partir de la liste WFFicContenu. L’utilisation des outils de manipulation des données au format TEXTE existants (lecture de fichier…) permet d’alimenter la liste WFFicContenu. Par la suite, il suffit d’utiliser l’action PUT-BODY avec le FORMAT TEXTE pour alimenter le body avec le contenu texte de cette description. COMMENTAIRE : "........On part du principe que la liste WFFicContenu est alimentée" COMMENTAIRE : "Alimentation du body à partir de la liste WFFicContenu." VLO.RetourFonction = SW-REQUETE-HTTP(ACTION= PUT-BODY , FORMAT= TEXTE, CLE= CLO."CLETEXTE") SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO."Erreur d'alimentation du Body :" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC Format FICHIER Voici un exemple d’alimentation du body avec un format totalement libre. Il vous suffit de générer le format souhaité dans un fichier et d’utiliser l’action PUT-BODY avec le format FICHIER comme ci-dessous : COMMENTAIRE : "Alimentation du body à partir d'un fichier (au format libre)." VLO.RetourFonction = SW-REQUETE-HTTP(ACTION= PUT-BODY , FORMAT= FICHIER, PATH= CLO."/tmp/FichierAImporter") SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO."Erreur d'alimentation du Body :" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC |
Quelles sont les valeurs de retour de la requête ?
Généralités sur le code de retour
Toute exécution de requête http va donner lieu à un code de retour. C’est une valeur numérique de type entier qui va suivre certaines normes.
La plage des entiers entre 200 et 299 va être utilisée dans le cas ou la requête s’est bien passée. Ainsi dans la très grande majorité des cas, c’est le code 200 qui sera retourné en cas de succès.
Les autres valeurs vont être utilisées pour les différents cas d’erreur. Les cas d’erreurs sont généralement décrits dans la documentation de l’API que vous souhaitez utiliser.
La valeur de retour du EXE-REQUETE
Valeur OK
Pour uniformiser les valeurs de retour des fonction DIALOG, l’action EXE-REQUETE retournera une chaine vide pour les cas de succès (code 200).
Valeur KO
Dans un cas d’erreur, le code retour sera retourné dans la chaine de caractères. Ce code pourra être suivi d’une description d’erreur dans le cas d’une erreur interne à Diapason.
Les cas d’erreurs sont généralement décrits dans la documentation de l’API que vous souhaitez utiliser. Dans certains cas d’API, vous trouverez des informations complémentaires dans le body de retour. Si c’est le cas, vous devrez utiliser l’action GET-BODY pour récupérer ces informations détaillées. (Voir paragraphe ci-dessous)
Récupération des paramètres de retour de la requête http
Le code de retour étant passé dans la chaine de retour de l’action EXE-REQUETE, il reste deux paramètres pouvant contenir des informations : les headers et le body. (Voir schéma général de début de chapitre)
Les Headers de retour Dans certains cas, la requête http va vous retourner des informations sous la forme de Header. Par exemple, il est fréquent que l’API retourne un Header « Content-Type » qui va vous indiquer le type ou le format de la réponse stockée dans le body de retour. L’action GET-HEADER vous permet de récupérer la valeur d’un Header donné dans une variable de type caractère. Voici un exemple d’utilisation de l’action GET-HEADER : | COMMENTAIRE : "........On part du principe que vous avez utilisé l'action EXE-REQUETE au préalable." COMMENTAIRE : "Exemple de récupération du Header Content-Type dans la variable ValHeader en retour de l'exécution de la requête HTTP." VLO.RetourFonction = SW-REQUETE-HTTP(ACTION= GET-HEADER , CLE-HEADER= CLO."Content-Type" , S:VALEUR= VLO.ValHeader) SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO. "Problème avec le Header Content-Type :" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC |
Le body de retour Le body va contenir l’information principale du retour de l’exécution de la requête HTTP. Le volume de cette information est très souvent trop important pour être stocké dans une variable. Le format JSON est certainement le plus utilisé mais le format XML est aussi utilisé dans certains cas. Afin de faciliter au maximum le paramétrage, Diapason permet d’alimenter les structures de description XML, Texte ou la nouvelle liste de description JSON à partir du body de retour. Pour couvrir un maximum de cas, il sera aussi possible d’enregistrer son contenu dans un fichier. | Voici donc les quatre formats possibles :
Voici un exemple d’alimentation de la liste WFSWListeJSON à partir du body de retour. La manipulation des données au format JSON sera présentée dans un paragraphe spécifique de ce document. COMMENTAIRE : "........On part du principe que vous avez utilisé l'action EXE-REQUETE au préalable." COMMENTAIRE : "Exemple de récupération du Body au format JSON après l'exécution de la requête HTTP." VLO.RetourFonction = SW-REQUETE-HTTP( ACTION= GET-BODY , FORMAT= JSON ) SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO."Problème de récupération du body" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC SINON POUR CHAQUE LST WFSWListeJSON : COMMENTAIRE : "Possibilité de récupérer les informations du body ici." FIN_BLOC FIN_BLOC
Voici un exemple d’alimentation de la liste WFEIAXmlMes à partir du body de retour. Les outils existants de manipulation des données au format XML (correspondance, écriture de fichier…) sont utilisables par la suite. COMMENTAIRE : "........On part du principe que vous avez utilisé l'action EXE-REQUETE au préalable." COMMENTAIRE : "Exemple de récupération du Body au format XML après l'exécution de la requête HTTP." VLO.RetourFonction = SW-REQUETE-HTTP( ACTION= GET-BODY , FORMAT= XML , CLE= CLO."CLEXML") SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO."Problème de récupération du body" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC SINON POUR CHAQUE LST WFEIAXmlMes : COMMENTAIRE : "Possibilité de récupérer les informations du body ici." FIN_BLOC FIN_BLOC
Voici un exemple d’alimentation de la liste WFFicContenu à partir du body de retour. Les outils existants de manipulation des données au format TEXTE (écriture de fichier…) sont utilisables par la suite. COMMENTAIRE : "........On part du principe que vous avez utilisé l'action EXE-REQUETE au préalable." COMMENTAIRE : "Exemple de récupération du Body au format TEXTE après l'exécution de la requête HTTP." VLO.RetourFonction = SW-REQUETE-HTTP( ACTION= GET-BODY , FORMAT= TEXTE , CLE= CLO."CLETEXTE") SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO."Problème de récupération du body" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC SINON POUR CHAQUE LST WFFicContenu : COMMENTAIRE : "Possibilité de récupérer les informations du body ici." FIN_BLOC FIN_BLOC
Voici un exemple d’enregistrement du body de retour dans une fichier. COMMENTAIRE : "........On part du principe que vous avez utilisé l'action EXE-REQUETE au préalable." COMMENTAIRE : " Exemple de récupération du Body dans un fichier après l'exécution de la requête HTTP." VLO.RetourFonction = SW-REQUETE-HTTP( ACTION= GET-BODY , FORMAT= FICHIER , PATH= CLO."/tmp/NomFichierBodySortie") SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO."Problème de récupération du body" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC |
Autres fonctionnalités
Voici la liste des autres fonctionnalités de la fonction DIALOG « SW-REQUETE-http ».
REINIT L’action REINIT permet de supprimer toutes les caractéristiques et tous les résultats précédemment obtenus par l’utilisation de la fonction SW-REQUETE-http dans la même requête DIALOG. Il conviendra donc d’utiliser l’action REINIT si vous voulez utiliser plusieurs fois l’action «EXE-REQUETE» dans une même requête. Il faudra le placer avant de commencer à définir les caractéristiques de la nouvelle demande. | COMMENTAIRE : "Exemple de réinitialisation pour permettre de définir et d'exécuter une nouvelle requête HTTP." VLO.RetourFonction = SW-REQUETE-HTTP( ACTION= REINIT ) SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO." Problème de réinitialisation " + " " + CLO.":" + VLO.RetourFonction FIN_BLOC |
NIV-TRACE L’action NIV-TRACE permet de déterminer le niveau de trace de l’action EXE-REQUETE suivante. Il s’agit d’une valeur numérique de type entier qui peut prendre les valeurs suivantes :
L’activation des traces va générer deux fichiers supplémentaires dans le répertoire DIAP_TMP :
Voici un exemple d’utilisation de l’action NIV-TRACE : | COMMENTAIRE : "Exemple d'activation des traces" VLO.RetourFonction = SW-REQUETE-HTTP( ACTION= NIV-TRACE , VALEUR= CLO.1 ) SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO."Problème avec l'activation des traces" + " " + CLO.":" + VLO.RetourFonction FIN_BLOC |
OPTION Les options sont des paramètres sous la forme CLE / Valeur qui vont permettre de modifier certains paramètres techniques de l’exécution de la requête http : L’option CERTIFICAT va permettre de spécifier le chemin complet du certificat que l’on souhaite utiliser pour la requête L’option FICHIERS-TMP va permettre de spécifier le répertoire de travail pour une requête donnée. | Voici un exemple d’utilisation d’une option : COMMENTAIRE : "Exemple de modification du répertoire de travail" VLO.RetourFonction = SW-REQUETE-HTTP( ACTION= OPTION , CLE-OPTION= CLO."FICHIERS-TMP" , VAL-OPTION= CLO."/tmp/" ) SI VLO.RetourFonction EXISTE ET <> "" LC-Erreur = CLO." Problème avec l'utilisation de l'option FICHIERS-TMP " + " " + CLO.":" + VLO.RetourFonction FIN_BLOC |