HTTPRequest

Hereda: Node < Object

Un nodo con la capacidad de enviar peticiones HTTP(S).

Descripción

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.new().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 = 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("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.

Tutoriales

Propiedades

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étodos

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)

Señales

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

Emitida cuando se completa una solicitud.

Enumeraciones

enum Result: 🔗

Result RESULT_SUCCESS = 0

Solicitud con éxito.

Result RESULT_CHUNKED_BODY_SIZE_MISMATCH = 1

La solicitud falló debido a una discrepancia entre el tamaño esperado y el tamaño real del cuerpo fragmentado durante la transferencia. Las posibles causas incluyen errores de red, una mala configuración del servidor o problemas con la codificación fragmentada.

Result RESULT_CANT_CONNECT = 2

La solicitud falló mientras se conectaba.

Result RESULT_CANT_RESOLVE = 3

La solicitud falló al resolverse.

Result RESULT_CONNECTION_ERROR = 4

La solicitud falló debido a un error de conexión (lectura/escritura).

Result RESULT_TLS_HANDSHAKE_ERROR = 5

La solicitud falló en el establecimiento de comunicación TLS.

Result RESULT_NO_RESPONSE = 6

La solicitud no tiene respuesta (todavía).

Result RESULT_BODY_SIZE_LIMIT_EXCEEDED = 7

La solicitud excedió su límite de tamaño máximo, ver body_size_limit.

Result RESULT_BODY_DECOMPRESS_FAILED = 8

La solicitud falló debido a un error al descomprimir el cuerpo de la respuesta. Las posibles causas incluyen un formato de compresión no compatible o incorrecto, datos dañados o una transferencia incompleta.

Result RESULT_REQUEST_FAILED = 9

Solicitud fallida (actualmente no utilizada).

Result RESULT_DOWNLOAD_FILE_CANT_OPEN = 10

HTTPRequest no pudo abrir el archivo descargado.

Result RESULT_DOWNLOAD_FILE_WRITE_ERROR = 11

HTTPRequest no pudo escribir el archivo descargado.

Result RESULT_REDIRECT_LIMIT_REACHED = 12

La solicitud alcanzó su límite máximo de redireccionamiento, ver max_redirects.

Result RESULT_TIMEOUT = 13

La solicitud falló debido a un tiempo de espera excedido. Si esperas que las solicitudes tarden mucho tiempo, intenta aumentar el valor de timeout o establecerlo en 0.0 para eliminar el tiempo de espera por completo.

Descripciones de Propiedades

bool accept_gzip = true 🔗

void set_accept_gzip(value: bool)
bool is_accepting_gzip()

If true, this header will be added to each request: Accept-Encoding: gzip, deflate telling servers that it's okay to compress response bodies.

Any Response body declaring a Content-Encoding of either gzip or deflate will then be automatically decompressed, and the uncompressed bytes will be delivered via request_completed.

If the user has specified their own Accept-Encoding header, then no header will be added regardless of accept_gzip.

If false no header will be added, and no decompression will be performed on response bodies. The raw bytes of the response body will be returned via request_completed.

int body_size_limit = -1 🔗

void set_body_size_limit(value: int)
int get_body_size_limit()

Tamaño máximo permitido para los cuerpos de las respuestas. Si el cuerpo de la respuesta está comprimido, esto se usará como el tamaño máximo permitido para el cuerpo descomprimido.

int download_chunk_size = 65536 🔗

void set_download_chunk_size(value: int)
int get_download_chunk_size()

The size of the buffer used and maximum bytes to read per iteration. See HTTPClient.read_chunk_size.

Set this to a lower value (e.g. 4096 for 4 KiB) when downloading small files to decrease memory usage at the cost of download speeds.

String download_file = "" 🔗

void set_download_file(value: String)
String get_download_file()

The file to download into. Will output any received file into it.

int max_redirects = 8 🔗

void set_max_redirects(value: int)
int get_max_redirects()

Maximum number of allowed redirects.

float timeout = 0.0 🔗

void set_timeout(value: float)
float get_timeout()

The duration to wait in seconds before a request times out. If timeout is set to 0.0 then the request will never time out. For simple requests, such as communication with a REST API, it is recommended that timeout is set to a value suitable for the server response time (e.g. between 1.0 and 10.0). This will help prevent unwanted timeouts caused by variation in server response times while still allowing the application to detect when a request has timed out. For larger requests such as file downloads it is suggested the timeout be set to 0.0, disabling the timeout functionality. This will help to 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 es true, se utiliza el multihilo para mejorar el rendimiento.

Descripciones de Métodos

void cancel_request() 🔗

Cancela la solicitud actual.

int get_body_size() const 🔗

Devuelve la longitud del cuerpo de respuesta.

Nota: Algunos servidores web pueden no enviar la longitud del cuerpo. En este caso, el valor devuelto será -1. Si se utiliza la codificación de transferencia de trozos, la longitud del cuerpo también será -1.

int get_downloaded_bytes() const 🔗

Devuelve el número de bytes que esta HTTPRequest ha descargado.

Status get_http_client_status() const 🔗

Devuelve el estado actual del HTTPClient subyacente.

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

Creates request on the underlying HTTPClient. If there is no configuration errors, it tries to connect using HTTPClient.connect_to_host() and passes parameters onto HTTPClient.request().

Returns @GlobalScope.OK if request is successfully created. (Does not imply that the server has responded), @GlobalScope.ERR_UNCONFIGURED if not in the tree, @GlobalScope.ERR_BUSY if still processing previous request, @GlobalScope.ERR_INVALID_PARAMETER if given string is not a valid URL format, or @GlobalScope.ERR_CANT_CONNECT if not using thread and the HTTPClient cannot connect to host.

Note: When method is HTTPClient.METHOD_GET, the payload sent via request_data might be ignored by the server or even cause the server to reject the request (check RFC 7231 section 4.3.1 for more details). As a workaround, you can send data as a query string in the URL (see String.uri_encode() for an example).

Note: It's recommended to use transport encryption (TLS) and to avoid sending sensitive information (such as login credentials) in HTTP GET URL parameters. Consider using HTTP POST requests or HTTP headers for such information instead.

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

Creates request on the underlying HTTPClient using a raw array of bytes for the request body. If there is no configuration errors, it tries to connect using HTTPClient.connect_to_host() and passes parameters onto HTTPClient.request().

Returns @GlobalScope.OK if request is successfully created. (Does not imply that the server has responded), @GlobalScope.ERR_UNCONFIGURED if not in the tree, @GlobalScope.ERR_BUSY if still processing previous request, @GlobalScope.ERR_INVALID_PARAMETER if given string is not a valid URL format, or @GlobalScope.ERR_CANT_CONNECT if not using thread and the HTTPClient cannot connect to host.

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

Sets the proxy server for HTTP requests.

The proxy server is unset if host is empty or port is -1.

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

Sets the proxy server for HTTPS requests.

The proxy server is unset if host is empty or port is -1.

void set_tls_options(client_options: TLSOptions) 🔗

Establece las TLSOptions que se usarán al conectarse a un servidor HTTPS. Véase TLSOptions.client().