312 lines
16 KiB
XML
312 lines
16 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="HTTPRequest" inherits="Node" version="4.0" 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]Note:[/b] When exporting to Android, make sure to enable the [code]INTERNET[/code] 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.
|
|
[b]Example of contacting a REST API and printing one of its returned fields:[/b]
|
|
[codeblocks]
|
|
[gdscript]
|
|
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.new().stringify({"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 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"])
|
|
[/gdscript]
|
|
[csharp]
|
|
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 = new JSON().Stringify(new Godot.Collections.Dictionary
|
|
{
|
|
{ "name", "Godette" }
|
|
});
|
|
error = httpRequest.Request("https://httpbin.org/post", null, true, 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(int result, int response_code, string[] headers, byte[] body)
|
|
{
|
|
var json = new JSON();
|
|
json.Parse(body.GetStringFromUTF8());
|
|
var response = json.GetData() 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"]);
|
|
}
|
|
[/csharp]
|
|
[/codeblocks]
|
|
[b]Example of loading and displaying an image using HTTPRequest:[/b]
|
|
[codeblocks]
|
|
[gdscript]
|
|
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://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
|
|
[/gdscript]
|
|
[csharp]
|
|
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://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;
|
|
}
|
|
[/csharp]
|
|
[/codeblocks]
|
|
[b]Gzipped response bodies[/b]: HTTPRequest will automatically handle decompression of response bodies. A [code]Accept-Encoding[/code] header will be automatically added to each of your requests, unless one is already specified. Any response with a [code]Content-Encoding: gzip[/code] header will automatically be decompressed and delivered to you as uncompressed bytes.
|
|
</description>
|
|
<tutorials>
|
|
<link title="Making HTTP requests">$DOCS_URL/tutorials/networking/http_request_class.html</link>
|
|
<link title="SSL certificates">$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="PackedStringArray" default="PackedStringArray()" />
|
|
<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.uri_encode] for an example).
|
|
[b]Note:[/b] 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.
|
|
</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="PackedStringArray" default="PackedStringArray()" />
|
|
<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="PackedByteArray" default="PackedByteArray()" />
|
|
<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="accept_gzip" type="bool" setter="set_accept_gzip" getter="is_accepting_gzip" default="true">
|
|
If [code]true[/code], this header will be added to each request: [code]Accept-Encoding: gzip, deflate[/code] telling servers that it's okay to compress response bodies.
|
|
Any Response body declaring a [code]Content-Encoding[/code] of either [code]gzip[/code] or [code]deflate[/code] will then be automatically decompressed, and the uncompressed bytes will be delivered via [code]request_completed[/code].
|
|
If the user has specified their own [code]Accept-Encoding[/code] header, then no header will be added regardless of [code]accept_gzip[/code].
|
|
If [code]false[/code] 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 [code]request_completed[/code].
|
|
</member>
|
|
<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. If the response body is compressed, this will be used as the maximum allowed size for the decompressed body.
|
|
</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. Will output any received file into it.
|
|
</member>
|
|
<member name="max_redirects" type="int" setter="set_max_redirects" getter="get_max_redirects" default="8">
|
|
Maximum number of allowed redirects.
|
|
</member>
|
|
<member name="timeout" type="float" setter="set_timeout" getter="get_timeout" default="0.0">
|
|
</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="PackedStringArray" />
|
|
<argument index="3" name="body" type="PackedByteArray" />
|
|
<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_BODY_DECOMPRESS_FAILED" value="8" enum="Result">
|
|
</constant>
|
|
<constant name="RESULT_REQUEST_FAILED" value="9" enum="Result">
|
|
Request failed (currently unused).
|
|
</constant>
|
|
<constant name="RESULT_DOWNLOAD_FILE_CANT_OPEN" value="10" enum="Result">
|
|
HTTPRequest couldn't open the download file.
|
|
</constant>
|
|
<constant name="RESULT_DOWNLOAD_FILE_WRITE_ERROR" value="11" enum="Result">
|
|
HTTPRequest couldn't write to the download file.
|
|
</constant>
|
|
<constant name="RESULT_REDIRECT_LIMIT_REACHED" value="12" enum="Result">
|
|
Request reached its maximum redirect limit, see [member max_redirects].
|
|
</constant>
|
|
<constant name="RESULT_TIMEOUT" value="13" enum="Result">
|
|
</constant>
|
|
</constants>
|
|
</class>
|