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

教程

• 进行 HTTP 请求

• SSL 证书

属性

方法

信号

• request_completed ( int result, int response_code, PoolStringArray headers, PoolByteArray body )

请求完成时触发。

枚举

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

允许的最大响应体大小。

• int download_chunk_size

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

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

• String download_file

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

• int max_redirects

允许的最大重定向数。

• int timeout

• bool use_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。

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

在底层的 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 无法连接到主机。

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

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

在底层的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.