Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

HTTPRequest

Hérite de : Node < Object

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

Description

A node with the ability to send HTTP requests. Uses HTTPClient internally.

Can be used to make HTTP requests, i.e. download or upload files or web content via HTTP.

Warning: See the notes and warnings on HTTPClient for limitations, especially regarding TLS security.

Note: When exporting to Android, make sure to enable the INTERNET permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android.

Example: Contact a REST API and print one of its returned fields:

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)

    # Perform a GET request. The URL below returns JSON as of writing.
    var error = http_request.request("https://httpbin.org/get")
    if error != OK:
        push_error("An error occurred in the HTTP request.")

    # Perform a POST request. The URL below returns JSON as of writing.
    # Note: Don't make simultaneous requests using a single HTTPRequest node.
    # The snippet below is provided for reference only.
    var body = JSON.stringify({"name": "Godette"})
    error = http_request.request("https://httpbin.org/post", [], HTTPClient.METHOD_POST, body)
    if error != OK:
        push_error("An error occurred in the HTTP request.")

# Called when the HTTP request is completed.
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()
{
    // Create an HTTP request node and connect its completion signal.
    var httpRequest = new HttpRequest();
    AddChild(httpRequest);
    httpRequest.RequestCompleted += HttpRequestCompleted;

    // Perform a GET request. The URL below returns JSON as of writing.
    Error error = httpRequest.Request("https://httpbin.org/get");
    if (error != Error.Ok)
    {
        GD.PushError("An error occurred in the HTTP request.");
    }

    // Perform a POST request. The URL below returns JSON as of writing.
    // Note: Don't make simultaneous requests using a single HTTPRequest node.
    // The snippet below is provided for reference only.
    string body = 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("An error occurred in the HTTP request.");
    }
}

// Called when the HTTP request is completed.
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"]);
}

Example: Load an image using HTTPRequest and display it:

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)

    # Perform the HTTP request. The URL below returns a PNG image as of writing.
    var error = http_request.request("https://placehold.co/512.png")
    if error != OK:
        push_error("An error occurred in the HTTP request.")

# Called when the HTTP request is completed.
func _http_request_completed(result, response_code, headers, body):
    if result != HTTPRequest.RESULT_SUCCESS:
        push_error("Image couldn't be downloaded. Try a different image.")

    var image = Image.new()
    var error = image.load_png_from_buffer(body)
    if error != OK:
        push_error("Couldn't load the image.")

    var texture = ImageTexture.create_from_image(image)

    # Display the image in a TextureRect node.
    var texture_rect = TextureRect.new()
    add_child(texture_rect)
    texture_rect.texture = texture

public override void _Ready()
{
    // Create an HTTP request node and connect its completion signal.
    var httpRequest = new HttpRequest();
    AddChild(httpRequest);
    httpRequest.RequestCompleted += HttpRequestCompleted;

    // Perform the HTTP request. The URL below returns a PNG image as of writing.
    Error error = httpRequest.Request("https://placehold.co/512.png");
    if (error != Error.Ok)
    {
        GD.PushError("An error occurred in the HTTP request.");
    }
}

// Called when the HTTP request is completed.
private void HttpRequestCompleted(long result, long responseCode, string[] headers, byte[] body)
{
    if (result != (long)HttpRequest.Result.Success)
    {
        GD.PushError("Image couldn't be downloaded. Try a different image.");
    }
    var image = new Image();
    Error error = image.LoadPngFromBuffer(body);
    if (error != Error.Ok)
    {
        GD.PushError("Couldn't load the image.");
    }

    var texture = ImageTexture.CreateFromImage(image);

    // Display the image in a TextureRect node.
    var textureRect = new TextureRect();
    AddChild(textureRect);
    textureRect.Texture = texture;
}

Note: HTTPRequest nodes will automatically handle decompression of response bodies. An Accept-Encoding header will be automatically added to each of your requests, unless one is already specified. Any response with a Content-Encoding: gzip header will automatically be decompressed and delivered to you as uncompressed bytes.

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()

The duration to wait before a request times out, in seconds (independent of Engine.time_scale). If timeout is set to 0.0, the request will never time out.

For simple requests, such as communication with a REST API, it is recommended to set timeout to a value suitable for the server response time (commonly between 1.0 and 10.0). This will help prevent unwanted timeouts caused by variation in response times while still allowing the application to detect when a request has timed out. For larger requests such as file downloads, it is recommended to set timeout to 0.0, disabling the timeout functionality. This will help prevent large transfers from failing due to exceeding the timeout value.

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().