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

Длительность ожидания в секундах до истечения времени ожидания запроса. Если 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().