godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-04 14:11:02 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
f6f6c1bf19b056c2fd289f5dda2dbf098a8cbe5c
godot-docs/classes/class_httprequest.rst
Rémi Verschelde f6f6c1bf19 classref: Sync with latest 4.0-dev
2021-10-06 11:19:07 +02:00

482 lines
25 KiB
ReStructuredText
Raw Blame History

:github_url: hide
.. Generated automatically by doc/tools/makerst.py in Godot's source tree.
.. DO NOT EDIT THIS FILE, but the HTTPRequest.xml source instead.
.. The source is found in doc/classes or modules/<name>/doc_classes.
.. _class_HTTPRequest:
HTTPRequest
===========
**Inherits:** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`
A node with the ability to send HTTP(S) requests.
Description
-----------
A node with the ability to send HTTP requests. Uses :ref:`HTTPClient<class_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 :ref:`HTTPClient<class_HTTPClient>` for limitations, especially regarding SSL 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 of contacting a REST API and printing one of its returned fields:**
.. tabs::
.. code-tab:: gdscript
func _ready():
# Create an HTTP request node and connect its completion signal.
var http_request = HTTPRequest.new()
add_child(http_request)
http_request.connect("request_completed", 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 = {"name": "Godette"}
error = http_request.request("https://httpbin.org/post", [], true, 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 response = parse_json(body.get_string_from_utf8())
# Will print the user agent string used by the HTTPRequest node (as recognized by httpbin.org).
print(response.headers["User-Agent"])
.. code-tab:: csharp
public override void _Ready()
{
// Create an HTTP request node and connect its completion signal.
var httpRequest = new HTTPRequest();
AddChild(httpRequest);
httpRequest.Connect("request_completed", this, nameof(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 = { "name", "Godette" };
// GDScript to_json is non existent, so we use JSON.Print() here.
error = httpRequest.Request("https://httpbin.org/post", null, true, HTTPClient.Method.Post, JSON.Print(body));
if (error != Error.Ok)
{
GD.PushError("An error occurred in the HTTP request.");
}
}
// Called when the HTTP request is completed.
private void HttpRequestCompleted(int result, int response_code, string[] headers, byte[] body)
{
// GDScript parse_json is non existent so we have to use JSON.parse, which has a slightly different syntax.
var response = JSON.Parse(body.GetStringFromUTF8()).Result as Godot.Collections.Dictionary;
// Will print the user agent string used by the HTTPRequest node (as recognized by httpbin.org).
GD.Print((response["headers"] as Godot.Collections.Dictionary)["User-Agent"]);
}
**Example of loading and displaying an image using HTTPRequest:**
.. tabs::
.. code-tab:: gdscript
func _ready():
# Create an HTTP request node and connect its completion signal.
var http_request = HTTPRequest.new()
add_child(http_request)
http_request.connect("request_completed", self, "_http_request_completed")
# Perform the HTTP request. The URL below returns a PNG image as of writing.
var error = http_request.request("https://via.placeholder.com/512")
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.new()
texture.create_from_image(image)
# Display the image in a TextureRect node.
var texture_rect = TextureRect.new()
add_child(texture_rect)
texture_rect.texture = texture
.. code-tab:: csharp
public override void _Ready()
{
// Create an HTTP request node and connect its completion signal.
var httpRequest = new HTTPRequest();
AddChild(httpRequest);
httpRequest.Connect("request_completed", this, nameof(HttpRequestCompleted));
// Perform the HTTP request. The URL below returns a PNG image as of writing.
Error error = httpRequest.Request("https://via.placeholder.com/512");
if (error != Error.Ok)
{
GD.PushError("An error occurred in the HTTP request.");
}
}
// Called when the HTTP request is completed.
private void HttpRequestCompleted(int result, int response_code, string[] headers, byte[] body)
{
if (result != (int)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 = new ImageTexture();
texture.CreateFromImage(image);
// Display the image in a TextureRect node.
var textureRect = new TextureRect();
AddChild(textureRect);
textureRect.Texture = texture;
}
**Gzipped response bodies**: HTTPRequest will automatically handle decompression of response bodies. A ``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.
Tutorials
---------
- :doc:`../tutorials/networking/http_request_class`
- :doc:`../tutorials/networking/ssl_certificates`
Properties
----------
+-----------------------------+----------------------------------------------------------------------------+-----------+
| :ref:`bool<class_bool>` | :ref:`accept_gzip<class_HTTPRequest_property_accept_gzip>` | ``true`` |
+-----------------------------+----------------------------------------------------------------------------+-----------+
| :ref:`int<class_int>` | :ref:`body_size_limit<class_HTTPRequest_property_body_size_limit>` | ``-1`` |
+-----------------------------+----------------------------------------------------------------------------+-----------+
| :ref:`int<class_int>` | :ref:`download_chunk_size<class_HTTPRequest_property_download_chunk_size>` | ``65536`` |
+-----------------------------+----------------------------------------------------------------------------+-----------+
| :ref:`String<class_String>` | :ref:`download_file<class_HTTPRequest_property_download_file>` | ``""`` |
+-----------------------------+----------------------------------------------------------------------------+-----------+
| :ref:`int<class_int>` | :ref:`max_redirects<class_HTTPRequest_property_max_redirects>` | ``8`` |
+-----------------------------+----------------------------------------------------------------------------+-----------+
| :ref:`int<class_int>` | :ref:`timeout<class_HTTPRequest_property_timeout>` | ``0`` |
+-----------------------------+----------------------------------------------------------------------------+-----------+
| :ref:`bool<class_bool>` | :ref:`use_threads<class_HTTPRequest_property_use_threads>` | ``false`` |
+-----------------------------+----------------------------------------------------------------------------+-----------+
Methods
-------
+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`cancel_request<class_HTTPRequest_method_cancel_request>` **(** **)** |
+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_body_size<class_HTTPRequest_method_get_body_size>` **(** **)** |const| |
+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_downloaded_bytes<class_HTTPRequest_method_get_downloaded_bytes>` **(** **)** |const| |
+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Status<enum_HTTPClient_Status>` | :ref:`get_http_client_status<class_HTTPRequest_method_get_http_client_status>` **(** **)** |const| |
+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`request<class_HTTPRequest_method_request>` **(** :ref:`String<class_String>` url, :ref:`PackedStringArray<class_PackedStringArray>` custom_headers=PackedStringArray(), :ref:`bool<class_bool>` ssl_validate_domain=true, :ref:`Method<enum_HTTPClient_Method>` method=0, :ref:`String<class_String>` request_data="" **)** |
+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`request_raw<class_HTTPRequest_method_request_raw>` **(** :ref:`String<class_String>` url, :ref:`PackedStringArray<class_PackedStringArray>` custom_headers=PackedStringArray(), :ref:`bool<class_bool>` ssl_validate_domain=true, :ref:`Method<enum_HTTPClient_Method>` method=0, :ref:`PackedByteArray<class_PackedByteArray>` request_data_raw=PackedByteArray() **)** |
+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Signals
-------
.. _class_HTTPRequest_signal_request_completed:
- **request_completed** **(** :ref:`int<class_int>` result, :ref:`int<class_int>` response_code, :ref:`PackedStringArray<class_PackedStringArray>` headers, :ref:`PackedByteArray<class_PackedByteArray>` body **)**
Emitted when a request is completed.
Enumerations
------------
.. _enum_HTTPRequest_Result:
.. _class_HTTPRequest_constant_RESULT_SUCCESS:
.. _class_HTTPRequest_constant_RESULT_CHUNKED_BODY_SIZE_MISMATCH:
.. _class_HTTPRequest_constant_RESULT_CANT_CONNECT:
.. _class_HTTPRequest_constant_RESULT_CANT_RESOLVE:
.. _class_HTTPRequest_constant_RESULT_CONNECTION_ERROR:
.. _class_HTTPRequest_constant_RESULT_SSL_HANDSHAKE_ERROR:
.. _class_HTTPRequest_constant_RESULT_NO_RESPONSE:
.. _class_HTTPRequest_constant_RESULT_BODY_SIZE_LIMIT_EXCEEDED:
.. _class_HTTPRequest_constant_RESULT_BODY_DECOMPRESS_FAILED:
.. _class_HTTPRequest_constant_RESULT_REQUEST_FAILED:
.. _class_HTTPRequest_constant_RESULT_DOWNLOAD_FILE_CANT_OPEN:
.. _class_HTTPRequest_constant_RESULT_DOWNLOAD_FILE_WRITE_ERROR:
.. _class_HTTPRequest_constant_RESULT_REDIRECT_LIMIT_REACHED:
.. _class_HTTPRequest_constant_RESULT_TIMEOUT:
enum **Result**:
- **RESULT_SUCCESS** = **0** --- Request successful.
- **RESULT_CHUNKED_BODY_SIZE_MISMATCH** = **1**
- **RESULT_CANT_CONNECT** = **2** --- Request failed while connecting.
- **RESULT_CANT_RESOLVE** = **3** --- Request failed while resolving.
- **RESULT_CONNECTION_ERROR** = **4** --- Request failed due to connection (read/write) error.
- **RESULT_SSL_HANDSHAKE_ERROR** = **5** --- Request failed on SSL handshake.
- **RESULT_NO_RESPONSE** = **6** --- Request does not have a response (yet).
- **RESULT_BODY_SIZE_LIMIT_EXCEEDED** = **7** --- Request exceeded its maximum size limit, see :ref:`body_size_limit<class_HTTPRequest_property_body_size_limit>`.
- **RESULT_BODY_DECOMPRESS_FAILED** = **8**
- **RESULT_REQUEST_FAILED** = **9** --- Request failed (currently unused).
- **RESULT_DOWNLOAD_FILE_CANT_OPEN** = **10** --- HTTPRequest couldn't open the download file.
- **RESULT_DOWNLOAD_FILE_WRITE_ERROR** = **11** --- HTTPRequest couldn't write to the download file.
- **RESULT_REDIRECT_LIMIT_REACHED** = **12** --- Request reached its maximum redirect limit, see :ref:`max_redirects<class_HTTPRequest_property_max_redirects>`.
- **RESULT_TIMEOUT** = **13**
Property Descriptions
---------------------
.. _class_HTTPRequest_property_accept_gzip:
- :ref:`bool<class_bool>` **accept_gzip**
+-----------+------------------------+
| *Default* | ``true`` |
+-----------+------------------------+
| *Setter* | set_accept_gzip(value) |
+-----------+------------------------+
| *Getter* | is_accepting_gzip() |
+-----------+------------------------+
If ``true``, this header will be added to each request: ``Accept-Encoding: gzip, deflate`` telling servers that it's okay to compress response bodies.
Any Response body declaring a ``Content-Encoding`` of either ``gzip`` or ``deflate`` will then be automatically decompressed, and the uncompressed bytes will be delivered via ``request_completed``.
If the user has specified their own ``Accept-Encoding`` header, then no header will be added regardless of ``accept_gzip``.
If ``false`` no header will be added, and no decompression will be performed on response bodies. The raw bytes of the response body will be returned via ``request_completed``.
----
.. _class_HTTPRequest_property_body_size_limit:
- :ref:`int<class_int>` **body_size_limit**
+-----------+----------------------------+
| *Default* | ``-1`` |
+-----------+----------------------------+
| *Setter* | set_body_size_limit(value) |
+-----------+----------------------------+
| *Getter* | get_body_size_limit() |
+-----------+----------------------------+
Maximum allowed size for response bodies. If the response body is compressed, this will be used as the maximum allowed size for the decompressed body.
----
.. _class_HTTPRequest_property_download_chunk_size:
- :ref:`int<class_int>` **download_chunk_size**
+-----------+--------------------------------+
| *Default* | ``65536`` |
+-----------+--------------------------------+
| *Setter* | set_download_chunk_size(value) |
+-----------+--------------------------------+
| *Getter* | get_download_chunk_size() |
+-----------+--------------------------------+
The size of the buffer used and maximum bytes to read per iteration. See :ref:`HTTPClient.read_chunk_size<class_HTTPClient_property_read_chunk_size>`.
Set this to a lower value (e.g. 4096 for 4 KiB) when downloading small files to decrease memory usage at the cost of download speeds.
----
.. _class_HTTPRequest_property_download_file:
- :ref:`String<class_String>` **download_file**
+-----------+--------------------------+
| *Default* | ``""`` |
+-----------+--------------------------+
| *Setter* | set_download_file(value) |
+-----------+--------------------------+
| *Getter* | get_download_file() |
+-----------+--------------------------+
The file to download into. Will output any received file into it.
----
.. _class_HTTPRequest_property_max_redirects:
- :ref:`int<class_int>` **max_redirects**
+-----------+--------------------------+
| *Default* | ``8`` |
+-----------+--------------------------+
| *Setter* | set_max_redirects(value) |
+-----------+--------------------------+
| *Getter* | get_max_redirects() |
+-----------+--------------------------+
Maximum number of allowed redirects.
----
.. _class_HTTPRequest_property_timeout:
- :ref:`int<class_int>` **timeout**
+-----------+--------------------+
| *Default* | ``0`` |
+-----------+--------------------+
| *Setter* | set_timeout(value) |
+-----------+--------------------+
| *Getter* | get_timeout() |
+-----------+--------------------+
----
.. _class_HTTPRequest_property_use_threads:
- :ref:`bool<class_bool>` **use_threads**
+-----------+------------------------+
| *Default* | ``false`` |
+-----------+------------------------+
| *Setter* | set_use_threads(value) |
+-----------+------------------------+
| *Getter* | is_using_threads() |
+-----------+------------------------+
If ``true``, multithreading is used to improve performance.
Method Descriptions
-------------------
.. _class_HTTPRequest_method_cancel_request:
- void **cancel_request** **(** **)**
Cancels the current request.
----
.. _class_HTTPRequest_method_get_body_size:
- :ref:`int<class_int>` **get_body_size** **(** **)** |const|
Returns the response body length.
**Note:** Some Web servers may not send a body length. In this case, the value returned will be ``-1``. If using chunked transfer encoding, the body length will also be ``-1``.
----
.. _class_HTTPRequest_method_get_downloaded_bytes:
- :ref:`int<class_int>` **get_downloaded_bytes** **(** **)** |const|
Returns the amount of bytes this HTTPRequest downloaded.
----
.. _class_HTTPRequest_method_get_http_client_status:
- :ref:`Status<enum_HTTPClient_Status>` **get_http_client_status** **(** **)** |const|
Returns the current status of the underlying :ref:`HTTPClient<class_HTTPClient>`. See :ref:`Status<enum_HTTPClient_Status>`.
----
.. _class_HTTPRequest_method_request:
- :ref:`Error<enum_@GlobalScope_Error>` **request** **(** :ref:`String<class_String>` url, :ref:`PackedStringArray<class_PackedStringArray>` custom_headers=PackedStringArray(), :ref:`bool<class_bool>` ssl_validate_domain=true, :ref:`Method<enum_HTTPClient_Method>` method=0, :ref:`String<class_String>` request_data="" **)**
Creates request on the underlying :ref:`HTTPClient<class_HTTPClient>`. If there is no configuration errors, it tries to connect using :ref:`HTTPClient.connect_to_host<class_HTTPClient_method_connect_to_host>` and passes parameters onto :ref:`HTTPClient.request<class_HTTPClient_method_request>`.
Returns :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` if request is successfully created. (Does not imply that the server has responded), :ref:`@GlobalScope.ERR_UNCONFIGURED<class_@GlobalScope_constant_ERR_UNCONFIGURED>` if not in the tree, :ref:`@GlobalScope.ERR_BUSY<class_@GlobalScope_constant_ERR_BUSY>` if still processing previous request, :ref:`@GlobalScope.ERR_INVALID_PARAMETER<class_@GlobalScope_constant_ERR_INVALID_PARAMETER>` if given string is not a valid URL format, or :ref:`@GlobalScope.ERR_CANT_CONNECT<class_@GlobalScope_constant_ERR_CANT_CONNECT>` if not using thread and the :ref:`HTTPClient<class_HTTPClient>` cannot connect to host.
**Note:** When ``method`` is :ref:`HTTPClient.METHOD_GET<class_HTTPClient_constant_METHOD_GET>`, the payload sent via ``request_data`` might be ignored by the server or even cause the server to reject the request (check `RFC 7231 section 4.3.1 <https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.1>`__ for more details). As a workaround, you can send data as a query string in the URL (see :ref:`String.uri_encode<class_String_method_uri_encode>` for an example).
**Note:** It's recommended to use transport encryption (SSL/TLS) and to avoid sending sensitive information (such as login credentials) in HTTP GET URL parameters. Consider using HTTP POST requests or HTTP headers for such information instead.
----
.. _class_HTTPRequest_method_request_raw:
- :ref:`Error<enum_@GlobalScope_Error>` **request_raw** **(** :ref:`String<class_String>` url, :ref:`PackedStringArray<class_PackedStringArray>` custom_headers=PackedStringArray(), :ref:`bool<class_bool>` ssl_validate_domain=true, :ref:`Method<enum_HTTPClient_Method>` method=0, :ref:`PackedByteArray<class_PackedByteArray>` request_data_raw=PackedByteArray() **)**
Creates request on the underlying :ref:`HTTPClient<class_HTTPClient>` using a raw array of bytes for the request body. If there is no configuration errors, it tries to connect using :ref:`HTTPClient.connect_to_host<class_HTTPClient_method_connect_to_host>` and passes parameters onto :ref:`HTTPClient.request<class_HTTPClient_method_request>`.
Returns :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` if request is successfully created. (Does not imply that the server has responded), :ref:`@GlobalScope.ERR_UNCONFIGURED<class_@GlobalScope_constant_ERR_UNCONFIGURED>` if not in the tree, :ref:`@GlobalScope.ERR_BUSY<class_@GlobalScope_constant_ERR_BUSY>` if still processing previous request, :ref:`@GlobalScope.ERR_INVALID_PARAMETER<class_@GlobalScope_constant_ERR_INVALID_PARAMETER>` if given string is not a valid URL format, or :ref:`@GlobalScope.ERR_CANT_CONNECT<class_@GlobalScope_constant_ERR_CANT_CONNECT>` if not using thread and the :ref:`HTTPClient<class_HTTPClient>` cannot connect to host.
.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`
Reference in New Issue View Git Blame Copy Permalink