HTTPClient

继承

简要描述

超文本传输协议客户端。

描述

超文本传输协议客户端（有时称为“用户代理”）。除其他用例外，用于发出HTTP请求以下载Web内容，上传文件和其他数据或与各种服务进行通信。有关更高级的选择，请参见HTTPRequest。

注意：该客户端只需连接一次主机（请参阅connect_to_host）即可发送多个请求。因此，采用URL的方法通常只占主机后面的一部分，而不占整个URL的一部分，因为客户端已连接到主机。有关完整的示例和入门，请参见request。

HTTPClient应该在多个请求之间重用或连接到不同的主机，而不是为每个请求创建一个客户端。支持SSL和SSL服务器证书验证。 2xx范围内的HTTP状态代码表示成功，3xx重定向（即“重试，但在此处”），4xx请求有问题，以及5xx服务器端出了问题。

有关HTTP的更多信息，请参见https://developer.mozilla.org/en-US/docs/Web/HTTP（或阅读RFC 2616以直接从源代码获取它：https://tools.ietf.org/html/rfc2616）。

成员

类型	属性名	默认值
bool	blocking_mode_enabled	false
StreamPeer	connection
int	read_chunk_size	4096

方法

返回值类型	方法名称
void	close()
int	connect_to_host(host: String, port: int = -1, use_ssl: bool = false, verify_host: bool = true)
int	get_response_body_length() const
int	get_response_code() const
PoolStringArray	get_response_headers()
Dictionary	get_response_headers_as_dictionary()
int	get_status() const
bool	has_response() const
bool	is_response_chunked() const
int	poll()
String	query_string_from_dict(fields: Dictionary)
PoolByteArray	read_response_body_chunk()
int	request(method: int, url: String, headers: PoolStringArray, body: String = "")
int	request_raw(method: int, url: String, headers: PoolStringArray, body: PoolByteArray)

枚举

enum Method:

**METHOD_GET = 0**

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

**METHOD_HEAD = 1**

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

**METHOD_POST = 2**

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

**METHOD_PUT = 3**

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

**METHOD_DELETE = 4**

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

**METHOD_OPTIONS = 5**

HTTP OPTIONS方法。 OPTIONS方法要求描述目标资源的通信选项。几乎没有使用过。

**METHOD_TRACE = 6**

HTTP TRACE方法。 TRACE方法沿到目标资源的路径执行消息环回测试。返回在响应主体中接收到的整个HTTP请求。几乎没有使用过。

**METHOD_CONNECT = 7**

HTTP CONNECT方法。 CONNECT方法建立到由目标资源标识的服务器的隧道。几乎没有使用过。

**METHOD_PATCH = 8**

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

**METHOD_MAX = 9**

表示Method枚举的大小。

enum Status:

**STATUS_DISCONNECTED = 0**

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

**STATUS_RESOLVING = 1**

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

**STATUS_CANT_RESOLVE = 2**

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

**STATUS_CONNECTING = 3**

状态：当前正在连接服务器。

**STATUS_CANT_CONNECT = 4**

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

**STATUS_CONNECTED = 5**

状态：连接已建立。

**STATUS_REQUESTING = 6**

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

**STATUS_BODY = 7**

状态：HTTP正文已收到。

**STATUS_CONNECTION_ERROR = 8**

状态：HTTP连接错误。

**STATUS_SSL_HANDSHAKE_ERROR = 9**

状态：SSL握手错误。

enum ResponseCode:

**RESPONSE_CONTINUE = 100**

HTTP状态码 100 Continue。指示到目前为止的一切都可以的临时响应是正确的，客户端应继续执行该请求（如果已完成，则忽略此状态）。

**RESPONSE_SWITCHING_PROTOCOLS = 101**

HTTP状态码101 Switching Protocol。响应客户端发送的 Upgrade请求标头而发送。指示服务器要切换到的协议。

**RESPONSE_PROCESSING = 102**

HTTP状态码 102 Processing（WebDAV）。表示服务器已接收并正在处理请求，但尚无响应。

**RESPONSE_OK = 200**

HTTP状态码200 OK。该请求已成功。成功请求的默认响应。含义因请求而异。 GET：资源已被获取并在消息正文中传输。 HEAD：实体标题位于消息正文中。 POST：描述操作结果的资源在消息正文中传输。跟踪：消息正文包含服务器接收到的请求消息。

**RESPONSE_CREATED = 201**

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

**RESPONSE_ACCEPTED = 202**

HTTP状态码 202 Accepted。该请求已收到，但尚未执行。它是非承诺性的，这意味着HTTP中没有办法以后再发送异步响应来指示处理请求的结果。它用于其他进程或服务器处理该请求的情况，或用于批处理。

**RESPONSE_NON_AUTHORITATIVE_INFORMATION = 203**

HTTP状态码 203 Non-Authoritative Information。此响应代码意味着返回的元信息集不是从原始服务器获得的确切集，而是从本地或第三方副本收集的。除这种情况外，应首选200 OK响应而不是此响应。

**RESPONSE_NO_CONTENT = 204**

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

**RESPONSE_RESET_CONTENT = 205**

HTTP状态码 205 Reset Content。服务器已满足该请求，并希望客户端重置“文档视图”，该文档视图导致从原始服务器接收到的请求被发送到其原始状态。

**RESPONSE_PARTIAL_CONTENT = 206**

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

**RESPONSE_MULTI_STATUS = 207**

HTTP状态码 207 Multi-Status（WebDAV）。在可能需要多个状态代码的情况下，多状态响应传达有关多个资源的信息。

**RESPONSE_ALREADY_REPORTED = 208**

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

**RESPONSE_IM_USED = 226**

HTTP状态码 226 IM Used（WebDAV）。服务器已完成对资源的GET请求，并且响应表示应用于当前实例的一个或多个实例操作的结果。

**RESPONSE_MULTIPLE_CHOICES = 300**

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

**RESPONSE_MOVED_PERMANENTLY = 301**

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

**RESPONSE_FOUND = 302**

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

**RESPONSE_SEE_OTHER = 303**

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

**RESPONSE_NOT_MODIFIED = 304**

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

**RESPONSE_USE_PROXY = 305**

HTTP状态代码 305 Use Proxy。 已弃用。不要使用。

**RESPONSE_SWITCH_PROXY = 306**

HTTP状态码 306 Switch Proxy。 已弃用。不要使用。

**RESPONSE_TEMPORARY_REDIRECT = 307**

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

**RESPONSE_PERMANENT_REDIRECT = 308**

HTTP状态码 308 Permanent Redirect。已为目标资源分配了新的永久URI，并且对该资源的任何将来引用都应使用随附的URI之一。

**RESPONSE_BAD_REQUEST = 400**

HTTP状态码 400 Bad Request。该请求无效。由于某些东西被认为是客户端错误（例如，格式不正确的请求语法，无效的请求消息框架，无效的请求内容或欺骗性的请求路由），服务器无法或不会处理该请求。

**RESPONSE_UNAUTHORIZED = 401**

HTTP状态码 401 Unauthorized。需要凭据。由于缺少针对目标资源的有效身份验证凭据，因此尚未应用该请求。

**RESPONSE_PAYMENT_REQUIRED = 402**

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

**RESPONSE_FORBIDDEN = 403**

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

**RESPONSE_NOT_FOUND = 404**

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

**RESPONSE_METHOD_NOT_ALLOWED = 405**

HTTP状态码 405 Method Not Allowed。服务器知道该请求的HTTP方法，但已被禁用，无法使用。例如，API可能禁止删除资源。决不能禁用这两个强制方法GET和HEAD，并且不应返回此错误代码。

**RESPONSE_NOT_ACCEPTABLE = 406**

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

**RESPONSE_PROXY_AUTHENTICATION_REQUIRED = 407**

HTTP状态码 407 Proxy Authentication Required。与401未经授权类似，但它表示客户端需要进行身份验证才能使用代理。

**RESPONSE_REQUEST_TIMEOUT = 408**

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

**RESPONSE_CONFLICT = 409**

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

**RESPONSE_GONE = 410**

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

**RESPONSE_LENGTH_REQUIRED = 411**

HTTP状态码 411 Length Required。服务器拒绝没有定义的Content-Length标头的请求。

**RESPONSE_PRECONDITION_FAILED = 412**

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

**RESPONSE_REQUEST_ENTITY_TOO_LARGE = 413**

HTTP状态码 413 Entity Too Larg。服务器拒绝处理请求，因为请求有效负载大于服务器愿意或能够处理的负载。

**RESPONSE_REQUEST_URI_TOO_LONG = 414**

HTTP状态码 414 Request-URI Too Long。服务器拒绝处理请求，因为请求目标的时间比服务器愿意解释的时间长。

**RESPONSE_UNSUPPORTED_MEDIA_TYPE = 415**

HTTP状态码 415 Unsupported Media Type。原始服务器拒绝为请求提供服务，因为有效载荷的格式不受目标资源上此方法的支持。

**RESPONSE_REQUESTED_RANGE_NOT_SATISFIABLE = 416**

HTTP状态代码 416 Requested Range Not Satisfiable。请求的“范围”标头字段中没有任何范围与所选资源的当前范围重叠，或者由于无效范围或过多的较小或重叠范围的请求而拒绝了所请求的范围集。

**RESPONSE_EXPECTATION_FAILED = 417**

HTTP状态码 417 Expectation Failed。至少一台入站服务器无法满足请求的Expect标头字段中给出的期望。

**RESPONSE_IM_A_TEAPOT = 418**

HTTP状态码 418 I'm A Teapot。任何尝试用茶壶冲泡咖啡的尝试都将导致错误代码" 418我是茶壶"。生成的实体主体可能短而结实。

**RESPONSE_MISDIRECTED_REQUEST = 421**

HTTP状态码 421 Misdirected Request。该请求被定向到不能产生响应的服务器。这可以由未配置为对请求URI中包含的方案和权限的组合产生响应的服务器发送。

**RESPONSE_UNPROCESSABLE_ENTITY = 422**

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

**RESPONSE_LOCKED = 423**

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

**RESPONSE_FAILED_DEPENDENCY = 424**

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

**RESPONSE_UPGRADE_REQUIRED = 426**

HTTP状态码 426 Upgrade Required。服务器拒绝使用当前协议执行请求，但是在客户端升级到其他协议后，服务器可能愿意这样做。

**RESPONSE_PRECONDITION_REQUIRED = 428**

HTTP状态码 428 Precondition Required。原始服务器要求该请求是有条件的。

**RESPONSE_TOO_MANY_REQUESTS = 429**

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

**RESPONSE_REQUEST_HEADER_FIELDS_TOO_LARGE = 431**

HTTP状态码 431 Request Header Fields Too Large。服务器不愿意处理该请求，因为其标头字段太大。减小请求头字段的大小后，可以重新提交请求。

**RESPONSE_UNAVAILABLE_FOR_LEGAL_REASONS = 451**

HTTP状态代码 451 Response Unavailable For Legal Reasons。由于法律要求，服务器拒绝对资源的访问。

**RESPONSE_INTERNAL_SERVER_ERROR = 500**

HTTP状态码 500 Internal Server Error。服务器遇到意外情况，阻止其满足请求。

**RESPONSE_NOT_IMPLEMENTED = 501**

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

**RESPONSE_BAD_GATEWAY = 502**

HTTP状态码 502 Bad Gateway。该服务器在充当网关或代理的同时，从尝试执行该请求时访问的入站服务器接收到无效响应。通常由负载均衡器或代理返回。

**RESPONSE_SERVICE_UNAVAILABLE = 503**

HTTP状态码 503 Service Unavailable。由于暂时的过载或计划的维护，服务器当前无法处理该请求，这可能会在某些延迟后得到缓解。稍后再试。

**RESPONSE_GATEWAY_TIMEOUT = 504**

HTTP状态码 504 Gateway Timeout。该服务器虽然充当网关或代理，但未收到来自其需要访问以完成请求的上游服务器的及时响应。通常由负载均衡器或代理返回。

**RESPONSE_HTTP_VERSION_NOT_SUPPORTED = 505**

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

**RESPONSE_VARIANT_ALSO_NEGOTIATES = 506**

HTTP状态码 506 Variant Also Negotiates。服务器有一个内部配置错误：所选变体资源被配置为本身参与透明的内容协商，因此不是协商过程中的适当终点。

**RESPONSE_INSUFFICIENT_STORAGE = 507**

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

**RESPONSE_LOOP_DETECTED = 508**

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

**RESPONSE_NOT_EXTENDED = 510**

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

**RESPONSE_NETWORK_AUTH_REQUIRED = 511**

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

常量

成员说明

bool blocking_mode_enabled

Default	false
setter	set_blocking_mode(value)
getter	is_blocking_mode_enabled

StreamPeer connection

setter	set_connection(value)
getter	get_connection

int read_chunk_size

Default	4096
setter	set_read_chunk_size(value)
getter	get_read_chunk_size

方法说明

close close()

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

connect_to_host connect_to_host(host: String, port: int = -1, use_ssl: bool = false, verify_host: bool = true)

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

主机不应带有http://，但会剥离协议标识符（如果提供）。

如果未指定port（或使用-1），则HTTP会自动设置为80，HTTPS会自动设置为443（如果use_ssl为启用）。

如果设置为true，则verify_host将检查主机的SSL身份。

get_response_body_length get_response_body_length() const

返回响应的正文长度。

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

get_response_code get_response_code() const

返回响应的HTTP状态代码。

get_response_headers get_response_headers()

返回响应头。

get_response_headers_as_dictionary get_response_headers_as_dictionary()

以结构{"key"："value1; value2"}的字典形式返回所有响应标头，其中键和值的区分大小写保持不变，就像服务器提供它一样。值是一个简单的字符串，该字符串可以有多个值，其中“;”用作分隔符。

示例：

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

get_status get_status() const

返回[枚举状态]常量。需要调用poll以获得状态更新。

has_response has_response() const

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

is_response_chunked is_response_chunked() const

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

poll poll()

需要调用它以便处理任何请求。使用get_status检查结果。

query_string_from_dict query_string_from_dict(fields: Dictionary)

从提供的字典中生成GET/POST application/x-www-form-urlencoded样式查询字符串，例如：

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

此外，如果一个键具有null值，则只添加键本身，没有等号和等值。如果该值是一个数组，则为其中的每个值添加一个具有相同键的对。

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

read_response_body_chunk read_response_body_chunk()

从响应中读取一个块。

request request(method: int, url: String, headers: PoolStringArray, body: String = "")

向连接的主机发送请求。 URL参数只是主机后面的部分，因此对于http://somehost.com/index.php，它是index.php。

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

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

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

request_raw request_raw(method: int, url: String, headers: PoolStringArray, body: PoolByteArray)

向连接的主机发送原始请求。 URL参数只是主机后面的部分，因此对于http://somehost.com/index.php，它是index.php。

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

以字节数组的形式发送主体数据，并且不对其进行任何编码。

HTTPClient

继承​

简要描述​

描述​

成员​

方法​

枚举​

常量​

成员说明​

方法说明​

继承

简要描述

描述

成员

方法

枚举

常量

成员说明

方法说明