HTTPClient

继承： RefCounted < Object

低级超文本传输协议客户端。

描述

超文本传输协议客户端（有时称为“用户代理”）。用于发出HTTP请求以下载Web内容、上传文件和其他数据或与各种服务通信，以及其他用例。

有关更高级别的替代方案，请参阅HTTPRequest节点。

注意：此客户端只需连接到主机一次（参见connect_to_host()）即可发送多个请求。因此，获取URL的方法通常只获取主机之后的部分，而不是完整的URL，因为客户端已经连接到主机。有关完整示例和开始，请参阅request()。

HTTPClient应该在多个请求之间重用或连接到不同的主机，而不是每个请求创建一个客户端。支持安全传输层协议（TLS），包括服务器证书验证。2xx范围内的HTTP状态代码表示成功，3xx重定向（即“重试，但在这里”），4xx请求出错，5xx服务器端出错。

有关HTTP的更多信息，请参阅MDN在HTTP上的文档（或阅读RFC 2616以直接从源代码获取）。

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

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

注意：执行从项目导出到Web的HTTP请求时，请记住，由于CORS，远程服务器可能不允许来自外部来源的请求。如果您托管相关服务器，您应该通过添加Access-Control-Allow-Origin：*HTTP标头来修改其后端以允许来自外部来源的请求。

注意：TLS支持目前仅限于TLSv1.2和TLSv1.3。尝试连接到仅支持较旧（不安全）TLS版本的服务器将返回错误。

警告：当前不支持TLS证书吊销和证书固定。只要证书在其他情况下有效，就接受吊销的证书。如果这是一个问题，您可能希望使用有效期较短的自动管理证书。

属性

bool	blocking_mode_enabled	false
StreamPeer	connection
int	read_chunk_size	65536

方法

void	close()
Error	connect_to_host(host: String, port: int = -1, tls_options: TLSOptions = null)
int	get_response_body_length() const
int	get_response_code() const
PackedStringArray	get_response_headers()
Dictionary	get_response_headers_as_dictionary()
Status	get_status() const
bool	has_response() const
bool	is_response_chunked() const
Error	poll()
String	query_string_from_dict(fields: Dictionary)
PackedByteArray	read_response_body_chunk()
Error	request(method: Method, url: String, headers: PackedStringArray, body: String = "")
Error	request_raw(method: Method, url: String, headers: PackedStringArray, body: PackedByteArray)
void	set_http_proxy(host: String, port: int)
void	set_https_proxy(host: String, port: int)

---

枚举

enum Method: 🔗

Method METHOD_GET = 0

HTTP GET方法。GET方法请求指定资源的表示。使用GET的请求应该只检索数据。

Method METHOD_HEAD = 1

HTTP HEAD方法。HEAD方法请求与GET请求相同的响应，但没有响应正文。这对于请求HTTP标头等元数据或检查资源是否存在很有用。

Method METHOD_POST = 2

HTTP POST方法。POST方法用于将实体提交到指定的资源，通常会导致状态发生变化或对服务器产生副作用。这通常用于表单和提交数据或上传文件。

Method METHOD_PUT = 3

HTTP PUT方法。PUT方法要求用请求负载替换目标资源的所有当前表示。（您可以将POST视为“创建或更新”，将PUT视为“更新”，尽管许多服务往往不会做出明确的区分或改变其含义）。

Method METHOD_DELETE = 4

HTTP DELETE方法。DELETE方法请求删除指定的资源。

Method METHOD_OPTIONS = 5

HTTP OPTIONS方法。OPTIONS方法要求描述目标资源的通信选项。很少使用。

Method METHOD_TRACE = 6

HTTP TRACE方法。TRACE方法沿着目标资源的路径执行消息循环测试。返回在响应正文中收到的整个HTTP请求。很少使用。

Method METHOD_CONNECT = 7

HTTP CONNECT方法。CONNECT方法建立到目标资源标识的服务器的隧道。很少使用。

Method METHOD_PATCH = 8

HTTP PATCH方法。PATCH方法用于对资源应用部分修改。

Method METHOD_MAX = 9

表示Method枚举的大小。

---

enum Status: 🔗

Status STATUS_DISCONNECTED = 0

状态：与服务器断开连接。

Status STATUS_RESOLVING = 1

状态：当前将给定URL的主机名解析为IP。

Status STATUS_CANT_RESOLVE = 2

状态：DNS失败：无法解析给定URL的主机名。

Status STATUS_CONNECTING = 3

状态：当前连接到服务器。

Status STATUS_CANT_CONNECT = 4

状态：无法连接到服务器。

Status STATUS_CONNECTED = 5

状态：连接已建立。

Status STATUS_REQUESTING = 6

状态：当前正在发送请求。

Status STATUS_BODY = 7

状态：收到HTTP正文。

Status STATUS_CONNECTION_ERROR = 8

状态：HTTP连接错误。

Status STATUS_TLS_HANDSHAKE_ERROR = 9

状态：TLS握手错误。

---

enum ResponseCode: 🔗

ResponseCode RESPONSE_CONTINUE = 100

HTTP状态代码100继续。指示到目前为止一切正常并且客户端应继续请求的临时响应（如果已经完成，则忽略此状态）。

ResponseCode RESPONSE_SWITCHING_PROTOCOLS = 101

HTTP状态代码101切换协议。响应客户端的升级请求标头发送。指示服务器正在切换到的协议。

ResponseCode RESPONSE_PROCESSING = 102

HTTP状态代码102处理（WebDAV）。表示服务器已经收到并正在处理请求，但还没有可用的响应。

ResponseCode RESPONSE_OK = 200

HTTP状态码200 OK。请求已成功。成功请求的默认响应。含义因请求而异：

-METHOD_GET：资源已被获取并在消息正文中传输。

-METHOD_HEAD：实体标题在消息正文中。

-METHOD_POST：描述动作结果的资源在消息体中传输。

-METHOD_TRACE：消息正文包含服务器接收到的请求消息。

ResponseCode RESPONSE_CREATED = 201

HTTP状态代码201 Created。请求已成功，并因此创建了一个新资源。这通常是在PUT请求之后发送的响应。

ResponseCode RESPONSE_ACCEPTED = 202

HTTP状态代码202已接受。请求已收到但尚未采取行动。它是非提交的，这意味着在HTTP中无法稍后发送指示处理请求结果的异步响应。它适用于另一个进程或服务器处理请求的情况，或者用于批次处理作业。

ResponseCode RESPONSE_NON_AUTHORITATIVE_INFORMATION = 203

HTTP状态代码203非权威信息。此响应代码表示返回的元信息集不是从源服务器获得的精确设置，而是从本地或第三方副本收集的。除此条件外，200 OK响应应该是首选，而不是此响应。

ResponseCode RESPONSE_NO_CONTENT = 204

HTTP状态代码204 No Content。此请求没有要发送的内容，但标头可能很有用。用户代理可以使用新的标头更新此资源的缓存标头。

ResponseCode RESPONSE_RESET_CONTENT = 205

HTTP状态代码205重置内容。服务器已完成请求，并希望客户端重置导致请求发送到从源服务器接收到的原始状态的“文档视图”。

ResponseCode RESPONSE_PARTIAL_CONTENT = 206

HTTP状态代码206部分内容。使用此响应代码是因为客户端发送了范围标头以将下载分成多个流。

ResponseCode RESPONSE_MULTI_STATUS = 207

HTTP状态代码207 Multi-State（WebDAV）。在可能适合多个状态代码的情况下，多状态响应传递有关多个资源的信息。

ResponseCode RESPONSE_ALREADY_REPORTED = 208

HTTP状态代码208已报告（WebDAV）。在DAV：prostat响应元素中使用，以避免重复枚举多个绑定到同一集合的内部成员。

ResponseCode RESPONSE_IM_USED = 226

HTTP状态代码226 IM已使用（WebDAV）。服务器已完成对资源的GET请求，响应是应用于当前实例的一个或多个instance-manipulations的结果的表示。

ResponseCode RESPONSE_MULTIPLE_CHOICES = 300

HTTP状态代码300 MultiChoice。请求有多个可能的响应，并且没有标准化的方法来选择其中一个响应。用户代理或用户应该选择其中之一。

ResponseCode RESPONSE_MOVED_PERMANENTLY = 301

HTTP状态代码301永久移动。重定向。此响应代码表示请求资源的URI已更改。新的URI通常包含在响应中。

ResponseCode RESPONSE_FOUND = 302

HTTP状态代码302找到。临时重定向。此响应代码表示请求资源的URI已被临时更改。将来可能会对URI进行新的更改。因此，客户端在未来的请求中应该使用相同的URI。

ResponseCode RESPONSE_SEE_OTHER = 303

HTTP状态代码303请参阅其他。服务器正在将用户代理重定向到不同的资源，如位置标头字段中的URI所示，该字段旨在提供对原始请求的间接响应。

ResponseCode RESPONSE_NOT_MODIFIED = 304

HTTP状态代码304 Not Modified。已收到条件GET或HEAD请求，如果不是条件评估为false，则会导致200 OK响应。

ResponseCode RESPONSE_USE_PROXY = 305

已弃用： 出于安全原因，许多客户端会忽略该响应代码。HTTP 标准也已弃用它。

HTTP状态代码305使用代理。

ResponseCode RESPONSE_SWITCH_PROXY = 306

已弃用： 出于安全原因，许多客户端会忽略该响应代码。HTTP 标准也已弃用它。

HTTP状态代码306交换机代理。

ResponseCode RESPONSE_TEMPORARY_REDIRECT = 307

HTTP状态代码307临时重定向。目标资源暂时驻留在不同的URI下，如果用户代理执行到该URI的自动重定向，则用户代理不得更改请求方法。

ResponseCode RESPONSE_PERMANENT_REDIRECT = 308

HTTP状态代码308永久重定向。目标资源已被分配一个新的永久URI，将来对该资源的任何引用都应使用随附的URI之一。

ResponseCode RESPONSE_BAD_REQUEST = 400

HTTP状态代码400错误请求。请求无效。由于被认为是客户端错误（例如，格式错误的请求语法、无效的请求消息帧、无效的请求内容或欺骗性的请求路由），服务器无法或不会处理请求。

ResponseCode RESPONSE_UNAUTHORIZED = 401

HTTP状态代码401未授权。需要凭据。该请求尚未应用，因为它缺少目标资源的有效身份验证凭据。

ResponseCode RESPONSE_PAYMENT_REQUIRED = 402

HTTP状态代码402需要付款。此响应代码保留供将来使用。创建此代码的最初目的是将其用于数字支付系统，但目前尚未使用。

ResponseCode RESPONSE_FORBIDDEN = 403

HTTP状态代码403禁止。客户端没有访问内容的权限，即它们是未经授权的，因此服务器拒绝给出适当的响应。与401不同，服务器知道客户端的身份。

ResponseCode RESPONSE_NOT_FOUND = 404

HTTP状态代码404未找到。服务器找不到请求的资源。URL未被识别或端点有效但资源本身不存在。如果客户端未被授权，也可以发送而不是403来隐藏资源的存在。

ResponseCode RESPONSE_METHOD_NOT_ALLOWED = 405

HTTP状态代码405方法不允许。服务器知道请求的HTTP方法，但已禁用且无法使用。例如，API可能会禁止删除资源。两个强制方法GET和HEAD不得禁用，也不应返回此错误代码。

ResponseCode RESPONSE_NOT_ACCEPTABLE = 406

HTTP状态代码406不可接受。根据请求中接收到的主动协商标头字段，目标资源没有用户代理可以接受的当前表示。协商内容时使用。

ResponseCode RESPONSE_PROXY_AUTHENTICATION_REQUIRED = 407

HTTP状态码407需要代理身份验证。类似于401未授权，但它表示客户端需要对自己进行身份验证才能使用代理。

ResponseCode RESPONSE_REQUEST_TIMEOUT = 408

HTTP状态代码408请求超时。服务器在准备等待的时间内没有收到完整的请求消息。

ResponseCode RESPONSE_CONFLICT = 409

HTTP状态代码409冲突。由于与目标资源的当前状态冲突，请求无法完成。此代码用于用户可能能够解决冲突并重新提交请求的情况。

ResponseCode RESPONSE_GONE = 410

HTTP状态代码410 Gone。目标资源在源服务器上不再可用，这种情况可能是永久性的。

ResponseCode RESPONSE_LENGTH_REQUIRED = 411

HTTP状态代码411长度必需。服务器拒绝接受没有定义Content-Llong标头的请求。

ResponseCode RESPONSE_PRECONDITION_FAILED = 412

HTTP状态代码412前置条件失败。在服务器上测试时，请求标头字段中给出的一个或多个条件被评估为false。

ResponseCode RESPONSE_REQUEST_ENTITY_TOO_LARGE = 413

HTTP状态代码413实体太大。服务器拒绝处理请求，因为请求负载大于服务器愿意或能够处理的负载。

ResponseCode RESPONSE_REQUEST_URI_TOO_LONG = 414

HTTP状态代码414 Request-URI Too Long。服务器拒绝为请求提供服务，因为请求目标比服务器愿意解释的要长。

ResponseCode RESPONSE_UNSUPPORTED_MEDIA_TYPE = 415

HTTP状态代码415不支持的媒体类型。源服务器拒绝为请求提供服务，因为目标资源上的有效负载采用此方法不支持的格式。

ResponseCode RESPONSE_REQUESTED_RANGE_NOT_SATISFIABLE = 416

HTTP状态代码416请求的范围不满足。请求的范围标头字段中没有一个范围与所选资源的当前范围重叠，或者由于无效范围或对小范围或重叠范围的过度请求，请求的范围集被拒绝。

ResponseCode RESPONSE_EXPECTATION_FAILED = 417

HTTP状态代码417期望失败。至少一个入站服务器无法满足请求的期望标头字段中给出的期望。

ResponseCode RESPONSE_IM_A_TEAPOT = 418

HTTP状态代码418 I'm A Teapot。任何用茶壶煮咖啡的尝试都应导致错误代码“418 I'm a teapot”。生成的实体主体可能又短又结实。

ResponseCode RESPONSE_MISDIRECTED_REQUEST = 421

HTTP状态代码421错误请求。请求被定向到无法产生响应的服务器。这可以由未配置为为请求URI中包含的方案和权限组合产生响应的服务器发送。

ResponseCode RESPONSE_UNPROCESSABLE_ENTITY = 422

HTTP状态代码422不可处理实体（WebDAV）。服务器了解请求实体的内容类型（因此415不支持的媒体类型状态代码不合适），请求实体的语法正确（因此400错误请求状态代码不合适），但无法处理包含的指令。

ResponseCode RESPONSE_LOCKED = 423

HTTP状态代码423 Locked（WebDAV）。方法的源或目标资源被锁定。

ResponseCode RESPONSE_FAILED_DEPENDENCY = 424

HTTP状态代码424失败的依赖关系（WebDAV）。无法在资源上执行该方法，因为请求的操作依赖于另一个操作并且该操作失败。

ResponseCode RESPONSE_UPGRADE_REQUIRED = 426

HTTP状态代码426需要升级。服务器拒绝使用当前协议执行请求，但在客户端升级到不同的协议后可能愿意这样做。

ResponseCode RESPONSE_PRECONDITION_REQUIRED = 428

HTTP状态代码428前置条件必需。源服务器要求请求是有条件的。

ResponseCode RESPONSE_TOO_MANY_REQUESTS = 429

HTTP状态代码429 Too More请求。用户在给定的时间内发送了太多请求（请参阅“速率限制”）。退后并增加请求之间的时间或稍后重试。

ResponseCode RESPONSE_REQUEST_HEADER_FIELDS_TOO_LARGE = 431

HTTP状态代码431请求头字段太大。服务器不愿意处理请求，因为它的头字段太大。减少请求头字段的大小后，可以重新提交请求。

ResponseCode RESPONSE_UNAVAILABLE_FOR_LEGAL_REASONS = 451

HTTP状态代码451响应因法律原因不可用。由于法律要求，服务器拒绝访问资源。

ResponseCode RESPONSE_INTERNAL_SERVER_ERROR = 500

HTTP状态代码500内部服务器错误。服务器遇到意外情况，无法完成请求。

ResponseCode RESPONSE_NOT_IMPLEMENTED = 501

HTTP状态代码501未实现。服务器不支持满足请求所需的功能。

ResponseCode RESPONSE_BAD_GATEWAY = 502

HTTP状态代码502错误网关。服务器在充当网关或代理时，在尝试满足请求时收到了来自其访问的入站服务器的无效响应。通常由负载均衡器或代理返回。

ResponseCode RESPONSE_SERVICE_UNAVAILABLE = 503

HTTP状态代码503服务不可用。由于临时过载或计划维护，服务器当前无法处理请求，延迟后可能会减轻。稍后再试。

ResponseCode RESPONSE_GATEWAY_TIMEOUT = 504

HTTP状态代码504网关超时。服务器在充当网关或代理时，没有收到来自它需要访问以完成请求的上游服务器的及时响应。通常由负载均衡器或代理返回。

ResponseCode RESPONSE_HTTP_VERSION_NOT_SUPPORTED = 505

HTTP状态代码505 HTTP版本不支持。服务器不支持或拒绝支持请求消息中使用的HTTP的主要版本。

ResponseCode RESPONSE_VARIANT_ALSO_NEGOTIATES = 506

HTTP状态代码506 Variant也协商服务器有一个内部配置错误：选择的变体资源被配置为自己进行透明内容协商，因此在协商过程中不是合适的终端。

ResponseCode RESPONSE_INSUFFICIENT_STORAGE = 507

HTTP状态代码507存储不足。无法在资源上执行该方法，因为服务器无法存储成功完成请求所需的表示。

ResponseCode RESPONSE_LOOP_DETECTED = 508

HTTP状态代码508 Loop Detted。服务器终止了一个操作，因为它在处理带有“深度：无穷大”的请求时遇到了无限循环。此状态表示整个操作失败。

ResponseCode RESPONSE_NOT_EXTENDED = 510

HTTP状态代码510未扩展。请求中未满足访问资源的策略。服务器应发回客户端发出扩展请求所需的所有信息。

ResponseCode RESPONSE_NETWORK_AUTH_REQUIRED = 511

HTTP状态代码511需要网络身份验证。客户端需要进行身份验证才能获得网络访问权限。

---

属性说明

bool blocking_mode_enabled = false 🔗

• void set_blocking_mode(value: bool)

• bool is_blocking_mode_enabled()

如果true，则执行将阻塞，直到从响应中读取所有数据。

---

StreamPeer connection 🔗

• void set_connection(value: StreamPeer)

• StreamPeer get_connection()

用于此客户端的连接。

---

int read_chunk_size = 65536 🔗

• void set_read_chunk_size(value: int)

• int get_read_chunk_size()

使用的缓冲区大小和每次迭代要读取的最大字节数。参见read_response_body_chunk()。

---

方法说明

void close() 🔗

关闭当前连接，允许重用此HTTPClient。

---

Error connect_to_host(host: String, port: int = -1, tls_options: TLSOptions = null) 🔗

连接到主机。这需要在发送任何请求之前完成。

如果未指定port（或使用-1），则HTTP自动设置为80，HTTPS自动设置为443。您可以传递可选的tls_options参数来自定义受信任的证书颁发机构，或在使用HTTPS时验证通用名称。请参阅TLSOptions.client()和TLSOptions.client_unsafe()。

---

int get_response_body_length() const 🔗

返回响应的主体长度。

注意：某些Web服务器可能不会发送正文长度。在这种情况下，返回的值将是-1。如果使用分块传输编码，正文长度也将是-1。

注意：由于浏览器的限制，此函数在Web平台上总是返回-1。

---

int get_response_code() const 🔗

返回响应的HTTP状态代码。

---

PackedStringArray get_response_headers() 🔗

返回响应标头。

---

Dictionary get_response_headers_as_dictionary() 🔗

以Dictionary的形式返回所有响应标头。每个条目由标头名称和一个String组成，其中包含由"; "分隔的值。标头的格式与接收时保持一致。

{
    "content-length": 12,
    "Content-Type": "application/json; charset=UTF-8",
}

---

Status get_status() const 🔗

返回Status常量。需要调用poll()以获取状态更新。

---

bool has_response() const 🔗

如果true，则此HTTPClient有可用的响应。

---

bool is_response_chunked() const 🔗

如果true，则此HTTPClient具有分块的响应。

---

Error poll() 🔗

这需要调用才能处理任何请求。使用get_status()检查结果。

---

String query_string_from_dict(fields: Dictionary) 🔗

从提供的字典中生成一个 GET/POST 应用程序/x-www-form-urlencoded 格式的查询字符串，例如：

S3ScriptC#

var fields = {"username": "user", "password": "pass"}
var query_string = http_client.query_string_from_dict(fields)
# 返回 "username=user&password=pass"

Furthermore, if a key has a null value, only the key itself is added, without equal sign and value. If the value is an array, for each value in it a pair with the same key is added.

S3ScriptC#

var fields = {"single": 123, "not_valued": null, "multiple": [22, 33, 44]}
var query_string = http_client.query_string_from_dict(fields)
# 返回 "single=123&not_valued&multiple=22&multiple=33&multiple=44"

---

PackedByteArray read_response_body_chunk() 🔗

从响应中读取一个块。

---

Error request(method: Method, url: String, headers: PackedStringArray, body: String = "") 🔗

向已连接的主机发送请求。

URL 参数通常只是主机名后面的部分，因此对于https://example.com/index.php来说，它是/index.php。当向HTTP代理服务器发送请求时，它应该是一个绝对URL。对于METHOD_OPTIONS请求，*也是允许的。对于METHOD_CONNECT请求，它应该是权限组件（host:port）。

Headers 参数是 HTTP 请求的报头。有关可用的 HTTP 方法，请参阅Method。

若要创建带有查询字符串的POST请求以推送到服务器，请执行以下操作：

S3ScriptC#

var fields = {"username" : "user", "password" : "pass"}
var query_string = http_client.query_string_from_dict(fields)
var headers = ["Content-Type: application/x-www-form-urlencoded", "Content-Length: " + str(query_string.length())]
var result = http_client.request(http_client.METHOD_POST, "/index.php", headers, query_string)

---

Error request_raw(method: Method, url: String, headers: PackedStringArray, body: PackedByteArray) 🔗

向连接的主机发送原始请求。

URL参数通常只是host后面的部分，所以对于https://example.com/index.php，它是/index. php。当向HTTP代理服务器发送请求时，它应该是一个绝对的URL。对于METHOD_OPTIONS请求，*也是允许的。对于METHOD_CONNECT请求，它应该是权限组件（host：port）。

标头是HTTP请求标头。有关可用的HTTP方法，请参阅Method。

将正文数据作为字节数组原始发送，并且不以任何方式对其进行编码。

---

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

为HTTP请求设置代理服务器。

如果host为空或port为-1，则代理服务器未设置。

---

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

为HTTPS请求设置代理服务器。

如果host为空或port为-1，则代理服务器未设置。