:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/3.6/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/3.6/doc/classes/HTTPRequest.xml. .. _class_HTTPRequest: HTTPRequest =========== **Inherits:** :ref:`Node` **<** :ref:`Object` A node with the ability to send HTTP(S) requests. .. rst-class:: classref-introduction-group Description ----------- A node with the ability to send HTTP requests. Uses :ref:`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` for limitations, especially regarding SSL security. \ **Example of contacting a REST API and printing 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.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 = to_json({"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"]) \ **Example of loading and displaying an image using HTTPRequest:**\ :: 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): 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 .. rst-class:: classref-introduction-group Tutorials --------- - :doc:`../tutorials/networking/http_request_class` - :doc:`../tutorials/networking/ssl_certificates` .. rst-class:: classref-reftable-group Properties ---------- .. table:: :widths: auto +-----------------------------+----------------------------------------------------------------------------+-----------+ | :ref:`int` | :ref:`body_size_limit` | ``-1`` | +-----------------------------+----------------------------------------------------------------------------+-----------+ | :ref:`int` | :ref:`download_chunk_size` | ``65536`` | +-----------------------------+----------------------------------------------------------------------------+-----------+ | :ref:`String` | :ref:`download_file` | ``""`` | +-----------------------------+----------------------------------------------------------------------------+-----------+ | :ref:`int` | :ref:`max_redirects` | ``8`` | +-----------------------------+----------------------------------------------------------------------------+-----------+ | :ref:`float` | :ref:`timeout` | ``0.0`` | +-----------------------------+----------------------------------------------------------------------------+-----------+ | :ref:`bool` | :ref:`use_threads` | ``false`` | +-----------------------------+----------------------------------------------------------------------------+-----------+ .. rst-class:: classref-reftable-group Methods ------- .. table:: :widths: auto +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`cancel_request` **(** **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_body_size` **(** **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_downloaded_bytes` **(** **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Status` | :ref:`get_http_client_status` **(** **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`request` **(** :ref:`String` url, :ref:`PoolStringArray` custom_headers=PoolStringArray( ), :ref:`bool` ssl_validate_domain=true, :ref:`Method` method=0, :ref:`String` request_data="" **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`request_raw` **(** :ref:`String` url, :ref:`PoolStringArray` custom_headers=PoolStringArray( ), :ref:`bool` ssl_validate_domain=true, :ref:`Method` method=0, :ref:`PoolByteArray` request_data_raw=PoolByteArray( ) **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_http_proxy` **(** :ref:`String` host, :ref:`int` port **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_https_proxy` **(** :ref:`String` host, :ref:`int` port **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Signals ------- .. _class_HTTPRequest_signal_request_completed: .. rst-class:: classref-signal **request_completed** **(** :ref:`int` result, :ref:`int` response_code, :ref:`PoolStringArray` headers, :ref:`PoolByteArray` body **)** Emitted when a request is completed. .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_HTTPRequest_Result: .. rst-class:: classref-enumeration enum **Result**: .. _class_HTTPRequest_constant_RESULT_SUCCESS: .. rst-class:: classref-enumeration-constant :ref:`Result` **RESULT_SUCCESS** = ``0`` Request successful. .. _class_HTTPRequest_constant_RESULT_CHUNKED_BODY_SIZE_MISMATCH: .. rst-class:: classref-enumeration-constant :ref:`Result` **RESULT_CHUNKED_BODY_SIZE_MISMATCH** = ``1`` .. _class_HTTPRequest_constant_RESULT_CANT_CONNECT: .. rst-class:: classref-enumeration-constant :ref:`Result` **RESULT_CANT_CONNECT** = ``2`` Request failed while connecting. .. _class_HTTPRequest_constant_RESULT_CANT_RESOLVE: .. rst-class:: classref-enumeration-constant :ref:`Result` **RESULT_CANT_RESOLVE** = ``3`` Request failed while resolving. .. _class_HTTPRequest_constant_RESULT_CONNECTION_ERROR: .. rst-class:: classref-enumeration-constant :ref:`Result` **RESULT_CONNECTION_ERROR** = ``4`` Request failed due to connection (read/write) error. .. _class_HTTPRequest_constant_RESULT_SSL_HANDSHAKE_ERROR: .. rst-class:: classref-enumeration-constant :ref:`Result` **RESULT_SSL_HANDSHAKE_ERROR** = ``5`` Request failed on SSL handshake. .. _class_HTTPRequest_constant_RESULT_NO_RESPONSE: .. rst-class:: classref-enumeration-constant :ref:`Result` **RESULT_NO_RESPONSE** = ``6`` Request does not have a response (yet). .. _class_HTTPRequest_constant_RESULT_BODY_SIZE_LIMIT_EXCEEDED: .. rst-class:: classref-enumeration-constant :ref:`Result` **RESULT_BODY_SIZE_LIMIT_EXCEEDED** = ``7`` Request exceeded its maximum size limit, see :ref:`body_size_limit`. .. _class_HTTPRequest_constant_RESULT_REQUEST_FAILED: .. rst-class:: classref-enumeration-constant :ref:`Result` **RESULT_REQUEST_FAILED** = ``8`` Request failed (currently unused). .. _class_HTTPRequest_constant_RESULT_DOWNLOAD_FILE_CANT_OPEN: .. rst-class:: classref-enumeration-constant :ref:`Result` **RESULT_DOWNLOAD_FILE_CANT_OPEN** = ``9`` HTTPRequest couldn't open the download file. .. _class_HTTPRequest_constant_RESULT_DOWNLOAD_FILE_WRITE_ERROR: .. rst-class:: classref-enumeration-constant :ref:`Result` **RESULT_DOWNLOAD_FILE_WRITE_ERROR** = ``10`` HTTPRequest couldn't write to the download file. .. _class_HTTPRequest_constant_RESULT_REDIRECT_LIMIT_REACHED: .. rst-class:: classref-enumeration-constant :ref:`Result` **RESULT_REDIRECT_LIMIT_REACHED** = ``11`` Request reached its maximum redirect limit, see :ref:`max_redirects`. .. _class_HTTPRequest_constant_RESULT_TIMEOUT: .. rst-class:: classref-enumeration-constant :ref:`Result` **RESULT_TIMEOUT** = ``12`` .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_HTTPRequest_property_body_size_limit: .. rst-class:: classref-property :ref:`int` **body_size_limit** = ``-1`` .. rst-class:: classref-property-setget - void **set_body_size_limit** **(** :ref:`int` value **)** - :ref:`int` **get_body_size_limit** **(** **)** Maximum allowed size for response bodies (``-1`` means no limit). When only small files are expected, this can be used to prevent disallow receiving files that are too large, preventing potential denial of service attacks. .. rst-class:: classref-item-separator ---- .. _class_HTTPRequest_property_download_chunk_size: .. rst-class:: classref-property :ref:`int` **download_chunk_size** = ``65536`` .. rst-class:: classref-property-setget - void **set_download_chunk_size** **(** :ref:`int` value **)** - :ref:`int` **get_download_chunk_size** **(** **)** The size of the buffer used and maximum bytes to read per iteration. See :ref:`HTTPClient.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. .. rst-class:: classref-item-separator ---- .. _class_HTTPRequest_property_download_file: .. rst-class:: classref-property :ref:`String` **download_file** = ``""`` .. rst-class:: classref-property-setget - void **set_download_file** **(** :ref:`String` value **)** - :ref:`String` **get_download_file** **(** **)** The file to download into. If set to a non-empty string, the request output will be written to the file located at the path. If a file already exists at the specified location, it will be overwritten as soon as body data begins to be received. \ **Note:** Folders are not automatically created when the file is created. If :ref:`download_file` points to a subfolder, it's recommended to create the necessary folders beforehand using :ref:`Directory.make_dir_recursive` to ensure the file can be written. .. rst-class:: classref-item-separator ---- .. _class_HTTPRequest_property_max_redirects: .. rst-class:: classref-property :ref:`int` **max_redirects** = ``8`` .. rst-class:: classref-property-setget - void **set_max_redirects** **(** :ref:`int` value **)** - :ref:`int` **get_max_redirects** **(** **)** Maximum number of allowed redirects. This is used to prevent endless redirect loops. .. rst-class:: classref-item-separator ---- .. _class_HTTPRequest_property_timeout: .. rst-class:: classref-property :ref:`float` **timeout** = ``0.0`` .. rst-class:: classref-property-setget - void **set_timeout** **(** :ref:`float` value **)** - :ref:`float` **get_timeout** **(** **)** If set to a value greater than ``0.0`` before the request starts, the HTTP request will time out after ``timeout`` seconds have passed and the request is not *completed* yet. For small HTTP requests such as REST API usage, set :ref:`timeout` to a value between ``10.0`` and ``30.0`` to prevent the application from getting stuck if the request fails to get a response in a timely manner. For file downloads, leave this to ``0.0`` to prevent the download from failing if it takes too much time. .. rst-class:: classref-item-separator ---- .. _class_HTTPRequest_property_use_threads: .. rst-class:: classref-property :ref:`bool` **use_threads** = ``false`` .. rst-class:: classref-property-setget - void **set_use_threads** **(** :ref:`bool` value **)** - :ref:`bool` **is_using_threads** **(** **)** If ``true``, multithreading is used to improve performance. .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_HTTPRequest_method_cancel_request: .. rst-class:: classref-method void **cancel_request** **(** **)** Cancels the current request. .. rst-class:: classref-item-separator ---- .. _class_HTTPRequest_method_get_body_size: .. rst-class:: classref-method :ref:`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``. .. rst-class:: classref-item-separator ---- .. _class_HTTPRequest_method_get_downloaded_bytes: .. rst-class:: classref-method :ref:`int` **get_downloaded_bytes** **(** **)** |const| Returns the amount of bytes this HTTPRequest downloaded. .. rst-class:: classref-item-separator ---- .. _class_HTTPRequest_method_get_http_client_status: .. rst-class:: classref-method :ref:`Status` **get_http_client_status** **(** **)** |const| Returns the current status of the underlying :ref:`HTTPClient`. See :ref:`Status`. .. rst-class:: classref-item-separator ---- .. _class_HTTPRequest_method_request: .. rst-class:: classref-method :ref:`Error` **request** **(** :ref:`String` url, :ref:`PoolStringArray` custom_headers=PoolStringArray( ), :ref:`bool` ssl_validate_domain=true, :ref:`Method` method=0, :ref:`String` request_data="" **)** Creates request on the underlying :ref:`HTTPClient`. If there is no configuration errors, it tries to connect using :ref:`HTTPClient.connect_to_host` and passes parameters onto :ref:`HTTPClient.request`. Returns :ref:`@GlobalScope.OK` if request is successfully created. (Does not imply that the server has responded), :ref:`@GlobalScope.ERR_UNCONFIGURED` if not in the tree, :ref:`@GlobalScope.ERR_BUSY` if still processing previous request, :ref:`@GlobalScope.ERR_INVALID_PARAMETER` if given string is not a valid URL format, or :ref:`@GlobalScope.ERR_CANT_CONNECT` if not using thread and the :ref:`HTTPClient` cannot connect to host. \ **Note:** When ``method`` is :ref:`HTTPClient.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 `__ for more details). As a workaround, you can send data as a query string in the URL. See :ref:`String.http_escape` for an example. .. rst-class:: classref-item-separator ---- .. _class_HTTPRequest_method_request_raw: .. rst-class:: classref-method :ref:`Error` **request_raw** **(** :ref:`String` url, :ref:`PoolStringArray` custom_headers=PoolStringArray( ), :ref:`bool` ssl_validate_domain=true, :ref:`Method` method=0, :ref:`PoolByteArray` request_data_raw=PoolByteArray( ) **)** Creates request on the underlying :ref:`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` and passes parameters onto :ref:`HTTPClient.request`. Returns :ref:`@GlobalScope.OK` if request is successfully created. (Does not imply that the server has responded), :ref:`@GlobalScope.ERR_UNCONFIGURED` if not in the tree, :ref:`@GlobalScope.ERR_BUSY` if still processing previous request, :ref:`@GlobalScope.ERR_INVALID_PARAMETER` if given string is not a valid URL format, or :ref:`@GlobalScope.ERR_CANT_CONNECT` if not using thread and the :ref:`HTTPClient` cannot connect to host. .. rst-class:: classref-item-separator ---- .. _class_HTTPRequest_method_set_http_proxy: .. rst-class:: classref-method void **set_http_proxy** **(** :ref:`String` host, :ref:`int` port **)** Sets the proxy server for HTTP requests. The proxy server is unset if ``host`` is empty or ``port`` is -1. .. rst-class:: classref-item-separator ---- .. _class_HTTPRequest_method_set_https_proxy: .. rst-class:: classref-method void **set_https_proxy** **(** :ref:`String` host, :ref:`int` port **)** Sets the proxy server for HTTPS requests. The proxy server is unset if ``host`` is empty or ``port`` is -1. .. |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.)` .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`