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

Наследует: Node < Object

Узел с возможностью отправки HTTP(S)-запросов.

Описание

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.

Обучающие материалы

Свойства

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`

Методы

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)

Сигналы

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

Выдается после завершения запроса.

Перечисления

enum Result: 🔗

Result RESULT_SUCCESS = 0

Запрос успешен.

Result RESULT_CHUNKED_BODY_SIZE_MISMATCH = 1

Запрос не выполнен из-за несоответствия между ожидаемым и фактическим размером фрагментированного тела во время передачи. Возможные причины включают сетевые ошибки, неправильную конфигурацию сервера или проблемы с фрагментированным кодированием.

Result RESULT_CANT_CONNECT = 2

Запрос не удался при подключении.

Result RESULT_CANT_RESOLVE = 3

Запрос не удалось разрешить.

Result RESULT_CONNECTION_ERROR = 4

Запрос не выполнен из-за ошибки соединения (чтение/запись).

Result RESULT_TLS_HANDSHAKE_ERROR = 5

Запрос не выполнен при установлении связи TLS.

Result RESULT_NO_RESPONSE = 6

Запрос не получил ответа (пока что).

Result RESULT_BODY_SIZE_LIMIT_EXCEEDED = 7

Запрос превысил максимальный размер, см. body_size_limit.

Result RESULT_BODY_DECOMPRESS_FAILED = 8

Запрос не выполнен из-за ошибки при распаковке тела ответа. Возможные причины включают неподдерживаемый или неправильный формат сжатия, поврежденные данные или неполную передачу.

Result RESULT_REQUEST_FAILED = 9

Запрос не выполнен (в настоящее время не используется).

Result RESULT_DOWNLOAD_FILE_CANT_OPEN = 10

HTTPRequest не смог открыть загружаемый файл.

Result RESULT_DOWNLOAD_FILE_WRITE_ERROR = 11

HTTPRequest не смог выполнить запись в загружаемый файл.

Result RESULT_REDIRECT_LIMIT_REACHED = 12

Запрос достиг максимального предела перенаправления, см. max_redirects.

Result RESULT_TIMEOUT = 13

Запрос не выполнен из-за тайм-аута. Если вы ожидаете, что запросы будут выполняться долго, попробуйте увеличить значение timeout или установить его на 0.0, чтобы полностью убрать тайм-аут.

Описания свойств

bool accept_gzip = true 🔗

void set_accept_gzip(value: bool)
bool is_accepting_gzip()

Если true, этот заголовок будет добавлен к каждому запросу: Accept-Encoding: gzip, deflate, сообщая серверам, что сжимать тела ответов можно.

Любое тело ответа, объявляющее Content-Encoding либо gzip, либо deflate, будет автоматически распаковано, а несжатые байты будут доставлены через request_completed.

Если пользователь указал свой собственный заголовок Accept-Encoding, то заголовок не будет добавлен независимо от accept_gzip.

Если false, заголовок не будет добавлен, и распаковка тел ответов не будет выполнена. Необработанные байты тела ответа будут возвращены через request_completed.

int body_size_limit = -1 🔗

void set_body_size_limit(value: int)
int get_body_size_limit()

Максимально допустимый размер для тел ответов. Если тело ответа сжато, это будет использоваться как максимально допустимый размер для распакованного тела.

int download_chunk_size = 65536 🔗

void set_download_chunk_size(value: int)
int get_download_chunk_size()

Размер используемого буфера и максимальное количество байтов для чтения за одну итерацию. См. HTTPClient.read_chunk_size.

Установите меньшее значение (например, 4096 для 4 КиБ) при загрузке небольших файлов, чтобы уменьшить использование памяти за счет скорости загрузки.

String download_file = "" 🔗

void set_download_file(value: String)
String get_download_file()

Файл для загрузки. В него будет выведен любой полученный файл.

int max_redirects = 8 🔗

void set_max_redirects(value: int)
int get_max_redirects()

Максимальное количество разрешенных перенаправлений.

float timeout = 0.0 🔗

void set_timeout(value: float)
float get_timeout()

Длительность ожидания до истечения таймаута запроса в секундах (независимо от параметра Engine.time_scale). Если timeout установлено на 0.0, запрос никогда не истечет по таймауту.

Для простых запросов, таких как взаимодействие с REST API, рекомендуется установить timeout на значение, подходящее для времени ответа сервера (обычно от 1.0 до 10.0). Это поможет предотвратить нежелательные таймауты, вызванные колебаниями времени ответа, и при этом позволит приложению определять, когда запрос истек по таймауту. Для более крупных запросов, таких как загрузка файлов, рекомендуется установить timeout на 0.0, отключив функцию таймаута. Это поможет предотвратить сбои при больших передачах из-за превышения значения таймаута.

bool use_threads = false 🔗

void set_use_threads(value: bool)
bool is_using_threads()

Если true, для повышения производительности используется многопоточность.

Описания метода

void cancel_request() 🔗

Отменяет текущий запрос.

int get_body_size() const 🔗

Возвращает длину тела запроса.

Примечание: Некоторые веб-серверы могут не отправлять длину тела. В этом случае возвращаемое значение будет -1. При использовании кодирования передачи по частям длина тела также будет -1.

int get_downloaded_bytes() const 🔗

Возвращает количество байтов, загруженных по этому HTTP-запросу.

Status get_http_client_status() const 🔗

Возвращает текущий статус базового HTTPClient.

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

Создает запрос на базовом HTTPClient. Если ошибок конфигурации нет, он пытается подключиться с помощью HTTPClient.connect_to_host() и передает параметры в HTTPClient.request().

Возвращает @GlobalScope.OK, если запрос успешно создан. (Не подразумевает, что сервер ответил), @GlobalScope.ERR_UNCONFIGURED, если нет в дереве, @GlobalScope.ERR_BUSY, если все еще обрабатывается предыдущий запрос, @GlobalScope.ERR_INVALID_PARAMETER, если заданная строка не является допустимым форматом URL, или @GlobalScope.ERR_CANT_CONNECT, если поток не используется и HTTPClient не может подключиться к хосту.

Примечание: Когда method — HTTPClient.METHOD_GET, полезная нагрузка, отправленная через request_data, может быть проигнорирована сервером или даже привести к отклонению запроса сервером (подробнее см. в RFC 7231, раздел 4.3.1). В качестве обходного пути вы можете отправить данные в виде строки запроса в URL (см. пример в String.uri_encode()).

Примечание: Рекомендуется использовать транспортное шифрование (TLS) и избегать отправки конфиденциальной информации (например, учетных данных для входа) в параметрах URL HTTP GET. Рассмотрите возможность использования запросов HTTP POST или заголовков HTTP для такой информации.

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

Создает запрос на базовом HTTPClient, используя необработанный массив байтов для тела запроса. Если ошибок конфигурации нет, он пытается подключиться с помощью HTTPClient.connect_to_host() и передает параметры в HTTPClient.request().

Возвращает @GlobalScope.OK, если запрос успешно создан. (Не подразумевает, что сервер ответил), @GlobalScope.ERR_UNCONFIGURED, если нет в дереве, @GlobalScope.ERR_BUSY, если все еще обрабатывается предыдущий запрос, @GlobalScope.ERR_INVALID_PARAMETER, если заданная строка не является допустимым форматом URL, или @GlobalScope.ERR_CANT_CONNECT, если поток не используется и HTTPClient не может подключиться к хосту.

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

Устанавливает прокси-сервер для HTTP-запросов.

Прокси-сервер не установлен, если host пуст или port равен -1.

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

Устанавливает прокси-сервер для HTTPS-запросов.

Прокси-сервер не установлен, если host пуст или port равен -1.

void set_tls_options(client_options: TLSOptions) 🔗

Устанавливает TLSOptions, которые будут использоваться при подключении к HTTPS-серверу. См. TLSOptions.client().