`$http.request`¶

Description¶

Génère une requête HTTP.

Syntaxe¶

$http.request( url [ , options ] )

Paramètres¶

url string

URL à appeler

options map

Paramètres supplémentaires d'appel. En l'absence de paramètres, la méthode effectue un simple GET sur l'URL. Les options reconnues sont:

method string

Méthode d'appel; peut valoir GET, POST, DELETE, PUT ou PATCH. Si non défini, la méthode est déterminée en fonction des autres options: si un payload ou des inputs sont présents, la méthode par défaut sera POST. Dans le cas contraire, la méthode par défaut sera GET. Cette dernière est la méthode par défaut si aucune option n'est spécifiée.

type string

Type de requête à construire. Peut valoir:

none : pour les requêtes sans payload, notamment dans le cas d'une requête GET
multipart : formulaire multipart
form : formulaire url-encoded
data (ou raw ou payload) : données brutes passées sans mise en forme directement dans le payload de la requête

S'il n'est pas spécifié, le type est déterminé en fonction des autres options. Ainsi, si un payload est présent, le type sera considéré comme data. Si des inputs sont fournis, le type sera form, sauf en cas de présence de fichiers parmi ces inputs. Dans ce cas, le type sera multipart. En l'absence d'inputs ou de payload, le type sera none.

parameters map

Paramètres d'URL; doit se présenter sous la forme d'une map clé/valeur; les paramètres définis ici seront ajoutés à l'URL

inputs map

Champs de formulaire à envoyer (dans le cas où le type est form ou multipart); doit se présenter sous la forme d'une map clé/valeur (la valeur pouvant être une valeur litérale ou un fichier)

payload string / file

Contenu à envoyer (uniquement dans le cas où le type est data; peut être une valeur litérale ou un fichier

headers map

Map clé/valeur décrivant les headers à reprendre dans la requête

auth map

Objet décrivant la méthode d'authentification sur le service; le contenu de l'objet varie en fonction du type d'authentification; les méthodes d'authentification actuellement reconnues sont:

Basic authentication: { type: "basic", username: "abc", password: "xyz" }
Bearer token: { type: "bearer", token: "abcxyz..." }

À noter qu'il est également possible de gérer l'authentification en agissant directement au niveau des headers de la requête

sslContext array

Permet de référencer un certificat à utiliser pour la connexion SSL. Cette valeur doit être une table contenant les éléments suivants:

file: Objet de type file référençant le keystore
type: Type de keystore (jceks, jks, dks, pkcs11, pkcs12) - voir KeyStore Types
storePassword: Mot de passe du keystore
keyPassword: Mot de passe du certificat

timeout number

Durée de timeout en secondes (par défaut 0)

charset string

Charset à utiliser pour la requête.

Si la propriété n'est pas définie, le charset utilisé par défaut est UTF-8. Il est possible de spécifier un charset vide ou null. Cela peut être nécessaire pour certains serveurs distant qui ne supportent pas la présence d'un charset et d'un boundary dans un content-type multipart par exemple.

boundary string

Boundary à utiliser dans le cas de requête multipart. Par défaut le boundary est généré automatiquement.

multipartMode string

Mode de requête multipart. Les valeurs possibles sont:

"strict": mode compatible RFC 822, RFC 2045, RFC 2046; c'est ce mode qui est appliqué par défaut
"lax": mode browser-compatible, dans ce mode seul le Content-Disposition est écrit; s'appuie sur le charset du contenu
"rfc6532": mode compatible RFC 6532

Voir HttpMultipartMode

destfile file / string

Fichier dans lequel les données de la réponse doivent être inscrites (peut désigner soit un file soit un path de manière litérale). Il est très fortement recommandé d'utiliser cette option pour le traitement de gros fichiers afin d'éviter des erreurs de type "OutOfMemory".

onprogress function

Fonction de callback à invoquer pour donner à l'application un retour sur le téléchargement de la réponse. Cette propriété n'est fonctionnelle que lorsque la réponse retourne des données binaires. Elle est utile lorsque la méthode attend un gros volume de données.

La fonction de callback, si définie, est invoquée toutes les secondes durant le téléchargement de la requête. Précisons au passage que la fonction de callback ne donne pas de retour sur le traitement de la requête par le host, mais uniquement l'état d'avancement du téléchargement.

Exemple d'utilisation:

$http.request("some_online_url", {
    method: "GET",
    destfile: $file.load("C:/Temp/sample.zip"),
    onprogress: function(event) {
      $logger.info($str.format(
          event.progress,
          {
              type: "double",
              mode: "percent",
              pattern: "0.00"
          }) & "%");
    }
});

Le paramètre event de la fonction de callback est un map contenant propriétés suivantes:

loaded: quantité de données déjà traitées
total: quantité total de données attendues
progress: rapport loaded / total
target: valeur donnant une indication sur la cible de l'event

La fonction de callback peut interrompre le traitement en retournant la valeur false.

interval number

Intervalle de temps en millisecondes entre deux appels de la fonction de callback onprogress. Par défaut, l'intervalle est fixé à 1000 (1 seconde).

Retour¶

Objet de type map contenant les éléments de la réponse (statut, headers, payload, mimetype, charset, etc.)

Exemple¶

Exemple de téléchargement d'un fichier avec affichage de l'état de progression toutes les 2.5 secondes dans le log.

$http.request(
    "https://public.madd.bfs.admin.ch/ch.zip", {
        method: "GET",
        destfile: $file.load("c:/Temp/ch.zip"),
        onprogress: function(event) {
            $logger.info($str.format(event.progress, {
                type: "double", mode: "percent", pattern: "0.00" }) & "%");
        },
        interval: 2500
    }
);
$logger.info("done");

La trace générée par le script ci-dessus est la suivante:

2024-01-06 17:41:38,973738 DEBUG ch.epilogic.ewt.utils.EwtHttpUtils.sendHttpRequest():357 - Invoke HTTP using default client builder
2024-01-06 17:41:39,820300 DEBUG ch.epilogic.ewt.utils.EwtHttpUtils.sendHttpRequest():586 - HTTP request status: 200 (OK)
2024-01-06 17:41:42,588705 INFO  ch.epilogic.ewt.scripts.library.EwtScriptLibLogger.infoApp():260 coupon - 0.79%
2024-01-06 17:41:45,089226 INFO  ch.epilogic.ewt.scripts.library.EwtScriptLibLogger.infoApp():260 coupon - 2.80%
2024-01-06 17:41:47,590814 INFO  ch.epilogic.ewt.scripts.library.EwtScriptLibLogger.infoApp():260 coupon - 5.80%
2024-01-06 17:41:50,094181 INFO  ch.epilogic.ewt.scripts.library.EwtScriptLibLogger.infoApp():260 coupon - 8.29%
...
2024-01-06 17:42:57,695878 INFO  ch.epilogic.ewt.scripts.library.EwtScriptLibLogger.infoApp():260 coupon - 83.84%
2024-01-06 17:43:00,198145 INFO  ch.epilogic.ewt.scripts.library.EwtScriptLibLogger.infoApp():260 coupon - 86.84%
2024-01-06 17:43:02,698229 INFO  ch.epilogic.ewt.scripts.library.EwtScriptLibLogger.infoApp():260 coupon - 90.20%
2024-01-06 17:43:05,200939 INFO  ch.epilogic.ewt.scripts.library.EwtScriptLibLogger.infoApp():260 coupon - 92.39%
2024-01-06 17:43:07,703469 INFO  ch.epilogic.ewt.scripts.library.EwtScriptLibLogger.infoApp():260 coupon - 94.77%
2024-01-06 17:43:10,206239 INFO  ch.epilogic.ewt.scripts.library.EwtScriptLibLogger.infoApp():260 coupon - 97.87%
2024-01-06 17:43:11,648872 INFO  ch.epilogic.ewt.scripts.library.EwtScriptLibLogger.infoApp():260 coupon - 100.00%
2024-01-06 17:43:11,669768 INFO  ch.epilogic.ewt.scripts.library.EwtScriptLibLogger.infoApp():260 coupon - done

$http.request¶