HTTPRequest

Inherits: Node < Object A node with the ability to send HTTP(S) requests.

Description

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:

  1. 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:

  1. 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

  • 进行 HTTP 请求
  • SSL 证书

    Properties

    Methods

    Signals

  • request_completed ( int result, int response_code, PoolStringArray headers, PoolByteArray body ) Emitted when a request is completed.

    Enumerations

    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 Maximum allowed size for response bodies.
  • int download_chunk_size 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 The file to download into. Will output any received file into it.
  • int max_redirects Maximum number of allowed redirects.

- int timeout

  • bool use_threads true, multithreading is used to improve performance.

    Method Descriptions

  • 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 HTTPClient. See Status.
  • Error request ( String url, PoolStringArray custom_headers=PoolStringArray( ), bool ssl_validate_domain=true, Method method=0, String request_data=”” ) HTTPClient. If there is no configuration errors, it tries to connect using HTTPClient.connect_to_host and passes parameters onto HTTPClient.request. @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( ) ) 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. @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.