You've already forked godot
mirror of
https://github.com/godotengine/godot.git
synced 2025-11-17 14:11:06 +00:00
32ddd4f4e0
We don't use that info for anything, and it generates unnecessary diffs
every time we bump the minor version (and CI failures if we forget to
sync some files from opt-in modules (mono, text_server_fb).
(cherry picked from commit 81064cc239)
216 lines
12 KiB
XML
216 lines
12 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="HTTPRequest" inherits="Node" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
|
|
<brief_description>
|
|
A node with the ability to send HTTP(S) requests.
|
|
</brief_description>
|
|
<description>
|
|
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.
|
|
[b]Warning:[/b] See the notes and warnings on [HTTPClient] for limitations, especially regarding SSL security.
|
|
[b]Example of contacting a REST API and printing one of its returned fields:[/b]
|
|
[codeblock]
|
|
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"])
|
|
[/codeblock]
|
|
[b]Example of loading and displaying an image using HTTPRequest:[/b]
|
|
[codeblock]
|
|
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
|
|
[/codeblock]
|
|
</description>
|
|
<tutorials>
|
|
<link>$DOCS_URL/tutorials/networking/http_request_class.html</link>
|
|
<link>$DOCS_URL/tutorials/networking/ssl_certificates.html</link>
|
|
</tutorials>
|
|
<methods>
|
|
<method name="cancel_request">
|
|
<return type="void" />
|
|
<description>
|
|
Cancels the current request.
|
|
</description>
|
|
</method>
|
|
<method name="get_body_size" qualifiers="const">
|
|
<return type="int" />
|
|
<description>
|
|
Returns the response body length.
|
|
[b]Note:[/b] Some Web servers may not send a body length. In this case, the value returned will be [code]-1[/code]. If using chunked transfer encoding, the body length will also be [code]-1[/code].
|
|
</description>
|
|
</method>
|
|
<method name="get_downloaded_bytes" qualifiers="const">
|
|
<return type="int" />
|
|
<description>
|
|
Returns the amount of bytes this HTTPRequest downloaded.
|
|
</description>
|
|
</method>
|
|
<method name="get_http_client_status" qualifiers="const">
|
|
<return type="int" enum="HTTPClient.Status" />
|
|
<description>
|
|
Returns the current status of the underlying [HTTPClient]. See [enum HTTPClient.Status].
|
|
</description>
|
|
</method>
|
|
<method name="request">
|
|
<return type="int" enum="Error" />
|
|
<argument index="0" name="url" type="String" />
|
|
<argument index="1" name="custom_headers" type="PoolStringArray" default="PoolStringArray( )" />
|
|
<argument index="2" name="ssl_validate_domain" type="bool" default="true" />
|
|
<argument index="3" name="method" type="int" enum="HTTPClient.Method" default="0" />
|
|
<argument index="4" name="request_data" type="String" default="""" />
|
|
<description>
|
|
Creates request on the underlying [HTTPClient]. If there is no configuration errors, it tries to connect using [method HTTPClient.connect_to_host] and passes parameters onto [method HTTPClient.request].
|
|
Returns [constant OK] if request is successfully created. (Does not imply that the server has responded), [constant ERR_UNCONFIGURED] if not in the tree, [constant ERR_BUSY] if still processing previous request, [constant ERR_INVALID_PARAMETER] if given string is not a valid URL format, or [constant ERR_CANT_CONNECT] if not using thread and the [HTTPClient] cannot connect to host.
|
|
[b]Note:[/b] When [code]method[/code] is [constant HTTPClient.METHOD_GET], the payload sent via [code]request_data[/code] might be ignored by the server or even cause the server to reject the request (check [url=https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.1]RFC 7231 section 4.3.1[/url] for more details). As a workaround, you can send data as a query string in the URL. See [method String.http_escape] for an example.
|
|
</description>
|
|
</method>
|
|
<method name="request_raw">
|
|
<return type="int" enum="Error" />
|
|
<argument index="0" name="url" type="String" />
|
|
<argument index="1" name="custom_headers" type="PoolStringArray" default="PoolStringArray( )" />
|
|
<argument index="2" name="ssl_validate_domain" type="bool" default="true" />
|
|
<argument index="3" name="method" type="int" enum="HTTPClient.Method" default="0" />
|
|
<argument index="4" name="request_data_raw" type="PoolByteArray" default="PoolByteArray( )" />
|
|
<description>
|
|
Creates request on the underlying [HTTPClient] using a raw array of bytes for the request body. If there is no configuration errors, it tries to connect using [method HTTPClient.connect_to_host] and passes parameters onto [method HTTPClient.request].
|
|
Returns [constant OK] if request is successfully created. (Does not imply that the server has responded), [constant ERR_UNCONFIGURED] if not in the tree, [constant ERR_BUSY] if still processing previous request, [constant ERR_INVALID_PARAMETER] if given string is not a valid URL format, or [constant ERR_CANT_CONNECT] if not using thread and the [HTTPClient] cannot connect to host.
|
|
</description>
|
|
</method>
|
|
<method name="set_http_proxy">
|
|
<return type="void" />
|
|
<argument index="0" name="host" type="String" />
|
|
<argument index="1" name="port" type="int" />
|
|
<description>
|
|
Sets the proxy server for HTTP requests.
|
|
The proxy server is unset if [code]host[/code] is empty or [code]port[/code] is -1.
|
|
</description>
|
|
</method>
|
|
<method name="set_https_proxy">
|
|
<return type="void" />
|
|
<argument index="0" name="host" type="String" />
|
|
<argument index="1" name="port" type="int" />
|
|
<description>
|
|
Sets the proxy server for HTTPS requests.
|
|
The proxy server is unset if [code]host[/code] is empty or [code]port[/code] is -1.
|
|
</description>
|
|
</method>
|
|
</methods>
|
|
<members>
|
|
<member name="body_size_limit" type="int" setter="set_body_size_limit" getter="get_body_size_limit" default="-1">
|
|
Maximum allowed size for response bodies ([code]-1[/code] 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.
|
|
</member>
|
|
<member name="download_chunk_size" type="int" setter="set_download_chunk_size" getter="get_download_chunk_size" default="65536">
|
|
The size of the buffer used and maximum bytes to read per iteration. See [member 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.
|
|
</member>
|
|
<member name="download_file" type="String" setter="set_download_file" getter="get_download_file" default="""">
|
|
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.
|
|
[b]Note:[/b] Folders are not automatically created when the file is created. If [member download_file] points to a subfolder, it's recommended to create the necessary folders beforehand using [method Directory.make_dir_recursive] to ensure the file can be written.
|
|
</member>
|
|
<member name="max_redirects" type="int" setter="set_max_redirects" getter="get_max_redirects" default="8">
|
|
Maximum number of allowed redirects. This is used to prevent endless redirect loops.
|
|
</member>
|
|
<member name="timeout" type="float" setter="set_timeout" getter="get_timeout" default="0.0">
|
|
If set to a value greater than [code]0.0[/code] before the request starts, the HTTP request will time out after [code]timeout[/code] seconds have passed and the request is not [i]completed[/i] yet. For small HTTP requests such as REST API usage, set [member timeout] to a value between [code]10.0[/code] and [code]30.0[/code] 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 [code]0.0[/code] to prevent the download from failing if it takes too much time.
|
|
</member>
|
|
<member name="use_threads" type="bool" setter="set_use_threads" getter="is_using_threads" default="false">
|
|
If [code]true[/code], multithreading is used to improve performance.
|
|
</member>
|
|
</members>
|
|
<signals>
|
|
<signal name="request_completed">
|
|
<argument index="0" name="result" type="int" />
|
|
<argument index="1" name="response_code" type="int" />
|
|
<argument index="2" name="headers" type="PoolStringArray" />
|
|
<argument index="3" name="body" type="PoolByteArray" />
|
|
<description>
|
|
Emitted when a request is completed.
|
|
</description>
|
|
</signal>
|
|
</signals>
|
|
<constants>
|
|
<constant name="RESULT_SUCCESS" value="0" enum="Result">
|
|
Request successful.
|
|
</constant>
|
|
<constant name="RESULT_CHUNKED_BODY_SIZE_MISMATCH" value="1" enum="Result">
|
|
</constant>
|
|
<constant name="RESULT_CANT_CONNECT" value="2" enum="Result">
|
|
Request failed while connecting.
|
|
</constant>
|
|
<constant name="RESULT_CANT_RESOLVE" value="3" enum="Result">
|
|
Request failed while resolving.
|
|
</constant>
|
|
<constant name="RESULT_CONNECTION_ERROR" value="4" enum="Result">
|
|
Request failed due to connection (read/write) error.
|
|
</constant>
|
|
<constant name="RESULT_SSL_HANDSHAKE_ERROR" value="5" enum="Result">
|
|
Request failed on SSL handshake.
|
|
</constant>
|
|
<constant name="RESULT_NO_RESPONSE" value="6" enum="Result">
|
|
Request does not have a response (yet).
|
|
</constant>
|
|
<constant name="RESULT_BODY_SIZE_LIMIT_EXCEEDED" value="7" enum="Result">
|
|
Request exceeded its maximum size limit, see [member body_size_limit].
|
|
</constant>
|
|
<constant name="RESULT_REQUEST_FAILED" value="8" enum="Result">
|
|
Request failed (currently unused).
|
|
</constant>
|
|
<constant name="RESULT_DOWNLOAD_FILE_CANT_OPEN" value="9" enum="Result">
|
|
HTTPRequest couldn't open the download file.
|
|
</constant>
|
|
<constant name="RESULT_DOWNLOAD_FILE_WRITE_ERROR" value="10" enum="Result">
|
|
HTTPRequest couldn't write to the download file.
|
|
</constant>
|
|
<constant name="RESULT_REDIRECT_LIMIT_REACHED" value="11" enum="Result">
|
|
Request reached its maximum redirect limit, see [member max_redirects].
|
|
</constant>
|
|
<constant name="RESULT_TIMEOUT" value="12" enum="Result">
|
|
</constant>
|
|
</constants>
|
|
</class>
|