HTTPRequest¶
A node with the ability to send HTTP(S) requests.
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.
Warning: See the notes and warnings on 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 = {"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
Tutorials¶
Properties¶
|
||
|
||
|
||
|
||
|
||
|
Methods¶
void |
cancel_request ( ) |
get_body_size ( ) const |
|
get_downloaded_bytes ( ) const |
|
get_http_client_status ( ) const |
|
request ( String url, PoolStringArray custom_headers=PoolStringArray( ), bool ssl_validate_domain=true, Method method=0, String request_data="" ) |
|
request_raw ( String url, PoolStringArray custom_headers=PoolStringArray( ), bool ssl_validate_domain=true, Method method=0, PoolByteArray request_data_raw=PoolByteArray( ) ) |
Signals¶
request_completed ( int result, int response_code, PoolStringArray headers, PoolByteArray body )
Emitted when a request is completed.
Enumerations¶
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 body_size_limit.
RESULT_REQUEST_FAILED = 8 --- Request failed (currently unused).
RESULT_DOWNLOAD_FILE_CANT_OPEN = 9 --- HTTPRequest couldn't open the download file.
RESULT_DOWNLOAD_FILE_WRITE_ERROR = 10 --- HTTPRequest couldn't write to the download file.
RESULT_REDIRECT_LIMIT_REACHED = 11 --- Request reached its maximum redirect limit, see max_redirects.
RESULT_TIMEOUT = 12
Property Descriptions¶
int body_size_limit
Default |
|
Setter |
set_body_size_limit(value) |
Getter |
get_body_size_limit() |
Maximum allowed size for response bodies.
int download_chunk_size
Default |
|
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 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.
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.
int max_redirects
Default |
|
Setter |
set_max_redirects(value) |
Getter |
get_max_redirects() |
Maximum number of allowed redirects.
int timeout
Default |
|
Setter |
set_timeout(value) |
Getter |
get_timeout() |
bool use_threads
Default |
|
Setter |
set_use_threads(value) |
Getter |
is_using_threads() |
If true
, multithreading is used to improve performance.
Method Descriptions¶
void cancel_request ( )
Cancels the current request.
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
.
int get_downloaded_bytes ( ) const
Returns the amount of bytes this HTTPRequest downloaded.
Status get_http_client_status ( ) const
Returns the current status of the underlying HTTPClient. See Status.
Error request ( String url, PoolStringArray custom_headers=PoolStringArray( ), bool ssl_validate_domain=true, Method method=0, String request_data="" )
Creates request on the underlying HTTPClient. If there is no configuration errors, it tries to connect using HTTPClient.connect_to_host and passes parameters onto HTTPClient.request.
Returns @GlobalScope.OK if request is successfully created. (Does not imply that the server has responded), @GlobalScope.ERR_UNCONFIGURED if not in the tree, @GlobalScope.ERR_BUSY if still processing previous request, @GlobalScope.ERR_INVALID_PARAMETER if given string is not a valid URL format, or @GlobalScope.ERR_CANT_CONNECT if not using thread and the HTTPClient cannot connect to host.
Note: When method
is 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 String.http_escape for an example.
Error request_raw ( String url, PoolStringArray custom_headers=PoolStringArray( ), bool ssl_validate_domain=true, Method method=0, PoolByteArray request_data_raw=PoolByteArray( ) )
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 HTTPClient.connect_to_host and passes parameters onto HTTPClient.request.
Returns @GlobalScope.OK if request is successfully created. (Does not imply that the server has responded), @GlobalScope.ERR_UNCONFIGURED if not in the tree, @GlobalScope.ERR_BUSY if still processing previous request, @GlobalScope.ERR_INVALID_PARAMETER if given string is not a valid URL format, or @GlobalScope.ERR_CANT_CONNECT if not using thread and the HTTPClient cannot connect to host.