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

Eredita: Node < Object

Un nodo con la capacità di inviare richieste HTTP(S).

Descrizione

Un nodo capace di inviare richieste HTTP. Utilizza HTTPClient internamente.

Può essere utilizzato per effettuare richieste HTTP, ovvero scaricare o caricare file o contenuti Web tramite HTTP.

Attenzione: Consulta le note e gli avvertimenti su HTTPClient per le limitazioni, in particolare per quanto riguarda la sicurezza TLS.

Nota: Quando si esporta su Android, assicurarsi di abilitare l'autorizzazione INTERNET nella preimpostazione d'esportazione Android prima di esportare il progetto o di utilizzare la distribuzione con un clic. Altrimenti, qualsiasi tipo di comunicazione di rete sarà bloccata da Android.

Esempio: Contatta un'API REST e stampa uno dei sui campi restituiti:

func _ready():
    # Crea un nodo di richiesta HTTP e collega il suo segnale di completamento.
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(self._http_request_completed)

    # Effettua una richiesta GET. L'URL sottostante restituisce JSON al momento.
    var error = http_request.request("https://placehold.co/512.png")
    if error != OK:
        push_error("An error occurred in the HTTP request.")

    # Effettua una richiesta POST. L'URL sottostante restituisce JSON al momento.
    # Nota: non effettuare richieste simultanee utilizzando un singolo nodo HTTPRequest.
    # Il pezzo di codice sottostante è fornito solo per riferimento.
    var body = JSON.stringify({"name": "Godette"})
    error = http_request.request("https://httpbin.org/post", [], HTTPClient.METHOD_POST, body)
    if error != OK:
        push_error("Si è verificato un errore nella richiesta HTTP.")

# Chiamato quando la richiesta HTTP è completata.
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()

    # Stamperà la stringa dell'agente utente utilizzata dal nodo HTTPRequest (come riconosciuto da httpbin.org).
    print(response.headers["User-Agent"])

public override void _Ready()
{
    // Crea un nodo di richiesta HTTP e collega il suo segnale di completamento.
    var httpRequest = new HttpRequest();
    AddChild(httpRequest);
    httpRequest.RequestCompleted += HttpRequestCompleted;

    // Effettua una richiesta GET. L'URL sottostante restituisce JSON al momento.
    Error error = httpRequest.Request("https://placehold.co/512.png");
    if (error != Error.Ok)
    {
        GD.PushError("Si è verificato un errore nella richiesta HTTP.");
    }

    // Effettua una richiesta POST. L'URL sottostante restituisce JSON al momento.
    // Nota: non effettuare richieste simultanee utilizzando un singolo nodo HTTPRequest.
    // Il pezzo di codice sottostante è fornito solo per riferimento.
    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.");
    }
}

// Chiamato quando la richiesta HTTP è completata.
private void HttpRequestCompleted(long result, long responseCode, string[] headers, byte[] body)
{
    var json = new Json();
    json.Parse(body.GetStringFromUtf8());
    var response = json.GetData().AsGodotDictionary();

    // Stamperà la stringa dell'agente utente utilizzata dal nodo HTTPRequest (come riconosciuto da httpbin.org).
    GD.Print((response["headers"].AsGodotDictionary())["User-Agent"]);
}

Esempio: Carica e visualizza un'immagine tramite HTTPRequest:

func _ready():
    # Crea un nodo di richiesta HTTP e collega il suo segnale di completamento.
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(self._http_request_completed)

    # Effettua la richiesta HTTP. L'URL sottostante restituisce un'immagine PNG al momento.
    var error = http_request.request("https://via.placeholder.com/512")
    if error != OK:
        push_error("Si è verificato un errore nella richiesta HTTP.")

# Chiamato quando la richiesta HTTP è completata.
func _http_request_completed(result, response_code, headers, body):
    if result != HTTPRequest.RESULT_SUCCESS:
        push_error("Impossibile scaricare l'immagine. Prova un'immagine diversa.")

    var image = Image.new()
    var error = image.load_png_from_buffer(body)
    if error != OK:
        push_error("Impossibile caricare l'immagine.")

    var texture = ImageTexture.create_from_image(image)

    # Visualizza l'immagine in un nodo TextureRect.
    var texture_rect = TextureRect.new()
    add_child(texture_rect)
    texture_rect.texture = texture

public override void _Ready()
{
    // Crea un nodo di richiesta HTTP e collega il suo segnale di completamento.
    var httpRequest = new HttpRequest();
    AddChild(httpRequest);
    httpRequest.RequestCompleted += HttpRequestCompleted;

    // Effettua la richiesta HTTP. L'URL sottostante restituisce un'immagine PNG al momento.
    Error error = httpRequest.Request("https://via.placeholder.com/512");
    if (error != Error.Ok)
    {
        GD.PushError("Si è verificato un errore nella richiesta HTTP.");
    }
}

// Chiamato quando la richiesta HTTP è completata.
private void HttpRequestCompleted(long result, long responseCode, string[] headers, byte[] body)
{
    if (result != (long)HttpRequest.Result.Success)
    {
        GD.PushError("Impossibile scaricare l'immagine. Prova un'immagine diversa.");
    }
    var image = new Image();
    Error error = image.LoadPngFromBuffer(body);
    if (error != Error.Ok)
    {
        GD.PushError("Impossibile caricare l'immagine.");
    }

    var texture = ImageTexture.CreateFromImage(image);

    // Visualizza l'immagine in un nodo TextureRect.
    var textureRect = new TextureRect();
    AddChild(textureRect);
    textureRect.Texture = texture;
}

Nota: I nodi HTTPRequest gestiranno automaticamente la decompressione dei corpi delle risposte. Un'intestazione Accept-Encoding sarà aggiunta automaticamente a ciascuna delle tue richieste, a meno che non ne sia già stata specificata una. Qualsiasi risposta con un'intestazione Content-Encoding: gzip sarà automaticamente decompressa e consegnata come byte non compressi.

Tutorial

Proprietà

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`

Metodi

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)

Segnali

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

Emesso quando una richiesta è completata.

Enumerazioni

enum Result: 🔗

Result RESULT_SUCCESS = 0

Richiesta riuscita.

Result RESULT_CHUNKED_BODY_SIZE_MISMATCH = 1

Richiesta non riuscita a causa di una mancata corrispondenza tra la dimensione del corpo in blocchi prevista e quella effettiva durante il trasferimento. Le possibili cause includono errori di rete, configurazione errata del server o problemi con la codifica in blocchi.

Result RESULT_CANT_CONNECT = 2

Richiesta fallita durante la connessione.

Result RESULT_CANT_RESOLVE = 3

Richiesta fallita durante la risoluzione.

Result RESULT_CONNECTION_ERROR = 4

Richiesta fallita a causa di un errore di connessione (lettura/scrittura).

Result RESULT_TLS_HANDSHAKE_ERROR = 5

Richiesta fallita durante l'handshake TLS.

Result RESULT_NO_RESPONSE = 6

La richiesta non ha (ancora) una risposta.

Result RESULT_BODY_SIZE_LIMIT_EXCEEDED = 7

La richiesta ha superato il limite massimo di dimensione, vedi body_size_limit.

Result RESULT_BODY_DECOMPRESS_FAILED = 8

Richiesta non riuscita a causa di un errore durante la decompressione del corpo della risposta. Le possibili cause includono un formato di compressione non supportato o non corretto, dati danneggiati o trasferimento incompleto.

Result RESULT_REQUEST_FAILED = 9

Richiesta fallita (attualmente inutilizzata).

Result RESULT_DOWNLOAD_FILE_CANT_OPEN = 10

HTTPRequest non è riuscito ad aprire il file scaricato.

Result RESULT_DOWNLOAD_FILE_WRITE_ERROR = 11

HTTPRequest non è riuscito a scrivere sul file scaricato.

Result RESULT_REDIRECT_LIMIT_REACHED = 12

La richiesta ha raggiunto il limite massimo di reindirizzamenti, vedi max_redirects.

Result RESULT_TIMEOUT = 13

Richiesta non riuscita a causa di un timeout. Se prevedi che le richieste impiegheranno molto tempo, prova ad aumentare il valore di timeout o a impostarlo su 0.0 per rimuovere completamente il timeout.

Descrizioni delle proprietà

bool accept_gzip = true 🔗

void set_accept_gzip(value: bool)
bool is_accepting_gzip()

Se true, questa intestazione sarà aggiunta a ogni richiesta: Accept-Encoding: gzip, deflate la quale indica ai server che è possibile comprimere i corpi delle risposte.

Qualsiasi corpo della risposta che dichiara un Content-Encoding di gzip o deflate sarà automaticamente decompresso e i byte non compressi saranno consegnati tramite request_completed.

Se l'utente ha specificato la propria intestazione Accept-Encoding, nessuna intestazione sarà aggiunta indipendentemente da accept_gzip.

Se false nessuna intestazione sarà aggiunta e nessuna decompressione sarà effettuata sui corpi delle risposte. I byte grezzi del corpo della risposta saranno restituiti tramite request_completed.

int body_size_limit = -1 🔗

void set_body_size_limit(value: int)
int get_body_size_limit()

Dimensione massima consentita per i corpi delle risposte. Se il corpo della risposta è compresso, ciò sarà utilizzato come dimensione massima consentita per il corpo decompresso.

int download_chunk_size = 65536 🔗

void set_download_chunk_size(value: int)
int get_download_chunk_size()

La dimensione del buffer utilizzato e il numero massimo di byte da leggere per ogni iterazione. Vedi HTTPClient.read_chunk_size.

Imposta questo su un valore inferiore (ad esempio 4096 per 4 KiB) quando si scaricano piccoli file per ridurre l'utilizzo di memoria a scapito della velocità di download.

String download_file = "" 🔗

void set_download_file(value: String)
String get_download_file()

Il file in cui scaricare. Invierà qualsiasi file ricevuto in esso.

int max_redirects = 8 🔗

void set_max_redirects(value: int)
int get_max_redirects()

Numero massimo di reindirizzamenti consentiti.

float timeout = 0.0 🔗

void set_timeout(value: float)
float get_timeout()

La durata di attesa in secondi prima che una richiesta scada, in secondi (indipendente da Engine.time_scale. Se timeout è impostato su 0.0, la richiesta non scadrà mai.

Per richieste semplici, come la comunicazione con un'API REST, si consiglia di impostare timeout su un valore adatto al tempo di risposta del server (ad esempio tra 1.0 e 10.0). Ciò contribuirà a prevenire timeout indesiderati causati da variazioni nei tempi di risposta del server, consentendo comunque all'applicazione di rilevare quando una richiesta è scaduta. Per richieste più grandi, come i download di file, si consiglia di impostare timeout su 0.0, disabilitando la funzionalità di timeout. Ciò aiuterà a impedire che i trasferimenti grandi falliscano a causa del superamento del valore di timeout.

bool use_threads = false 🔗

void set_use_threads(value: bool)
bool is_using_threads()

Se true, il multithreading è utilizzato per migliorare le prestazioni.

Descrizioni dei metodi

void cancel_request() 🔗

Annulla la richiesta in corso.

int get_body_size() const 🔗

Restituisce la lunghezza del corpo della risposta.

Nota: Alcuni server Web potrebbero non inviare una lunghezza del corpo. In questo caso, il valore restituito sarà -1. Anche se si utilizza la codifica di trasferimento in blocchi, la lunghezza del corpo sarà -1.

int get_downloaded_bytes() const 🔗

Restituisce il numero di byte scaricati da questa HTTPRequest.

Status get_http_client_status() const 🔗

Restituisce lo stato attuale del HTTPClient sottostante.

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

Crea una richiesta sul HTTPClient sottostante. Se non ci sono errori di configurazione, prova a connettersi tramite HTTPClient.connect_to_host() e passa i parametri a HTTPClient.request().

Restituisce @GlobalScope.OK se la richiesta è stata creata correttamente. (Non significa che il server abbia risposto), @GlobalScope.ERR_UNCONFIGURED se non è nell'albero, @GlobalScope.ERR_BUSY se sta ancora elaborando la richiesta precedente, @GlobalScope.ERR_INVALID_PARAMETER se la stringa fornita non è un formato URL valido o @GlobalScope.ERR_CANT_CONNECT se non sta usando un thread e HTTPClient non riesce a connettersi all'host.

Nota: Quando method è HTTPClient.METHOD_GET, il payload inviato tramite request_data potrebbe essere ignorato dal server o addirittura causare la richiesta a essere rifiutata dal server (controlla RFC 7231 sezione 4.3.1 per maggiori dettagli). Come alternativa, è possibile inviare i dati come stringa di richiesta nell'URL (vedi String.uri_encode() per un esempio).

Nota: Si consiglia di utilizzare la crittografia di trasporto (TLS) ed evitare di inviare informazioni sensibili (come le credenziali di accesso) nei parametri URL HTTP GET. Considera di utilizzare richieste HTTP POST o intestazioni HTTP per tali informazioni.

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

Crea una richiesta sul sottostante HTTPClient utilizzando un array grezzo di byte per il corpo della richiesta. Se non ci sono errori di configurazione, prova a connettersi tramite HTTPClient.connect_to_host() e passa i parametri a HTTPClient.request().

Restituisce @GlobalScope.OK se la richiesta è stata creata correttamente. (Non significa che il server abbia risposto), @GlobalScope.ERR_UNCONFIGURED se non è nell'albero, @GlobalScope.ERR_BUSY se sta ancora elaborando la richiesta precedente, @GlobalScope.ERR_INVALID_PARAMETER se la stringa fornita non è un formato URL valido o @GlobalScope.ERR_CANT_CONNECT se non utilizza un thread e HTTPClient non riesce a connettersi all'host.

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

Imposta il server proxy per le richieste HTTP.

Il server proxy non è impostato se host è vuoto o port è -1.

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

Imposta il server proxy per le richieste HTTPS.

Il server proxy non è impostato se host è vuoto o port è -1.

void set_tls_options(client_options: TLSOptions) 🔗

Imposta le TLSOptions da utilizzare quando ci si connette a un server HTTPS. Vedi TLSOptions.client().