Version: v20 R4 BETA

HTTPRequest

La classe HTTPRequest vous permet de manipuler des objets HTTPRequest qui peuvent être utilisés pour configurer et envoyer des requêtes à un serveur HTTP, ainsi que pour traiter les réponses du serveur HTTP.

La classe HTTPRequest est disponible dans le class store 4D. Vous créez et envoyez des requêtes HTTP à l'aide de la fonction 4D.HTTPRequest.new(), qui renvoie un objet HTTPRequest.

Historique

Version	Modifications
v19 R6	Classe ajoutée

Exemple

Création d'une classe MyHttpRequestOptions pour les options de la requête :

Class constructor($method : Text ; $headers : Object ; $body : Text)
This.method:=$method
This.headers:=$headers
This.body:=$body

Function onResponse($request : 4D.HTTPRequest ; $event : Object)
//Méthode onResponse, si vous souhaitez traiter la requête de manière asynchrone

Function onError($request : 4D.HTTPRequest ; $event : Object)
//Méthode onError, si vous souhaitez traiter la requête de manière asynchrone

Vous pouvez maintenant créer votre requête :

var $headers : Object
$headers:=New object()
$headers["field1"]:="value1"

var myHttpRequestOptions : cs.MyHttpRequestOptions
myHttpRequestOptions := cs.MyHttpRequestOptions.new("GET" ; $headers; "")

var $request : 4D.HTTPRequest
$request:=4D.HTTPRequest.new("www.google.com" ; myHttpRequestOptions)
$request.wait() //Si vous voulez traiter la requête de manière synchrone
//Maintenant vous pouvez utiliser $request.response pour accéder au résultat de la requête ou $request.error pour vérifier l'erreur qui s'est produite.

Objet HTTPRequest

Un objet HTTPRequest est un objet non partageable.

Les objets HTTPRequest fournissent les propriétés et fonctions suivantes :


dataType : Text le `dataType` passé dans l'objet `options` lors de l'appel à new(), "auto" s'il a été omis
encoding : Text l'`encoding` passé dans l'objet `options` lors de l'appel à new(), "UTF-8" s'il a été omis
errors : Collection la collection de toutes les erreurs si au moins une erreur a été générée
headers : Object les `headers` passés dans l'objet `options` lors de l'appel à new()
method : Text la `method` passée dans l'objet `options` lors de l'appel à new()
protocol : Text le `protocol` passé dans l'objet `options` lors de l'appel à new()
response : Object la réponse à la requête si elle a reçu au moins le status code, sinon undefined
returnResponseBody : Boolean le `returnResponseBody` passé dans l'objet `options` lors de l'appel à new()
.terminate() met fin à la requête HTTP
terminated : Boolean Vrai si la requête est terminée (après l'appel à `onTerminate`), Faux sinon
timeout : Real le `timeout` passé dans l'objet `options` lors de l'appel à new()
url : Text l'URL de la requête HTTP
.wait( { time : Real } ) : 4D.HTTPRequest attend la réponse du serveur

4D.HTTPRequest.new()

Historique

Version	Modifications
v20	Validation TLS par défaut
v19 R7	Prise en charge des propriétés automaticRedirections et decodeData

4D.HTTPRequest.new( url : Text { ; options : Object } ) : 4D.HTTPRequest

Paramètres	Type		Description
url	Text	->	URL à laquelle envoyer la requête
options	Object	->	Propriétés de configuration de la requête
Résultat	4D.HTTPRequest	<-	Nouvel objet HTTPRequest

Description

La fonction 4D.HTTPRequest.new() crée et envoie une requête HTTP au serveur HTTP défini dans url avec les options définies, et renvoie un objet 4D.HTTPRequest.

L'objet HTTPRequest retourné est utilisé pour traiter les réponses du serveur HTTP et appeler des méthodes.

Dans url, passez l'URL où vous voulez envoyer la requête. La syntaxe à utiliser est la suivante :

{http://}[{user}:[{password}]@]host[ :{port}][/{path}][ ?{queryString}]
{https://}[{user}:[{password}]@]host[ :{port}][/{path}][ ?{queryString}]

Si vous omettez la partie "scheme" (http:// ou https://), une requête https est envoyée.

Par exemple, vous pouvez passer les chaînes suivantes :

    http://www.myserver.com
    www.myserver.com/path
    http://www.myserver.com/path?name="jones"
    https://www.myserver.com/login
    http://123.45.67.89:8083
    http://john:smith@123.45.67.89:8083
    http://[2001:0db8:0000:0000:0000:ff00:0042:8329]
    http://[2001:0db8:0000:0000:0000:ff00:0042:8329]:8080/index.html (**)

Paramètre `options`

Dans le paramètre options, passez un objet qui peut contenir les propriétés suivantes :

Propriété	Type	Description	Par défaut
automaticRedirections	Boolean	Si true, les redirections sont effectuées automatiquement (jusqu'à 5 redirections sont gérées, la 6e réponse de redirection est renvoyée s'il y en a une)	True
body	Variant	Corps de la requête (requis dans le cas des requêtes `post` ou `put`). Il peut s'agir d'un texte, d'un blob ou d'un objet. Le content-type est déterminé à partir du type de cette propriété, sauf s'il est défini dans les headers	undefined
certificatesFolder	Folder	Définit le dossier actif des certificats du client	undefined
dataType	Text	Type de l'attribut response body. Valeurs : "text", "blob", "object", ou "auto". Si "auto", le type du contenu du corps sera déduit de son type MIME (object pour JSON, text pour texte, javascript, xml, message http et url sous forme encodée, blob sinon)	"auto"
decodeData	Boolean	Si vrai, les données reçues dans le callback `onData` sont décompressées	False
encoding	Text	Utilisé uniquement dans le cas de requêtes avec un `body` (méthodes `post` ou `put`). Encodage du body content de la requête s'il s'agit d'un texte, ignoré si le content-type est défini dans les headers	"UTF-8"
headers	Object	Headers de la requête. Syntaxe : `headers.key=value` (value peut être une Collection si la même clé doit apparaître plusieurs fois)	Objet vide
method	Text	"POST", "GET", ou autre méthode	"GET"
minTLSVersion	Text	Définit la version minimale de TLS : "`TLSv1_0`", "`TLSv1_1`", "`TLSv1_2`", "`TLSv1_3`"	"`TLSv1_2`"
onData	Function	Callback lorsque les données du body sont reçues. Elle reçoit deux objets en paramètres (voir ci-dessous)	undefined
onError	Function	Callback lorsqu'une erreur se produit. Elle reçoit deux objets en paramètres (voir ci-dessous)	undefined
onHeaders	Function	Callback lorsque les headers sont reçus. Elle reçoit deux objets en paramètres (voir ci-dessous)	undefined
onResponse	Function	Rappel lorsqu'une réponse est reçue. Elle reçoit deux objets en paramètres (voir ci-dessous)	undefined
onTerminate	Function	Rappel lorsque la requête est terminée. Elle reçoit deux objets en paramètres (voir ci-dessous)	undefined
protocol	Text	"auto" ou "HTTP1". "auto" signifie HTTP1 dans l'implémentation actuelle	"auto"
proxyAuthentication	authentication object	Objet manipulant l'authentification du proxy	undefined
serverAuthentication	authentication object	Objet manipulant l'authentification par serveur	undefined
returnResponseBody	Boolean	Si faux, le body de la réponse n'est pas renvoyé dans l'objet `response`. Renvoie une erreur si faux et `onData` est undefined	True
timeout	Real	Timeout en secondes. Undefined = pas de timeout	Undefined
validateTLSCertificate	Boolean	Si faux, 4D ne valide pas le certificat TLS et ne renvoie pas d'erreur s'il est invalide (c'est-à-dire expiré, auto-signé...). Important : dans l'implémentation actuelle, l'autorité de certification elle-même n'est pas vérifiée.	True

Fonctions de callback

Toutes les fonctions de callback reçoivent deux paramètres objet:

Paramètres	Type
$param1	objet `HTTPRequest`
$param2	objet `Event`

Voici la séquence des appels de callbacks :

onHeaders est toujours appelé une fois
onData est appelé zéro ou plusieurs fois (non appelé si la requête n'a pas de body)
Si aucune erreur ne s'est produite, onResponse est toujours appelé une fois
Si une erreur se produit, onError est exécuté une fois (et termine la requête)
onTerminate est toujours exécuté une fois

event object

Un objet event est renvoyé lorsqu'une fonction de callback est appelée. Il contient les propriétés suivantes :

Propriété	Type	Description
.data	blob	Données reçues. Toujours undefined sauf dans la callback `onData`
.type	text	Type d'événement. Valeurs possibles : "response", "error", "headers", "data", or "terminate"

authentication object

Un objet d'authentification gère la propriété options.serverAuthentication ou options.proxyAuthentication . Il peut contenir les propriétés suivantes :

Propriété	Type	Description	Par défaut
name	Text	Nom utilisé pour l'authentification	undefined
password	Text	Mot de passe utilisé pour l'authentification	undefined
method	Text	Méthode utilisée pour l'authentification : "basic", "digest", "auto"	"auto"

HTTP Parse message

Historique

Version	Modifications
v20 R4	Ajout

HTTP Parse message( data : Text ) : Object
HTTP Parse message( data : Blob ) : Object

Paramètres	Type		Description
data	Text, Blob	->	Données à analyser
Résultat	Object	<-	Objet dont chaque propriété est une partie des données multiparties

Description

La commande HTTP Parse message analyse un texte ou un blob multipart/form-data (message HTTP "response") et en extrait le contenu dans un objet. Chaque propriété de l'objet renvoyé correspond à une partie des données multiparties.

info

HTTP lui-même est un protocole de communication sans état. Dans ce cadre, les clients initient la communication en envoyant des messages "request" aux serveurs, en spécifiant des détails tels que la méthode, la cible, les en-têtes, le contenu, etc. Les serveurs, à leur tour, répondent par des messages "response" qui contiennent les mêmes détails. HTTP Parse message analyse le message "request" ou "response" et retourne un objet structuré.

Exemple

Dans l'exemple suivant, nous analysons les données d'un fichier texte contenant des requêtes HTTP.

Voici le contenu du fichier :

POST /batch/gmail/v1/ HTTP/1.1
Accept-Encoding: gzip, deflate
Authorization: Bearer xxxxxx
Connection: Close
Content-Length: 442
Content-Type: multipart/mixed; boundary=batch_19438756D576A14ABA87C112F56B9396; charset=UTF-8
Date: Wed, 29 Nov 2023 13:51:35 GMT
Host: gmail.googleapis.com
User-Agent: 4D/20.4.0


--batch_19438756D576A14ABA87C112F56B9396
Content-Type: application/http
Content-ID: <item1>

GET https://gmail.googleapis.com/gmail/v1/users/me/messages/18c1b58689824c92?format=raw HTTP/1.1


--batch_19438756D576A14ABA87C112F56B9396
Content-Type: application/http
Content-ID: <item2>

GET https://gmail.googleapis.com/gmail/v1/users/me/messages/18c1b58642b28e2b?format=raw HTTP/1.1

--batch_19438756D576A14ABA87C112F56B9396--

Pour analyser le fichier :

var $message : Text:=File("/RESOURCES/HTTPrequest.txt").getText()
var $parsedMessage : Object:=HTTP Parse message($message)
//$parsedMessage= {
//headers:{"User-Agent":"4D/20.4.0",...},
//parts:[{"contentType":"application/http","contentID":"item1",...}], 
//requestLine:"POST /batch/gmail/v1/ HTTP/1.1"
//}

.dataType

dataType : Text

Description

La propriété .dataType contient le dataType passé dans l'objet options lors de l'appel à new(), "auto" s'il a été omis.

.encoding

encoding : Text

Description

La propriété .encoding contient l'encoding passé dans l'objet options lors de l'appel à new(), "UTF-8" s'il a été omis.

.errors

errors : Collection

Description

La propriété .errors contient la collection de toutes les erreurs si au moins une erreur a été générée.

Voici le contenu de la propriété .errors :

Propriété		Type	Description
errors		Collection	Pile d'erreurs 4D en cas d'erreur
	[].errCode	Number	Code d'erreur 4D
	[].message	Text	Description de l'erreur 4D
	[].componentSignature	Text	Signature du composant interne qui a retourné l'erreur

.headers

headers : Object

Description

La propriété .headers contient les headers passés dans l'objet options lors de l'appel à new(). S'il a été omis, contient un objet vide.

.method

method : Text

Description

La propriété .method contient la method passée dans l'objet options lors de l'appel à new(). S'il a été omis, elle contient "GET".

.protocol

protocol : Text

Description

La propriété .protocol contient le protocol passé dans l'objet options lors de l'appel à new(). S'il a été omis ou si "auto" a été utilisé, contient la version du protocole utilisé.

.response

Historique

Version	Modifications
v19 R8	`.headers` renvoie les noms en minuscules. Nouvelle propriété `.rawHeaders`

response : Object

Description

La propriété .response contient la réponse à la requête si elle a reçu au moins le status code, sinon undefined.

Un objet response est un objet non partageable. Il contient les propriétés suivantes :

Propriété	Type	Description
.body	Variant	Body de la réponse. Le type du message est défini en fonction de la propriété `dataType`. Undefined si le body n'a pas encore été reçu
.headers	Object	Headers de la réponse. Les noms des headers sont retournés en minuscules. `<headername>.key` = valeur (la valeur peut être une collection si la même clé apparaît plusieurs fois). Undefined si les headers n'ont pas encore été reçus.
.status	Number	Status code de la réponse
.statusText	Text	Message expliquant le status code
.rawHeaders	Object	Headers de la réponse. Les noms des headers sont retournés tels quels (avec leur casse d'origine). `<headerName>.key` = valeur (la valeur peut être une collection si la même clé apparaît plusieurs fois). Undefined si les headers n'ont pas encore été reçus.

.returnResponseBody

returnResponseBody : Boolean

Description

La propriété .returnResponseBody contient le returnResponseBody passé dans l'objet options lors de l'appel à new(). S'il a été omis, il contient True.

.terminate()

.terminate()

Paramètres	Type		Description
			Ne requiert aucun paramètre

Description

Cette fonction est thread-safe.

La fonction .terminate() met fin à la requête HTTP. Elle déclenche l'événement onTerminate .

.terminated

terminated : Boolean

Description

La propriété .terminated contient Vrai si la requête est terminée (après l'appel à onTerminate), Faux sinon.

.timeout

timeout : Real

Description

La propriété .timeout contient le timeout passé dans l'objet options lors de l'appel à new(). S'il a été omis, il contient Undefined.

.url

url : Text

Description

La propriété .url contient l'URL de la requête HTTP.

.wait()

.wait( { time : Real } ) : 4D.HTTPRequest

Paramètres	Type		Description
time	Real	->	Délai d'attente maximum en secondes pour la réponse
Résultat	4D.HTTPRequest	<-	Objet HTTPRequest

Description

Cette fonction est thread-safe.

La fonction wait() attend la réponse du serveur.

Si un paramètre time est passé, la fonction attendra au maximum le nombre de secondes défini.

Si la réponse du serveur est déjà arrivée, la fonction rend la main immédiatement.

Exemple​

Objet HTTPRequest​

4D.HTTPRequest.new()​

Description​

Paramètre options​

Fonctions de callback​

event object​

authentication object​

HTTP Parse message​

Description​

Exemple​

.dataType​

Description​

.encoding​

Description​

.errors​

Description​

.headers​

Description​

.method​

Description​

.protocol​

Description​

.response​

Description​

.returnResponseBody​

Description​

.terminate()​

Description​

.terminated​

Description​

.timeout​

Description​

.url​

Description​

.wait()​

Description​

Exemple

Objet HTTPRequest

4D.HTTPRequest.new()

Description

Paramètre `options`

Fonctions de callback

event object

authentication object

HTTP Parse message

Description

Exemple

.dataType

Description

.encoding

Description

.errors

Description

.headers

Description

.method

Description

.protocol

Description

.response

Description

.returnResponseBody

Description

.terminate()

Description

.terminated

Description

.timeout

Description

.url

Description

.wait()

Description