HTTPRequest¶
具有发送 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 ( ) |
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( ) ) |
|
void |
set_http_proxy ( String host, int port ) |
void |
set_https_proxy ( String host, int port ) |
信号¶
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
Default |
|
Setter |
set_body_size_limit(value) |
Getter |
get_body_size_limit() |
允许的最大响应体大小。
int download_chunk_size
Default |
|
Setter |
set_download_chunk_size(value) |
Getter |
get_download_chunk_size() |
使用的缓冲区大小和每次迭代读取的最大字节数。参阅 HTTPClient.read_chunk_size。
下载小文件时将其设置为较低的值，以降低内存使用量，但会降低下载速度，例如 4096 表示 4 KiB。
String download_file
Default |
|
Setter |
set_download_file(value) |
Getter |
get_download_file() |
下载到的文件。将在其中写入任何收到的文件。
int max_redirects
Default |
|
Setter |
set_max_redirects(value) |
Getter |
get_max_redirects() |
允许的最大重定向数。
int timeout
Default |
|
Setter |
set_timeout(value) |
Getter |
get_timeout() |
bool use_threads
Default |
|
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。
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 无法连接到主机。
Sets the proxy server for HTTP requests.
The proxy server is unset if host is empty or port is -1.
Sets the proxy server for HTTPS requests.
The proxy server is unset if host is empty or port is -1.