Fonction HttpsGet  [Web]

Syntaxe

HttpsGet(< URL > [, < Option > : < Valeur >] [, < Option > : < Valeur >] …)

  • < URL > : l'url à appeler en GET. Le préfixe "https://" est facultatif.
  • < Option > : le nom d'une option (voir la remarque), avec ou sans guillemets.
  • < Valeur > : la valeur de l'option (une valeur ou une formule).

Description

Fait une requête GET en utilisant le protocole https, retourne le résultat de la requête.


Elle permet de :

  • d'appeler des services web (API)
  • passer des paramètres de requête, sans avoir à les encoder ;
  • s'authentifier : identifiant et mot de passe (basic ou digest), jeton Bearer ou OAuth2 (SIMAX gère la demande d'autorisation et la récupération du token d'accès) ;
  • ajouter des en-têtes http, y compris des en-têtes dont la valeur est calculée une fois l'URL et le corps de la requête construits (une signature par exemple) ;
  • gérer les cookies ;
  • traiter la réponse avant de la retourner : code de retour, en-têtes, type MIME, nom de fichier ou réponse brute.

Remarque

Les options s'écrivent après l'URL, sous la forme Option : Valeur, séparées par des virgules. Le nom d'une option s'écrit avec ou sans guillemets, et sa casse et ses accents n'ont pas d'importance. Les noms entre parenthèses sont des alias. Une option peut être répétée quand c'est précisé.

Paramètres de la requête :

  • AvecCookies (NeedCookies / WithCookies) : 0 ou 1, si l'appel a besoin de récupérer les cookies pour fonctionner ( cf https://en.wikipedia.org/wiki/HTTP_cookie ).
  • Param (Params) : paramètres de la requête. Le nom et la valeur sont encodés automatiquement pour l'URL : inutile de les encoder soi-même. L'option peut être répétée, un paramètre par option, ex : Param : "ville=montpellier", Param : "pays=france". La valeur peut avoir les formes suivantes :
    • un texte avec les paramètres séparés par des « ; », ex : Param : "ville=montpellier;pays=france"
    • un tableau de 2 éléments, le nom puis la valeur, ex : Param : Tableau( "base", "eur" )
    • un tableau de tableaux de 2 éléments, un par paramètre, ex : Param : Tableau( Tableau( "base", "eur" ), Tableau( "symbols", "usd" ) ), c'est-à-dire Tableau( Tableau( <nom param 1>, <valeur param 1> ), Tableau( <nom param 2>, <valeur param 2> ) [, …] )
    • Nul : aucun paramètre n'est ajouté (utile pour un paramètre facultatif)
  • Param_N : comme Param (mêmes formes de valeur), mais le nom (à gauche du =) n'est pas encodé.
  • Param_NV : comme Param (mêmes formes de valeur), mais ni le nom ni la valeur ne sont encodés.
  • Param_V : comme Param (mêmes formes de valeur), mais la valeur (à droite du =) n'est pas encodée.

En-têtes :

  • Entête (Entêtes / Header / Headers) : en-têtes http supplémentaires à donner à la requête ( cf https://en.wikipedia.org/wiki/List_of_HTTP_header_fields ). L'option peut être répétée, un en-tête par option, ex : Entête : "Accept:application/json", Entête : "Accept-Language:fr". La valeur est un texte au format "Nom:valeur".
  • Entête_Nom (Header_Name) : nom d'un en-tête dont la valeur est donnée par l'option Entête_Valeur qui suit L'option peut être répétée, avec une Entête_Valeur après chaque Entête_Nom..
  • Entête_Valeur (Header_Value) : valeur de l'en-tête de l'Entête_Nom précédent. C'est une formule évaluée après la construction de l'URL et du corps de la requête. Elle peut utiliser les arguments suivants :
    • <% Chemin %> (<% Path %>) : chemin de l'URL
    • <% Corps %> (<% Body %>) : corps de la requête
    • <% Horodatage %> (<% TimeStamp %>) : horodatage de la requête (sa valeur peut être fixée avec l'option Horodatage)
    • <% Hote %> (<% Host %>) : nom d'hôte de l'URL
    • <% Méthode %> (<% Method %>) : méthode HTTP de la requête
    • <% MotDePasse %> (<% Password %>) : mot de passe de la requête
    • <% Port %> : port de l'URL
    • <% Protocole %> (<% Protocol %>) : protocole de l'URL
    • <% Requête %> (<% Query %>) : partie requête (paramètres) de l'URL
    • <% Scheme %> : schéma de l'URL
    • <% URL %> (<% URI %>) : URL de la requête
    • <% Utilisateur %> (<% User %>) : utilisateur de la requête
  • Horodatage : fixe la valeur de l'argument <% Horodatage %> utilisé dans Entête_Valeur, par exemple avec l'heure renvoyée par le serveur de l'API.

Authentification :

  • ApiToken : identifiant pour l'api utilisée (il faut spécifier l'option Auth en tant que bearer pour avoir un Authorization Bearer).
  • Auth : type d'authentification : basic, digest ou bearer (basic par défaut).
  • BearerToken : token (cette option force l'authentification en bearer).
  • Identifiant (Login, ClientId, Client_Id) : identifiant pour l'authentification.
  • MotDePasse (Password, ClientSecret, Client_Secret) : mot de passe pour l'authentification.

Retour :

  • TraiteRetour (ProcessResponse) : formule qui transforme le retour de l'api en résultat de la fonction. Elle peut utiliser les arguments suivants :
  • <% Brut %> : réponse HTTP brute
  • <% Code %> : code de retour HTTP
  • <% Corps %> (<% Body %>) : corps de la réponse
  • <% Entetes %> (<% Entities %>, <% Headers %>) : en-têtes de la réponse (<% Headers %> est disponible à partir de la version 2641 de SIMAX ; <% Entities %> reste valable pour la compatibilité)
  • <% MimeType %> (<% ContentType %>) : type MIME de la réponse
  • <% MultiPart %> : matrice dont chaque ligne est un tableau de 3 éléments : le cid du multipart, le multipart (de type fichier ou texte long selon son contenu) et son type MIME. Un multipart se récupère par son cid avec ValeurTableau. Les cid ne sont pas fixes : ils sont propres à la requête, souvent indiqués dans le contenu principal (<% Corps %>), et parfois absents.
  • <% NomFichier %> (<% FileName %>) : nom du fichier de la réponse

OAuth2 :

  • OAuth2_Access_Custom : tableau à 2 axes avec des paramètres spécifiques à la phase de récupération du token d'accès.
  • OAuth2_AccessToken_Uri : l'url pour la demande de token.
  • OAuth2_Auth_Custom (OAuth2_Authorization_Custom) : tableau à 2 axes avec des paramètres spécifiques à la phase d'autorisation.
  • OAuth2_Authorization_Timeout (OAuth2_Auth_Timeout) : durée en secondes au bout de laquelle la requête échoue si l'utilisateur n'a pas autorisé l'application SIMAX (par défaut 5 minutes).
  • OAuth2_Authorization_Uri (OAuth2_Auth_Uri) : l'url pour la demande d'autorisation de l'application.
  • OAuth2_Grant_Type (OAuth2_GrantType) : type d'identification.
  • OAuth2_Scope : scope.
  • OAuth2_Spec_Omettre_Scope_Si_Vide (OAuth2_Spec_Omit_Scope_If_Empty, OAuth2_Spec_Ommetre_Scope_Si_Vide) : si Vrai, le paramètre scope est omis de la demande de token quand le scope est vide (pour les api qui n'acceptent pas de scope vide). Disponible à partir de la version 2641 de SIMAX (avant cette version, seul l'ancien nom OAuth2_Spec_Ommetre_Scope_Si_Vide existe ; sa faute d'orthographe est conservée pour la compatibilité).
  • OAuth2_Spec_Path2Response (OAuth2_Spec_Path_To_Response) : chemin vers la racine de l'objet json qui contient le token d'accès, si l'api n'est pas conforme à la norme.
  • OAuth2_Spec_QueryParamForAccessToken (OAuth2_Spec_Query_Param_For_Access_Token) : paramètre pour le token d'accès, si l'api n'est pas conforme à la norme.
  • OAuth2_Spec_Redirect_Port : port pour la redirection après la demande d'autorisation, si elle doit être fixe.

Comportement de la requête :

  • Résultat : du texte, ou une valeur de type fichier si le contenu de la réponse est binaire.
  • Erreurs HTTP (4xx, 5xx) : si l'option TraiteRetour est présente, c'est à sa formule de gérer le cas d'erreur (par exemple avec <% Code %>) ; sinon, l'erreur HTTP provoque une erreur de formule.
  • Redirections : elles sont suivies automatiquement.
  • Compression : pas de décompression gzip.
  • Délai d'attente : 1 minute par défaut, modifiable dans info.simax avec la clé WEBSERVICE_TIMEOUT de la section [CLIENT].
  • Journal : les appels des fonctions http et https peuvent être journalisés en renseignant, dans la section [CLIENT] de info.simax, la clé CLIENTWEBSERVICE_LOG=chemin du fichier de log.
  • Réponse sans contenu (204) : la fonction retourne Nul.

Exemple

HttpsGet( "www.monip.org" )

Retourne le texte de la réponse de la page.


HttpsGet( "maps.googleapis.com/maps/api/geocode/json"

, Param : "key="+['Clé Api Google' de 'Paramètres généraux' <1FFIF8A79H>]

, Param : "address="+RemplaceAccent( ['Adresse à envoyer' de 'Web Service coordonnées' <14DMF89OKA>] )

)

Appelle l'API de géocodage avec deux paramètres de requête, sans avoir à les encoder.


HttpsGet( ['URL' de 'Signature Yousign' <172L4S5M9E>]+"/signature_requests/"+['Id Signature Request' de 'Signature Yousign' <16UPP3EVGP>]

, Auth : "Bearer"

, ApiToken : Col( ['Clé API' de 'Paramètres Yousign' <16H0RRLI4J>], ['Paramètres Yousign' de 'Signature Yousign' <1C3SS69DUU>] )

)

Appelle une API en envoyant un jeton dans l'en-tête Authorization Bearer.


HttpsGet( "api.insee.fr/entreprises/sirene/V3.11/siren/"+Gauche( Remplace( <%Siren%>, " ", "" ), 9 )

, BearerToken : <%APIKey%>

)

Appelle l'API avec un jeton Bearer. Équivalent plus court de l'exemple précédent : BearerToken force l'authentification Bearer.


HttpsGet( "api.exemple.fr/export"

, Identifiant : "mon_login"

, MotDePasse : "mon_mot_de_passe"

)

Appelle une API avec une authentification par identifiant et mot de passe (basic par défaut).


HttpsGet( "api.exemple.fr/v1/clients"

, Entête : "Accept:application/json"

, Entête : "Accept-Language:fr"

)

Ajoute deux en-têtes à la requête.


HttpsGet( "eu.api.ovh.com/1.0/"+<%API%>

, Horodatage : HttpsGet( "eu.api.ovh.com/1.0/auth/time" )

, Entête : "X-Ovh-Application:"+<%ApplicationKey%>

, Entête : "X-Ovh-Consumer:"+<%ConsumerKey%>

, Entête_Nom : "X-Ovh-Timestamp"

, Entête_Valeur : <% Horodatage %>

, Entête_Nom : "X-Ovh-Signature"

, Entête_Valeur : "$1$"+HachageValeur( "sha1", <%ApplicationSecret%>+"+"+<%ConsumerKey%>+"+"+<% Méthode %>+"+"+<% URL %>+"+"+ChangeCharset( <% Corps %>, "ANSI", "UTF8" )+"+"+<% Horodatage %>, "hexamin" )

)

Signe la requête : l'horodatage est celui du serveur de l'API, et l'en-tête de signature est construit après l'URL et le corps de la requête grâce à Entête_Valeur.


HttpsGet( "www.googleapis.com/calendar/v3/calendars/primary/events"

, ClientId : "229031535445-xxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com"

, ClientSecret : "xxxxxxx"

, OAuth2_Scope : "https://www.googleapis.com/auth/calendar.events"

)

Appelle l'API avec une authentification OAuth2.


HttpsGet( "api.exemple.fr/v1/commandes"

, TraiteRetour : ConstruitJSON( "code" : <% Code %>, "body" : <% Corps %> )

)

Retourne un JSON contenant le code de retour HTTP et le corps de la réponse.


HttpsGet( "api.laposte.fr/suivi/v2/idships/"+['Réf transporteur' de 'Bon de livraison' <15VKUK1HGP>]

, Header : "X-Okapi-Key: "+['LaPoste Clé API' de 'Paramètres logistiques' <1F53E2NU40>]

, Header : "Accept: application/json"

, TraiteRetour : MajValeurJSON( ""

, ""

, Tableau( Tableau( "code", ValeurJSON( <% Code %>, "returnCode" ) )

, Tableau( "body", ValeurJSON( <% Corps %>, "shipment/event[0]" ) )

)

, 1 )

)

Appelle l'API de suivi de La Poste, avec la clé d'API dans l'en-tête X-Okapi-Key, et retourne un JSON à deux clés : code et body.


HttpsGet( "api.insee.fr/api-sirene/3.11/siren/"+SiNonVide( Gauche( Remplace( ['N° de Siret' de 'Société' <16P5BEJI2G>], " ", "" ), 9 )

, Gauche( Remplace( ['N° Siret' de 'Société' <1APH34P8FE>], " ", "" ), 9 ) )

, "Header" : ( "X-INSEE-Api-Key-Integration: "+['Clé API SIREN' de 'Paramètres généraux' <1028KOG0MH>] )

)

Appelle l'API Sirene de l'INSEE avec les 9 premiers caractères du numéro de Siret de la société (lu dans l'une ou l'autre des deux colonnes, espaces retirés), la clé d'API étant envoyée dans l'en-tête X-INSEE-Api-Key-Integration. Les noms d'options peuvent être écrits entre guillemets, et leur valeur entre parenthèses.


<%Params%> := SI( <%Limit%><>Nul, Tableau( "limit", <%Limit%> ) )

HttpsGet( "api.openai.com/v1/batches"

, Params : <%Params%>

, BearerToken : <%APIKey%>

)

Dans une fonction externe, construit les paramètres de la requête dans <%Params%>, un argument local dont le nom est libre : le tableau (nom, valeur) n'est créé que si le paramètre <%Limit%> est renseigné, sinon <%Params%> vaut Nul et aucun paramètre n'est ajouté. L'API est appelée avec un jeton Bearer.


ConvertitFichier(

HttpsGet( "api.qrserver.com/v1/create-qr-code/"

, Param : "size=125x125"

, Param : "margin=10"

, Param : "data="+ConstruitJSON( "name" : "un petit test", "serialnumber" : "IW-001" )

)

, "qrcode.png"

)

Génère un QR code avec un service web et le convertit en fichier image nommé qrcode.png. Chaque paramètre est encodé automatiquement par Param, y compris le JSON passé dans data.


HttpsGet( "api.ppd.iopole.fr/v1/invoice/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/download"

, ClientId : "xxxxxx"

, ClientSecret : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

, OAuth2_AccessToken_Uri : "auth.ppd.iopole.fr/realms/iopole/protocol/openid-connect/token"

, OAuth2_Grant_Type : "client_credentials"

, OAuth2_Spec_Omettre_Scope_Si_Vide : Vrai

, TraiteRetour : ConstruitJSON( "code" : <% Code %>

, "body" : <% Corps %>

, "mimetype" : <% MimeType %>

, "multipart" : <% MultiPart %>

)

)

Télécharge une facture avec une authentification OAuth2 de type client_credentials, sans scope. Retourne un JSON contenant le code de retour, le corps, le type MIME et le contenu multipart de la réponse. Avant la version 2641 de SIMAX, l'option OAuth2_Spec_Omettre_Scope_Si_Vide s'écrit OAuth2_Spec_Ommetre_Scope_Si_Vide.


HttpsGet( "www.org.com/6803/open-book.jpg"

, Entête : "Host: www.org.com"

)

Récupère une image. L'en-tête Host force l'origine de la requête et évite une erreur 404.


HttpsGet( "api.exemple.fr/documents/multipart"

, TraiteRetour : ConstruitJSON( "code" : <% Code %>

, "body" : <% Corps %>

, "mimetype" : <% MimeType %>

, "multipart" : <% MultiPart %>

, "cid" : ValeurJSON( <% Corps %>, "/[1]/cid" )

, "base64" : EncodeBase64( ValeurTableau( <% MultiPart %>, ValeurJSON( <% Corps %>, "/[1]/cid" ), 2 ) )

)

)

Lit le cid indiqué dans le corps de la réponse (un JSON), puis encode en base64 le multipart correspondant : ValeurTableau retrouve la ligne de <% MultiPart %> par son cid et retourne son 2e élément, le multipart.