2017-09-13 04:42:36 +08:00
<?xml version="1.0" encoding="UTF-8" ?>
2020-02-01 09:03:48 +08:00
<class name= "HTTPRequest" inherits= "Node" version= "4.0" >
2017-09-13 04:42:36 +08:00
<brief_description >
2019-11-07 08:51:31 +08:00
A node with the ability to send HTTP(S) requests.
2017-09-13 04:42:36 +08:00
</brief_description>
<description >
2017-12-11 03:32:34 +08:00
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.
2021-08-11 21:49:58 +08:00
[b]Warning:[/b] See the notes and warnings on [HTTPClient] for limitations, especially regarding SSL security.
2021-08-10 23:47:09 +08:00
[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.
2019-12-25 06:20:27 +08:00
[b]Example of contacting a REST API and printing one of its returned fields:[/b]
2020-10-31 07:37:55 +08:00
[codeblocks]
[gdscript]
2019-12-25 06:20:27 +08:00
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")
2020-07-10 05:24:04 +08:00
# Perform a GET request. The URL below returns JSON as of writing.
2019-12-25 06:20:27 +08:00
var error = http_request.request("https://httpbin.org/get")
if error != OK:
push_error("An error occurred in the HTTP request.")
2020-07-10 05:24:04 +08:00
# 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"}
2020-11-01 02:20:18 +08:00
error = http_request.request("https://httpbin.org/post", [], true, HTTPClient.METHOD_POST, body)
2020-07-10 05:24:04 +08:00
if error != OK:
push_error("An error occurred in the HTTP request.")
2019-12-25 06:20:27 +08:00
# 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"])
2020-10-31 07:37:55 +08:00
[/gdscript]
[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"]);
}
[/csharp]
[/codeblocks]
2019-11-07 08:51:31 +08:00
[b]Example of loading and displaying an image using HTTPRequest:[/b]
2020-10-31 07:37:55 +08:00
[codeblocks]
[gdscript]
2019-11-07 08:51:31 +08:00
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):
2020-10-31 07:37:55 +08:00
if result != HTTPRequest.RESULT_SUCCESS:
push_error("Image couldn't be downloaded. Try a different image.")
2019-11-07 08:51:31 +08:00
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
2020-10-31 07:37:55 +08:00
[/gdscript]
[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;
}
[/csharp]
[/codeblocks]
2020-10-17 20:47:49 +08:00
[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.
2017-09-13 04:42:36 +08:00
</description>
<tutorials >
2021-11-15 17:43:07 +08:00
<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>
2017-09-13 04:42:36 +08:00
</tutorials>
<methods >
<method name= "cancel_request" >
2021-07-30 21:28:05 +08:00
<return type= "void" />
2017-09-13 04:42:36 +08:00
<description >
2017-12-11 03:32:34 +08:00
Cancels the current request.
2017-09-13 04:42:36 +08:00
</description>
</method>
<method name= "get_body_size" qualifiers= "const" >
2021-07-30 21:28:05 +08:00
<return type= "int" />
2017-09-13 04:42:36 +08:00
<description >
2017-12-11 03:32:34 +08:00
Returns the response body length.
2019-10-23 02:16:29 +08:00
[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].
2017-09-13 04:42:36 +08:00
</description>
</method>
<method name= "get_downloaded_bytes" qualifiers= "const" >
2021-07-30 21:28:05 +08:00
<return type= "int" />
2017-09-13 04:42:36 +08:00
<description >
2017-12-11 03:32:34 +08:00
Returns the amount of bytes this HTTPRequest downloaded.
2017-09-13 04:42:36 +08:00
</description>
</method>
<method name= "get_http_client_status" qualifiers= "const" >
2021-07-30 21:28:05 +08:00
<return type= "int" enum= "HTTPClient.Status" />
2017-09-13 04:42:36 +08:00
<description >
2019-12-07 06:09:20 +08:00
Returns the current status of the underlying [HTTPClient]. See [enum HTTPClient.Status].
2017-09-13 04:42:36 +08:00
</description>
</method>
<method name= "request" >
2021-07-30 21:28:05 +08:00
<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= """" />
2017-09-13 04:42:36 +08:00
<description >
2018-04-20 17:25:06 +08:00
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].
2019-06-27 19:24:03 +08:00
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.
2021-09-07 22:48:31 +08:00
[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.
2017-09-13 04:42:36 +08:00
</description>
</method>
2020-05-21 16:05:32 +08:00
<method name= "request_raw" >
2021-07-30 21:28:05 +08:00
<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()" />
2020-05-21 16:05:32 +08:00
<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>
2021-12-09 11:34:32 +08:00
<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>
2017-09-13 04:42:36 +08:00
</methods>
<members >
2020-09-11 18:22:10 +08:00
<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.
2020-09-18 19:35:51 +08:00
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].
2021-03-18 19:04:28 +08:00
If the user has specified their own [code]Accept-Encoding[/code] header, then no header will be added regardless of [code]accept_gzip[/code].
2020-09-11 18:22:10 +08:00
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>
2019-06-29 18:38:01 +08:00
<member name= "body_size_limit" type= "int" setter= "set_body_size_limit" getter= "get_body_size_limit" default= "-1" >
2020-05-21 16:05:32 +08:00
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.
2017-09-13 04:42:36 +08:00
</member>
2020-10-19 20:41:29 +08:00
<member name= "download_chunk_size" type= "int" setter= "set_download_chunk_size" getter= "get_download_chunk_size" default= "65536" >
2019-11-24 20:20:24 +08:00
The size of the buffer used and maximum bytes to read per iteration. See [member HTTPClient.read_chunk_size].
2020-10-19 20:41:29 +08:00
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.
2019-11-24 20:20:24 +08:00
</member>
2019-06-29 18:38:01 +08:00
<member name= "download_file" type= "String" setter= "set_download_file" getter= "get_download_file" default= """" >
2018-01-12 06:38:35 +08:00
The file to download into. Will output any received file into it.
</member>
2019-06-29 18:38:01 +08:00
<member name= "max_redirects" type= "int" setter= "set_max_redirects" getter= "get_max_redirects" default= "8" >
2017-12-11 03:32:34 +08:00
Maximum number of allowed redirects.
2017-09-13 04:42:36 +08:00
</member>
2019-07-10 22:06:23 +08:00
<member name= "timeout" type= "int" setter= "set_timeout" getter= "get_timeout" default= "0" >
</member>
2019-06-29 18:38:01 +08:00
<member name= "use_threads" type= "bool" setter= "set_use_threads" getter= "is_using_threads" default= "false" >
2018-12-20 20:46:54 +08:00
If [code]true[/code], multithreading is used to improve performance.
2017-09-13 04:42:36 +08:00
</member>
</members>
<signals >
<signal name= "request_completed" >
2021-07-30 21:28:05 +08:00
<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" />
2017-09-13 04:42:36 +08:00
<description >
2019-06-22 07:04:47 +08:00
Emitted when a request is completed.
2017-09-13 04:42:36 +08:00
</description>
</signal>
</signals>
<constants >
2017-11-25 06:16:30 +08:00
<constant name= "RESULT_SUCCESS" value= "0" enum= "Result" >
2017-09-13 04:42:36 +08:00
Request successful.
</constant>
2017-11-25 06:16:30 +08:00
<constant name= "RESULT_CHUNKED_BODY_SIZE_MISMATCH" value= "1" enum= "Result" >
2017-09-13 04:42:36 +08:00
</constant>
2017-11-25 06:16:30 +08:00
<constant name= "RESULT_CANT_CONNECT" value= "2" enum= "Result" >
2017-09-13 04:42:36 +08:00
Request failed while connecting.
</constant>
2017-11-25 06:16:30 +08:00
<constant name= "RESULT_CANT_RESOLVE" value= "3" enum= "Result" >
2017-09-13 04:42:36 +08:00
Request failed while resolving.
</constant>
2017-11-25 06:16:30 +08:00
<constant name= "RESULT_CONNECTION_ERROR" value= "4" enum= "Result" >
2018-12-29 07:17:09 +08:00
Request failed due to connection (read/write) error.
2017-09-13 04:42:36 +08:00
</constant>
2017-11-25 06:16:30 +08:00
<constant name= "RESULT_SSL_HANDSHAKE_ERROR" value= "5" enum= "Result" >
2017-09-13 04:42:36 +08:00
Request failed on SSL handshake.
</constant>
2017-11-25 06:16:30 +08:00
<constant name= "RESULT_NO_RESPONSE" value= "6" enum= "Result" >
2018-12-29 07:17:09 +08:00
Request does not have a response (yet).
2017-09-13 04:42:36 +08:00
</constant>
2017-11-25 06:16:30 +08:00
<constant name= "RESULT_BODY_SIZE_LIMIT_EXCEEDED" value= "7" enum= "Result" >
2018-12-29 07:17:09 +08:00
Request exceeded its maximum size limit, see [member body_size_limit].
2017-09-13 04:42:36 +08:00
</constant>
2020-09-11 18:22:10 +08:00
<constant name= "RESULT_BODY_DECOMPRESS_FAILED" value= "8" enum= "Result" >
</constant>
<constant name= "RESULT_REQUEST_FAILED" value= "9" enum= "Result" >
2020-01-23 18:14:14 +08:00
Request failed (currently unused).
2017-09-13 04:42:36 +08:00
</constant>
2020-09-11 18:22:10 +08:00
<constant name= "RESULT_DOWNLOAD_FILE_CANT_OPEN" value= "10" enum= "Result" >
2017-09-13 04:42:36 +08:00
HTTPRequest couldn't open the download file.
</constant>
2020-09-11 18:22:10 +08:00
<constant name= "RESULT_DOWNLOAD_FILE_WRITE_ERROR" value= "11" enum= "Result" >
2017-09-13 04:42:36 +08:00
HTTPRequest couldn't write to the download file.
</constant>
2020-09-11 18:22:10 +08:00
<constant name= "RESULT_REDIRECT_LIMIT_REACHED" value= "12" enum= "Result" >
2018-12-29 07:17:09 +08:00
Request reached its maximum redirect limit, see [member max_redirects].
2017-09-13 04:42:36 +08:00
</constant>
2020-09-11 18:22:10 +08:00
<constant name= "RESULT_TIMEOUT" value= "13" enum= "Result" >
2019-07-10 22:06:23 +08:00
</constant>
2017-09-13 04:42:36 +08:00
</constants>
</class>
