Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

HTTPRequest

继承： Node < Object

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

描述

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

可用于发出 HTTP 请求，即通过 HTTP 下载或上传文件或网络内容。

警告：请参阅 HTTPClient 中的注释和警告以了解限制，尤其是有关 TLS 安全性的限制。

注意：导出到 Android 时，在导出项目或使用一键部署前，请确保在 Android 导出预设中启用 INTERNET 权限。否则，任何类型的网络通信都将被 Android 阻止。

示例：联系 REST API 并输出一个返回字段：

func _ready():
    # 创建一个 HTTP 请求节点并连接其完成信号。
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(self._http_request_completed)

    # 执行一个 GET 请求。以下 URL 会将写入作为 JSON 返回。
    var error = http_request.request("https://httpbin.org/get")
    if error != OK:
        push_error("在HTTP请求中发生了一个错误。")

    # 执行一个 POST 请求。 以下 URL 会将写入作为 JSON 返回。
    # 注意：不要使用单个 HTTPRequest 节点同时发出请求。
    # 下面的代码片段仅供参考。
    var body = JSON.new().stringify({"name": "Godette"})
    error = http_request.request("https://httpbin.org/post", [], HTTPClient.METHOD_POST, body)
    if error != OK:
        push_error("在HTTP请求中发生了一个错误。")

# 当 HTTP 请求完成时调用。
func _http_request_completed(result, response_code, headers, body):
    var json = JSON.new()
    json.parse(body.get_string_from_utf8())
    var response = json.get_data()

    # 将打印 HTTPRequest 节点使用的用户代理字符串（由 httpbin.org 识别）。
    print(response.headers["User-Agent"])

public override void _Ready()
{
    // 创建一个 HTTP 请求节点并连接其完成信号。
    var httpRequest = new HttpRequest();
    AddChild(httpRequest);
    httpRequest.RequestCompleted += HttpRequestCompleted;

    // 执行一个 GET 请求。以下 URL 会将写入作为 JSON 返回。
    Error error = httpRequest.Request("https://httpbin.org/get");
    if (error != Error.Ok)
    {
        GD.PushError("在HTTP请求中发生了一个错误。");
    }

    // 执行一个 POST 请求。 以下 URL 会将写入作为 JSON 返回。
    // 注意：不要使用单个 HTTPRequest 节点同时发出请求。
    // 下面的代码片段仅供参考。
    string body = new Json().Stringify(new Godot.Collections.Dictionary
    {
        { "name", "Godette" }
    });
    error = httpRequest.Request("https://httpbin.org/post", null, HttpClient.Method.Post, body);
    if (error != Error.Ok)
    {
        GD.PushError("在HTTP请求中发生了一个错误。");
    }
}

// 当 HTTP 请求完成时调用。
private void HttpRequestCompleted(long result, long responseCode, string[] headers, byte[] body)
{
    var json = new Json();
    json.Parse(body.GetStringFromUtf8());
    var response = json.GetData().AsGodotDictionary();

    // 将打印 HTTPRequest 节点使用的用户代理字符串（由 httpbin.org 识别）。
    GD.Print((response["headers"].AsGodotDictionary())["User-Agent"]);
}

示例：使用 HTTPRequest 加载并显示图像：

func _ready():
    # 创建一个 HTTP 请求节点并连接其完成信号。
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(self._http_request_completed)

    # 执行一个 HTTP 请求。下面的 URL 将写入作为一个 PNG 图像返回。
    var error = http_request.request("https://placehold.co/512")
    if error != OK:
        push_error("在HTTP请求中发生了一个错误。")

# 当 HTTP 请求完成时调用。
func _http_request_completed(result, response_code, headers, body):
    if result != HTTPRequest.RESULT_SUCCESS:
        push_error("无法下载图像。尝试一个不同的图像。")

    var image = Image.new()
    var error = image.load_png_from_buffer(body)
    if error != OK:
        push_error("无法加载图像。")

    var texture = ImageTexture.create_from_image(image)

    # 在 TextureRect 节点中显示图像。
    var texture_rect = TextureRect.new()
    add_child(texture_rect)
    texture_rect.texture = texture

public override void _Ready()
{
    // 创建一个 HTTP 请求节点并连接其完成信号。
    var httpRequest = new HttpRequest();
    AddChild(httpRequest);
    httpRequest.RequestCompleted += HttpRequestCompleted;

    // 执行一个 HTTP 请求。下面的 URL 将写入作为一个 PNG 图像返回。
    Error error = httpRequest.Request("https://placehold.co/512");
    if (error != Error.Ok)
    {
        GD.PushError("在HTTP请求中发生了一个错误。");
    }
}

// 当 HTTP 请求完成时调用。
private void HttpRequestCompleted(long result, long responseCode, string[] headers, byte[] body)
{
    if (result != (long)HttpRequest.Result.Success)
    {
        GD.PushError("无法下载图像。尝试一个不同的图像。");
    }
    var image = new Image();
    Error error = image.LoadPngFromBuffer(body);
    if (error != Error.Ok)
    {
        GD.PushError("无法加载图像。");
    }

    var texture = ImageTexture.CreateFromImage(image);

    // 在 TextureRect 节点中显示图像。
    var textureRect = new TextureRect();
    AddChild(textureRect);
    textureRect.Texture = texture;
}

注意：HTTPRequest 节点会自动处理响应体的解压缩。除非已经指定了一个，否则 Accept-Encoding 报头将自动添加到你的每个请求中。任何带有 Content-Encoding: gzip 报头的响应都将自动解压，并作为未压缩的字节传送给你。

教程

属性

bool	accept_gzip	`true`
int	body_size_limit	`-1`
int	download_chunk_size	`65536`
String	download_file	`""`
int	max_redirects	`8`
float	timeout	`0.0`
bool	use_threads	`false`

方法

void	cancel_request()
int	get_body_size() const
int	get_downloaded_bytes() const
Status	get_http_client_status() const
Error	request(url: String, custom_headers: PackedStringArray = PackedStringArray(), method: Method = 0, request_data: String = "")
Error	request_raw(url: String, custom_headers: PackedStringArray = PackedStringArray(), method: Method = 0, request_data_raw: PackedByteArray = PackedByteArray())
void	set_http_proxy(host: String, port: int)
void	set_https_proxy(host: String, port: int)
void	set_tls_options(client_options: TLSOptions)

信号

request_completed(result: int, response_code: int, headers: PackedStringArray, body: PackedByteArray) 🔗

请求完成时触发。

枚举

enum Result: 🔗

Result RESULT_SUCCESS = 0

请求成功。

Result RESULT_CHUNKED_BODY_SIZE_MISMATCH = 1

请求失败，传输的实际数据块大小与预期不符。可能的原因有网络错误、服务器配置问题、数据块编码问题等。

Result RESULT_CANT_CONNECT = 2

连接时请求失败。

Result RESULT_CANT_RESOLVE = 3

解析时请求失败。

Result RESULT_CONNECTION_ERROR = 4

因连接（读写）错误而失败。

Result RESULT_TLS_HANDSHAKE_ERROR = 5

TLS 握手时请求失败。

Result RESULT_NO_RESPONSE = 6

请求（目前还）没有获得相应。

Result RESULT_BODY_SIZE_LIMIT_EXCEEDED = 7

请求超出了大小上限，见 body_size_limit。

Result RESULT_BODY_DECOMPRESS_FAILED = 8

请求失败，解压响应体出错。可能的原因有压缩格式不支持、压缩格式错误、数据损坏、传输不完整等。

Result RESULT_REQUEST_FAILED = 9

请求失败（目前未使用）。

Result RESULT_DOWNLOAD_FILE_CANT_OPEN = 10

HTTPRequest 无法打开下载文件。

Result RESULT_DOWNLOAD_FILE_WRITE_ERROR = 11

HTTPRequest 无法写入下载文件。

Result RESULT_REDIRECT_LIMIT_REACHED = 12

请求超出了重定向次数上限，见 max_redirects。

Result RESULT_TIMEOUT = 13

请求由于超时而失败。如果本就希望请求花费较长的时间，请尝试增大 timeout，或将其设为 0.0 从而完全移除超时。

属性说明

bool accept_gzip = true 🔗

void set_accept_gzip(value: bool)
bool is_accepting_gzip()

如果为 true，这个报头会被添加到每个请求中：Accept-Encoding: gzip, deflate 告诉服务器可以压缩响应正文。

任何声明 gzip 或 deflate 的 Content-Encoding 的响应正文，将被自动解压缩，并且未压缩的字节将通过 request_completed 被传递。

如果用户指定了自己的 Accept-Encoding 报头，那么无论 accept_gzip 是什么，都不会添加任何报头。

如果为 false，这将不会添加报头，并且不会对响应正文执行任何解压缩。响应正文的原始字节将通过 request_completed 返回。

int body_size_limit = -1 🔗

void set_body_size_limit(value: int)
int get_body_size_limit()

响应正文的最大允许大小。如果响应正文被压缩，这将用作解压缩的正文的最大允许大小。

int download_chunk_size = 65536 🔗

void set_download_chunk_size(value: int)
int get_download_chunk_size()

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

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

String download_file = "" 🔗

void set_download_file(value: String)
String get_download_file()

要下载到的文件。将任何接收到的文件输出到其中。

int max_redirects = 8 🔗

void set_max_redirects(value: int)
int get_max_redirects()

允许的最大重定向数。

float timeout = 0.0 🔗

void set_timeout(value: float)
float get_timeout()

请求超时前等待的秒数。如果 timeout 为 0.0，则请求不会超时。对于简单的请求，例如与 REST API 通信，建议将 timeout 设为与服务器响应时间匹配的值（例如 1.0 和 10.0 之间）。这样能够防止由于服务器响应时间的变化而造成的超时，同时仍然允许应用程序检测到请求超时。对于大型请求，例如下载文件，建议将 timeout 设置为 0.0 禁用超时功能。这样有助于防止由于超时而让大型传输失败。

bool use_threads = false 🔗

void set_use_threads(value: bool)
bool 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(url: String, custom_headers: PackedStringArray = PackedStringArray(), method: Method = 0, request_data: String = "") 🔗

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

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

注意：当 method 为 HTTPClient.METHOD_GET 时，通过 request_data 发送的有效载荷可能会被服务器忽略，甚至导致服务器拒绝请求（见 RFC 7231 第 4.3.1 节了解更多详情）。作为一种变通方法，可以在 URL 中将数据作为查询字符串发送（有关示例，请参见 String.uri_encode()）。

注意：建议使用传输加密（TLS）并避免在 HTTP GET URL 参数中发送敏感信息（例如登录凭据）。考虑改用 HTTP POST 请求或 HTTP 报头来获取此类信息。

Error request_raw(url: String, custom_headers: PackedStringArray = PackedStringArray(), method: Method = 0, request_data_raw: PackedByteArray = PackedByteArray()) 🔗

在底层的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(host: String, port: int) 🔗

设置 HTTP 请求使用的代理服务器。

如果 host 为空或者 port 为 -1，则会取消设置代理服务器。

void set_https_proxy(host: String, port: int) 🔗

设置 HTTPS 请求使用的代理服务器。

如果 host 为空或者 port 为 -1，则会取消设置代理服务器。

void set_tls_options(client_options: TLSOptions) 🔗

设置连接到 HTTPS 服务器时使用的 TLSOptions。见 TLSOptions.client()。