HTTPRequest

Успадковує: Node < Object

Вузол із можливістю надсилання запитів HTTP(S).

Опис

Вузол з можливістю надсилання HTTP-запитів. Використовує HTTPClient внутрішньо.

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

Попередження: Див. примітки та попередження щодо HTTPClient щодо обмежень, особливо щодо безпеки TLS.

Примітка: Під час експорту в Android переконайтеся, що ви ввімкнули дозвіл INTERNET у попередньому налаштуванні експорту Android, перш ніж експортувати проект або використовувати розгортання одним клацанням миші. В іншому випадку 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("У HTTP-запиті сталася помилка.")

    # Виконайте 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("У HTTP-запиті сталася помилка.")

# Викликається, коли 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("У HTTP-запиті сталася помилка.");
    }

    // Виконайте 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("Сталася помилка в HTTP-запиті.");
    }
}

// Викликається після завершення 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("Сталася помилка в HTTP-запиті.")

# Викликається, коли HTTP-запит завершено.
func _http_request_completed(result, response_code, headers, body):
    if result != HTTPRequest.RESULT_SUCCESS:
        push_error("Не вдалося завантажити зображення. Спробуйте інше зображення.")

    var image = Image.new()
    var error = image.load_png_from_buffer(body)
    if error != OK:
        push_error("Не вдалося завантажити зображення.")

    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("Сталася помилка в HTTP-запиті.");
    }
}

// Викликається після завершення HTTP-запиту.
private void HttpRequestCompleted(long result, long responseCode, string[] headers, byte[] body)
{
    if (result != (long)HttpRequest.Result.Success)
    {
        GD.PushError("Не вдалося завантажити зображення. Спробуйте інше зображення..");
    }
    var image = new Image();
    Error error = image.LoadPngFromBuffer(body);
    if (error != Error.Ok)
    {
        GD.PushError("Не вдалося завантажити зображення.");
    }

    var texture = ImageTexture.CreateFromImage(image);

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

Будь-який корпус відгуку, декларація Контент-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()

Тривалість, щоб чекати в секундах до часу запиту. 0.0 Для простих запитів, таких як комунікація з REST API, рекомендується timeout встановити значення, придатне для часу реагування сервера (наприклад, між 1.0 та 10.0. Це допоможе уникнути небажаних часів, викликаних варіацією в часі реагування сервера, але все ще дозволяє програмі виявити, коли запит виповнилося. Для більших запитів, таких як завантаження файлів, пропонується пам'ятний час, щоб 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().