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
Release | Modifications |
---|---|
19 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 :
agent : 4D.HTTPAgent l'objet agent passé dans options ou l'objet agent global s'il a été omis |
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 méthode passée dans l'objet options lors de l'appel à new() |
protocol : Text le protocole 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 code de statut, sinon undefined |
returnResponseBody : Boolean le returnResponseBody passé dans l'objet options lors de l'appel à new() |
.terminate() interrompt la requête HTTP |
terminated : Boolean True si la requête est terminée (après l'appel à onTerminate ), false 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
Release | Modifications |
---|---|
20 | Validation TLS par défaut |
19 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 |
---|---|---|---|
agent | 4D.HTTPAgent | HTTPAgent à utiliser pour la requête HTTPRequest. Les options de l'agent seront fusionnées avec les options de la requête (les options de la requête sont prioritaires). Si aucun agent spécifique n'est défini, un agent global avec des valeurs par défaut est utilisé. | Objet agent global |
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 | objet d'authentification | Objet manipulant l'authentification du proxy | undefined |
serverAuthentication | objet d'authentification | Objet manipulant l'authentification par serveur | undefined |
returnResponseBody | Boolean | Si false, 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
Pour que les fonctions de rappel soient appelées lorsque vous n'utilisez pas wait()
(appel asynchrone), le process doit être un process worker créé avec CALL WORKER
, et NON New process
.
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
Release | Modifications |
---|---|
20 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 extrait le contenu vers un objet. Chaque propriété de l'objet renvoyé correspond à une partie des données multipart.
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"
//}
.agent
agent : 4D.HTTPAgent
Description
La propriété .agent
contient l'objet agent
passé dans options
ou l'objet agent global s'il a été omis.
.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 méthode
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 protocole
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
Release | Modifications |
---|---|
19 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 code de statut, 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 selon l'attribut 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()
interrompt la requête HTTP. Elle déclenche l'événement onTerminate
.
.terminated
terminated : Boolean
Description
La propriété .terminated
contient True si la requête est terminée (après l'appel à onTerminate
), false 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.
Lors d'une exécution .wait()
, les fonctions de rappel sont exécutées, que ce soit à partir d'autres instances HTTPRequest
ou SystemWorker
, ou d'autres appels CALL WORKER
. Vous pouvez sortir d'un .wait()
en appelant terminate()
à partir d'une callback.