HTTPRequest

Hérite de : Node < Object

Un nœud qui permet d'envoyer des requêtes HTTP(S).

Description

Un nœud avec la possibilité d'envoyer des requêtes HTTP. Utilise HTTPClient en interne.

Peut être utilisé pour faire des requêtes HTTP, c'est-à-dire télécharger ou téléverser des fichiers ou du contenu web via HTTP.

** Avertissement :** Voir les notes et les avertissements sur HTTPClient pour les limitations, en particulier en ce qui concerne la sécurité TLS.

Note : Lors de l'export vers Android, assurez-vous d'activer la permission INTERNET dans le pré-réglage d'export Android avant d'exporter le projet ou d'utiliser le déploiement en un clic. Sinon, les communications réseau de toutes sortes seront bloquées par Android.

Exemple : Contacter une API REST et afficher l'un des champs renvoyés :

func _ready():
    # Create an HTTP request node and connect its completion signal.
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(self._http_request_completed)

    # Effectuer une requête GET. L'URL ci-dessous renvoyait un JSON au moment où nous avons écrit ce code.
    var error = http_request.request("https://httpbin.org/get")
    if error != OK:
        push_error("Une erreur est survenue dans la requête HTTP.")

    # Effectuer une requête POST. L'URL ci-dessous renvoyait un JSON au moment où nous avons écrit ce code.
    # Note : Ne faites pas de requêtes simultanées avec un unique nœud HTTPRequest
    # Le bout de code ci-dessous est fourni seulement comme référence.
    var body = JSON.new().stringify({"name": "Godette"})
    error = http_request.request("https://httpbin.org/post", [], HTTPClient.METHOD_POST, body)
    if error != OK:
        push_error("Une erreur est survenue dans la requête HTTP.")

# Appelée quand la requête HTTP est complétée.
func _http_request_completed(result, response_code, headers, body):
    var json = JSON.new()
    json.parse(body.get_string_from_utf8())
    var response = json.get_data()

    # Will print the user agent string used by the HTTPRequest node (as recognized by httpbin.org).
    print(response.headers["User-Agent"])

public override void _Ready()
{
    // Créer un nœud de requête HTTP et se connecter à son signal de complétion.
    var httpRequest = new HttpRequest();
    AddChild(httpRequest);
    httpRequest.RequestCompleted += HttpRequestCompleted;

    // Effectuer une requête GET. L'URL ci-dessous renvoyait un JSON au moment où nous avons écrit ce code.
    Error error = httpRequest.Request("https://httpbin.org/get");
    if (error != Error.Ok)
    {
        GD.PushError("Une erreur est survenue dans la requête HTTP.");
    }

    // Effectuer une requête POST. L'URL ci-dessous renvoyait un JSON au moment où nous avons écrit ce code.
    // Note : Ne faites pas de requêtes simultanées avec un unique nœud HTTPRequest
    // Le bout de code ci-dessous est fourni seulement comme référence.
    string body = new Json().Stringify(new Godot.Collections.Dictionary
    {
        { "name", "Godette" }
    });
    error = httpRequest.Request("https://httpbin.org/post", null, HttpClient.Method.Post, body);
    if (error != Error.Ok)
    {
        GD.PushError("Une erreur est survenue dans la requête HTTP.");
    }
}

// Appelée quand la requête HTTP est complétée.
private void HttpRequestCompleted(long result, long responseCode, string[] headers, byte[] body)
{
    var json = new Json();
    json.Parse(body.GetStringFromUtf8());
    var response = json.GetData().AsGodotDictionary();

    // Will print the user agent string used by the HTTPRequest node (as recognized by httpbin.org).
    GD.Print((response["headers"].AsGodotDictionary())["User-Agent"]);
}

Exemple : Charger une image en utilisant HTTPRequest et l'afficher :

func _ready():
    # Créer un nœud de requête HTTP et se connecter à son signal de complétion.
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(self._http_request_completed)

    # Effectuer la requête HTTP. L'URL ci-dessous renvoyait un PNG au moment où nous avons écrit ce code.
    var error = http_request.request("https://placehold.co/512.png")
    if error != OK:
        push_error("Une erreur est survenue dans la requête HTTP.")

# Appelée quand la requête HTTP est complétée.
func _http_request_completed(result, response_code, headers, body):
    if result != HTTPRequest.RESULT_SUCCESS:
        push_error("L'image n'a pu être téléchargée. Essayez avec une image différente.")

    var image = Image.new()
    var error = image.load_png_from_buffer(body)
    if error != OK:
        push_error("Impossible de charger l'image.")

    var texture = ImageTexture.create_from_image(image)

    # Afficher l'image dans un nœud TextureRect
    var texture_rect = TextureRect.new()
    add_child(texture_rect)
    texture_rect.texture = texture

public override void _Ready()
{
    // Créer un nœud de requête HTTP et se connecter à son signal de complétion.
    var httpRequest = new HttpRequest();
    AddChild(httpRequest);
    httpRequest.RequestCompleted += HttpRequestCompleted;

    // Effectuer la requête HTTP. L'URL ci-dessous renvoyait un PNG au moment où nous avons écrit ce code.
    Error error = httpRequest.Request("https://placehold.co/512.png");
    if (error != Error.Ok)
    {
        GD.PushError("Une erreur est survenue dans la requête HTTP.");
    }
}

// Appelée quand la requête HTTP est complétée.
private void HttpRequestCompleted(long result, long responseCode, string[] headers, byte[] body)
{
    if (resultat != (long)HttpRequest.Result.Success)
    {
        GD.PushError("L'image n'a pu être téléchargée. Essayez avec une image différente.");
    }
    var image = new Image();
    Error error = image.LoadPngFromBuffer(body);
    if (erreur != Error.Ok)
    {
        GD.PushError("Impossible de charger l'image.");
    }

    var texture = ImageTexture.CreateFromImage(image);

    // Afficher l'image dans un nœud TextureRect
    var textureRect = new TextureRect();
    AddChild(textureRect);
    textureRect.Texture = texture;
}

Note : Les nœuds HTTPRequest géreront automatiquement la décompression des corps de réponse. Un en-tête Accept-Encoding sera automatiquement ajouté à chacune de vos requêtes, sauf si un est déjà spécifié. Toute réponse avec un en-tête Content-Encoding: gzip sera automatiquement décompressée et livrée à vous en tant qu'octets non compressés.

Tutoriels

Propriétés

bool	accept_gzip	`true`
int	body_size_limit	`-1`
int	download_chunk_size	`65536`
String	download_file	`""`
int	max_redirects	`8`
float	timeout	`0.0`
bool	use_threads	`false`

Méthodes

void	cancel_request()
int	get_body_size() const
int	get_downloaded_bytes() const
Status	get_http_client_status() const
Error	request(url: String, custom_headers: PackedStringArray = PackedStringArray(), method: Method = 0, request_data: String = "")
Error	request_raw(url: String, custom_headers: PackedStringArray = PackedStringArray(), method: Method = 0, request_data_raw: PackedByteArray = PackedByteArray())
void	set_http_proxy(host: String, port: int)
void	set_https_proxy(host: String, port: int)
void	set_tls_options(client_options: TLSOptions)

Signaux

request_completed(result: int, response_code: int, headers: PackedStringArray, body: PackedByteArray) 🔗

Émis lorsqu'une requête est complétée.

Énumérations

enum Result: 🔗

Result RESULT_SUCCESS = 0

Requête réussie.

Result RESULT_CHUNKED_BODY_SIZE_MISMATCH = 1

Requête échouée en raison d'une erreur entre la taille de corps en bloc attendue et réelle au cours du transfert. Les causes possibles incluent les erreurs réseau, la mauvaise configuration du serveur ou les problèmes avec l'encodage en blocs.

Result RESULT_CANT_CONNECT = 2

La requête a échoué lors de la connexion.

Result RESULT_CANT_RESOLVE = 3

La requête a échoué lors de la résolution.

Result RESULT_CONNECTION_ERROR = 4

La requête a échoué en raison d'une erreur de connexion (lecture / écriture).

Result RESULT_TLS_HANDSHAKE_ERROR = 5

La requête a échoué lors de la poignée de main TLS..

Result RESULT_NO_RESPONSE = 6

La requête n'a pas (encore) de réponse.

Result RESULT_BODY_SIZE_LIMIT_EXCEEDED = 7

La requête a dépassé la taille maximale, voir body_size_limit.

Result RESULT_BODY_DECOMPRESS_FAILED = 8

La requête a échoué en raison d'une erreur lors de la décompression du corps de réponse. Les causes possibles incluent un format de compression non supporté ou incorrect, des données corrompues ou un transfert incomplet.

Result RESULT_REQUEST_FAILED = 9

Échec de la requête (actuellement inutilisé).

Result RESULT_DOWNLOAD_FILE_CANT_OPEN = 10

La HTTPRequest n'a pu ouvrir le fichier téléchargé.

Result RESULT_DOWNLOAD_FILE_WRITE_ERROR = 11

La HTTPRequest n'a pu écrire dans un fichier de téléchargement.

Result RESULT_REDIRECT_LIMIT_REACHED = 12

La requête a atteint le nombre de redirections autorisée, voir max_redirects.

Result RESULT_TIMEOUT = 13

La requête a échoué en raison d'un timeout. Si vous vous attendez à ce que les requêtes prennent du temps, essayez d'augmenter la valeur de timeout ou de le définir à 0.0 pour supprimer complètement le timeout.

Descriptions des propriétés

bool accept_gzip = true 🔗

void set_accept_gzip(value: bool)
bool is_accepting_gzip()

Si true, cet en-tête sera ajouté à chaque requête : Accept-Encoding: gzip, deflate indiquant aux serveurs qu'il est acceptable de compresser les corps de réponse.

Tout corps de réponse déclarant un Content-Encoding de gzip ou deflate sera automatiquement décompressé, et les octets non compressés seront livrés via request_completed.

Si l'utilisateur a spécifié son propre en-tête Accept-Encoding, aucun en-tête ne sera ajouté indépendamment de accept_gzip.

Si false, aucun en-tête ne sera ajouté, et aucune décompression ne sera effectuée sur les corps de réponse. Les octets bruts du corps de réponse seront renvoyés par request_completed.

int body_size_limit = -1 🔗

void set_body_size_limit(value: int)
int get_body_size_limit()

Taille maximale autorisée pour les corps de réponse. Si le corps de réponse est compressé, cela sera utilisé comme la taille maximale autorisée pour le corps décompressé.

int download_chunk_size = 65536 🔗

void set_download_chunk_size(value: int)
int get_download_chunk_size()

La taille du buffer utilisé et les octets maximaux à lire par itération. Voir HTTPClient.read_chunk_size.

Définissez ceci à une valeur inférieure (par exemple 4096 pour 4 KiB) lors du téléchargement de petits fichiers pour diminuer l'utilisation de la mémoire au coût des vitesses de téléchargement.

String download_file = "" 🔗

void set_download_file(value: String)
String get_download_file()

Le fichier dans lequel enregistrer le téléchargement. Enverra tout fichier reçu dedans.

int max_redirects = 8 🔗

void set_max_redirects(value: int)
int get_max_redirects()

Nombre maximal de redirections autorisées.

float timeout = 0.0 🔗

void set_timeout(value: float)
float get_timeout()

La durée d'attente en secondes avant un timeout. Si timeout est défini à 0.0, la requête ne fera jamais de timeout. Pour des requêtes simples, comme la communication avec une API REST, il est recommandé que timeout soit défini à une valeur adaptée au temps de réponse du serveur (par exemple entre 1.0 et 10.0). Cela permettra d'éviter les timeouts indésirables causés par des variations dans les temps de réponse du serveur tout en permettant à l'application de détecter quand une requête a timeout. Pour les requêtes plus grandes telles que les téléchargements de fichiers, il est suggéré que timeout soit défini à 0.0, désactivant la fonctionnalité de timeout. Cela contribuera à empêcher les grands transferts d'échouer à cause du dépassement de la valeur de timeout.

bool use_threads = false 🔗

void set_use_threads(value: bool)
bool is_using_threads()

Si true, le multithreading est utilisé pour améliorer les performances.

Descriptions des méthodes

void cancel_request() 🔗

Annule la requête en cours.

int get_body_size() const 🔗

Renvoie la longueur du corps de réponse.

Note : Quelques serveurs Web peuvent ne pas envoyer de longueur de corps. Dans ce cas, la valeur renvoyée sera -1. Si vous utilisez l'encodage de transfert en bloc (Chunked transfer encoding), la longueur du corps sera également de -1.

int get_downloaded_bytes() const 🔗

Renvoie le nombre d'octets téléchargés par cette HTTPRequest.

Status get_http_client_status() const 🔗

Renvoie le statut actuel du HTTPClient sous-jacent.

Error request(url: String, custom_headers: PackedStringArray = PackedStringArray(), method: Method = 0, request_data: String = "") 🔗

Crée une requête sur le HTTPClient sous-jacent. S'il n'y a pas d'erreur de configuration, il essaie de se connecter en utilisant HTTPClient.connect_to_host() et passe les paramètres à HTTPClient.request().

Renvoie @GlobalScope.OK si la requête est créée avec succès. (Ne signifie pas que le serveur a répondu), @GlobalScope.ERR_UNCONFIGURED si il n'est pas dans l'arbre, @GlobalScope.ERR_BUSY si il traite encore la requête précédente, @GlobalScope.ERR_INVALID_PARAMETER si la chaîne donnée n'est pas un format d'URL valide, ou @GlobalScope.ERR_CANT_CONNECT si il n'utilise pas de thread et HTTPClient ne peut se connecter à l'hôte..

Note : Quand method est HTTPClient.METHOD_GET, la charge utile envoyée via request_data peut être ignorée par le serveur ou même faire que le serveur rejette la requête (regardez RFC 7231 section 4.3.1 pour plus de détails). En guise de contournement, vous pouvez envoyer les données comme une chaîne de requête dans l'URL (voir String.uri_encode() pour un exemple).

Note : Il est recommandé d'utiliser le chiffrement de transport (TLS) et d'éviter d'envoyer des informations sensibles (comme des identifiants de connexion) dans les paramètres d'URL GET HTTP. Envisagez d'utiliser des requêtes HTTP POST ou des en-têtes HTTP pour ces informations à la place.

Error request_raw(url: String, custom_headers: PackedStringArray = PackedStringArray(), method: Method = 0, request_data_raw: PackedByteArray = PackedByteArray()) 🔗

Crée une requête sur le HTTPClient sous-jacent en utilisant un tableau brut d'octets pour le corps de requête. S'il n'y a pas d'erreur de configuration, il essaie de se connecter en utilisant HTTPClient.connect_to_host() et passe les paramètres à HTTPClient.request().

Renvoie @GlobalScope.OK si la requête est créée avec succès. (Ne signifie pas que le serveur a répondu), @GlobalScope.ERR_UNCONFIGURED si il n'est pas dans l'arbre, @GlobalScope.ERR_BUSY si il traite encore la requête précédente, @GlobalScope.ERR_INVALID_PARAMETER si la chaîne donnée n'est pas un format d'URL valide, ou @GlobalScope.ERR_CANT_CONNECT si il n'utilise pas le thread et HTTPClient ne peut se connecter à l'hôte.

void set_http_proxy(host: String, port: int) 🔗

Définit le serveur de proxy pour les requêtes HTTP.

Le serveur de proxy n'est pas défini si host est vide ou si port vaut -1.

void set_https_proxy(host: String, port: int) 🔗

Définit le serveur de proxy pour les requêtes HTTPS.

Le serveur de proxy n'est pas défini si host est vide ou si port vaut -1.

void set_tls_options(client_options: TLSOptions) 🔗

Définit les TLSOptions à utiliser lors de la connexion à un serveur HTTPS. Voir TLSOptions.client().