HTTPRequest

Inherits: Node < Object

具有发送 HTTP(S) 请求能力的节点。

描述

有能力发送HTTP请求的节点。内部使用HTTPClient

可以用来进行HTTP请求,即通过HTTP下载或上传文件或网络内容。

警告:参阅HTTPClient的注释和警告,以了解其局限性,特别是关于SSL的安全性。

连接REST API并打印其返回字段之一的例子:

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"])

使用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

方法

void

cancel_request ( )

int

get_body_size ( ) const

int

get_downloaded_bytes ( ) const

Status

get_http_client_status ( ) const

Error

request ( String url, PoolStringArray custom_headers=PoolStringArray( ), bool ssl_validate_domain=true, Method method=0, String request_data="" )

Error

request_raw ( String url, PoolStringArray custom_headers=PoolStringArray( ), bool ssl_validate_domain=true, Method method=0, PoolByteArray request_data_raw=PoolByteArray( ) )

void

set_http_proxy ( String host, int port )

void

set_https_proxy ( String host, int port )

信号

请求完成时触发。

枚举

enum Result:

  • RESULT_SUCCESS = 0 --- 请求成功。

  • RESULT_CHUNKED_BODY_SIZE_MISMATCH = 1

  • RESULT_CANT_CONNECT = 2 --- 连接时请求失败。

  • RESULT_CANT_RESOLVE = 3 --- 解析时请求失败。

  • RESULT_CONNECTION_ERROR = 4 --- 因连接(读写)错误而失败。

  • RESULT_SSL_HANDSHAKE_ERROR = 5 --- SSL 握手时请求失败。

  • RESULT_NO_RESPONSE = 6 --- 请求(目前还)没有获得相应。

  • RESULT_BODY_SIZE_LIMIT_EXCEEDED = 7 --- 请求超出了大小上限,见 body_size_limit

  • RESULT_REQUEST_FAILED = 8 --- 请求失败(目前未使用)。

  • RESULT_DOWNLOAD_FILE_CANT_OPEN = 9 --- HTTPRequest 无法打开下载文件。

  • RESULT_DOWNLOAD_FILE_WRITE_ERROR = 10 --- HTTPRequest 无法写入下载文件。

  • RESULT_REDIRECT_LIMIT_REACHED = 11 --- 请求超出了重定向次数上限,见 max_redirects

  • RESULT_TIMEOUT = 12

属性说明

  • int body_size_limit

Default

-1

Setter

set_body_size_limit(value)

Getter

get_body_size_limit()

允许的最大响应体大小。


  • int download_chunk_size

Default

65536

Setter

set_download_chunk_size(value)

Getter

get_download_chunk_size()

使用的缓冲区大小和每次迭代读取的最大字节数。参阅 HTTPClient.read_chunk_size

下载小文件时将其设置为较低的值,以降低内存使用量,但会降低下载速度,例如 4096 表示 4 KiB。


Default

""

Setter

set_download_file(value)

Getter

get_download_file()

下载到的文件。将在其中写入任何收到的文件。


  • int max_redirects

Default

8

Setter

set_max_redirects(value)

Getter

get_max_redirects()

允许的最大重定向数。


Default

0

Setter

set_timeout(value)

Getter

get_timeout()


Default

false

Setter

set_use_threads(value)

Getter

is_using_threads()

true 时,将启用多线程提高性能。

方法说明

  • void cancel_request ( )

取消当前请求。


  • int get_body_size ( ) const

返回响应体长度。

注意: 部分 Web 服务器可能不发送响应体长度,此时返回值将为 -1。如果使用分块传输编码,响应体的长度也将为 -1


  • int get_downloaded_bytes ( ) const

返回该 HTTPRequest 已下载的字节数。


  • Status get_http_client_status ( ) const

返回内部 HTTPClient 的当前状态。见 Status


在底层的 HTTPClient 上创建请求。如果没有配置错误,它会尝试使用 HTTPClient.connect_to_host 连接并将参数传递给 HTTPClient.request

如果请求创建成功,则返回 @GlobalScope.OK。 (并不意味着服务器已响应),@GlobalScope.ERR_UNCONFIGURED 如果不在树中,@GlobalScope.ERR_BUSY 如果仍在处理先前的请求,@GlobalScope.ERR_INVALID_PARAMETER 如果给定的字符串不是有效的 URL 格式,或 @GlobalScope.ERR_CANT_CONNECT如果不使用线程并且 HTTPClient 无法连接到主机。

注意:methodHTTPClient.METHOD_GET时,通过request_data发送的payload可能会被服务器忽略甚至导致服务器拒绝请求,参阅 RFC 7231 第 4.3.1 节 了解更多。作为一种解决方法,你可以将数据作为 URL 中的查询字符串发送。参阅 String.http_escape 示例。


在底层的HTTPClient上创建请求,使用一个原始字节数组作为请求主体。如果没有配置错误,它会尝试使用 HTTPClient.connect_to_host 连接并将参数传递给 HTTPClient.request

如果请求创建成功,则返回 @GlobalScope.OK。 (并不意味着服务器已响应),@GlobalScope.ERR_UNCONFIGURED 如果不在树中,@GlobalScope.ERR_BUSY 如果仍在处理先前的请求,@GlobalScope.ERR_INVALID_PARAMETER 如果给定的字符串不是有效的 URL 格式,或 @GlobalScope.ERR_CANT_CONNECT如果不使用线程并且 HTTPClient 无法连接到主机。


  • void set_http_proxy ( String host, int port )

Sets the proxy server for HTTP requests.

The proxy server is unset if host is empty or port is -1.


  • void set_https_proxy ( String host, int port )

Sets the proxy server for HTTPS requests.

The proxy server is unset if host is empty or port is -1.