HTTPRequest

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

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

Описание

Узел с возможностью отправки HTTP-запросов. Использует HTTPClient для внутренних целей.

Может использоваться для выполнения HTTP-запросов, т. е. загрузки или выгрузки файлов или веб-контента через HTTP.

Предупреждение: Ознакомьтесь с примечаниями и предупреждениями по HTTPClient относительно ограничений, особенно касающихся безопасности TLS.

Примечание: При экспорте на Android убедитесь, что в настройках экспорта Android включено разрешение INTERNET перед экспортом проекта или использованием развертывания в один клик. В противном случае Android будет блокировать любые сетевые соединения.

Пример: Обратиться к REST API и вывести одно из возвращенных им полей:

func _ready():
    # Создайте узел HTTP-запроса и подключите его сигнал завершения.
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(self._http_request_completed)

    # Выполните GET-запрос. URL-адрес ниже возвращает JSON на момент написания статьи.
    var error = http_request.request("https://httpbin.org/get")
    if error != OK:
        push_error("An error occurred in the HTTP request.")

    # Выполните POST-запрос. URL-адрес ниже возвращает JSON на момент написания статьи.
    # Примечание: не отправляйте одновременные запросы с использованием одного узла HTTPRequest.
    # Фрагмент ниже предоставлен только для справки.
    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.")

# Вызывается после завершения HTTP-запроса.
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()

    # Выведет строку пользовательского агента, используемую узлом HTTPRequest (распознанную httpbin.org).
    print(response.headers["User-Agent"])

public override void _Ready()
{
    // Создайте узел HTTP-запроса и подключите его сигнал завершения.
    var httpRequest = new HttpRequest();
    AddChild(httpRequest);
    httpRequest.RequestCompleted += HttpRequestCompleted;

    // Выполните GET-запрос. URL-адрес ниже возвращает JSON на момент написания статьи.
    Error error = httpRequest.Request("https://httpbin.org/get");
    if (error != Error.Ok)
    {
        GD.PushError("An error occurred in the HTTP request.");
    }

    // Выполните POST-запрос. URL-адрес ниже возвращает JSON на момент написания статьи.
    // Примечание: не отправляйте одновременные запросы с использованием одного узла HTTPRequest.
    // Фрагмент ниже предоставлен только для справки.
    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.");
    }
}

// Вызывается после завершения HTTP-запроса.
private void HttpRequestCompleted(long result, long responseCode, string[] headers, byte[] body)
{
    var json = new Json();
    json.Parse(body.GetStringFromUtf8());
    var response = json.GetData().AsGodotDictionary();

    // Выведет строку пользовательского агента, используемую узлом HTTPRequest (распознанную httpbin.org).
    GD.Print((response["headers"].AsGodotDictionary())["User-Agent"]);
}

Пример: Загрузите изображение с помощью HTTPRequest и отобразите его:

func _ready():
    # Создайте узел HTTP-запроса и подключите его сигнал завершения.
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(self._http_request_completed)

    # Выполните HTTP-запрос. URL-адрес ниже возвращает изображение в формате PNG (на момент написания статьи).
    var error = http_request.request("https://placehold.co/512.png")
    if error != OK:
        push_error("An error occurred in the HTTP request.")

# Вызывается после завершения HTTP-запроса.
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)

    # Отобразите изображение в узле TextureRect.
    var texture_rect = TextureRect.new()
    add_child(texture_rect)
    texture_rect.texture = texture

public override void _Ready()
{
    // Создайте узел HTTP-запроса и подключите его сигнал завершения.
    var httpRequest = new HttpRequest();
    AddChild(httpRequest);
    httpRequest.RequestCompleted += HttpRequestCompleted;

    // Выполните HTTP-запрос. URL-адрес ниже возвращает изображение в формате PNG (на момент написания статьи).
    Error error = httpRequest.Request("https://placehold.co/512.png");
    if (error != Error.Ok)
    {
        GD.PushError("An error occurred in the HTTP request.");
    }
}

// Вызывается после завершения HTTP-запроса.
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);

    // Отобразите изображение в узле TextureRect.
    var textureRect = new TextureRect();
    AddChild(textureRect);
    textureRect.Texture = texture;
}

Примечание: Узлы HTTPRequest автоматически распаковывают тела ответов. Заголовок Accept-Encoding будет автоматически добавлен к каждому вашему запросу, если он ещё не указан. Любой ответ с заголовком Content-Encoding: gzip будет автоматически распакован и доставлен вам в виде несжатых байтов.

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

Свойства

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