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 розповідаючи сервери, які вона буде одержувати до органів зворотного зв'язку.

Будь-який корпус відгуку, декларація Контент-Encoding або gzip або deflate буде автоматично декомпресовано, а несупресовані байти будуть доставлені через визначний запит_повний.

Якщо користувач заданий самостійно 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 KiB) при завантаженні невеликих файлів для зменшення використання пам'яті за вартістю швидкості завантаження.

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, відправлений через [param запиту_data може ігноруватися сервером або навіть викликати сервер, щоб відхилити запит (check RFC 7231 розділ 4.3.1 для отримання більш детально інформації. Як працює, ви можете надсилати дані як рядок запиту у URL (див. String.uri_encode() на прикладі).

Note: Рекомендується використовувати транспортне шифрування (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().