HTTPClient

Inherits: Reference < Object

类别： 核心

简要说明

超文本传输协议客户端。

属性

bool	blocking_mode_enabled	假
StreamPeer	connection

方法

无效	close ( )
Error	connect_to_host ( String host, int port=-1, bool use_ssl=false, bool verify_host=true )
int	get_response_body_length ( ) const
int	get_response_code ( ) const
PoolStringArray	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 ( Dictionary fields )
PoolByteArray	read_response_body_chunk ( )
Error	request ( Method method, String url, PoolStringArray headers, String body="" )
Error	request_raw ( Method method, String url, PoolStringArray headers, PoolByteArray body )
无效	set_read_chunk_size ( int bytes )

枚举

枚举 方法 ：

• METHOD_GET = 0 ---HTTP GET方法。get方法请求指定资源的表示形式。使用get的请求应该只检索数据。

• METHOD_HEAD = 1 ---HTTP头方法。head方法请求的响应与get请求的响应相同，但没有响应主体。这对于请求元数据（如HTTP头）或检查资源是否存在很有用。

• METHOD_POST = 2 ---HTTP Post方法。post方法用于将实体提交到指定的资源，通常会导致状态更改或对服务器产生副作用。这通常用于表单和提交数据或上载文件。

• METHOD_PUT = 3 ---HTTP Put方法。Put方法要求用请求负载替换目标资源的所有当前表示。（您可以将post视为“创建或更新”，并将其放为“更新”，尽管许多服务往往没有明确区分或更改其含义）。

• METHOD_DELETE = 4 ---HTTP删除方法。删除方法请求删除指定的资源。

• METHOD_OPTIONS = 5 ---HTTP选项方法。Options方法要求描述目标资源的通信选项。很少使用。

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

• METHOD_CONNECT = 7 ---HTTP连接方法。connect方法建立到目标资源标识的服务器的通道。很少使用。

• METHOD_PATCH = 8 ---HTTP补丁方法。patch方法用于对资源应用部分修改。

• METHOD_MAX = 9 ---表示 Method 枚举。

枚举 状态 ：

• 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握手错误。

枚举 ResponseCode ：

• RESPONSE_CONTINUE = 100 ---HTTP状态码 100 Continue . 临时响应，表示到目前为止一切正常，客户机应该继续执行请求（或者如果已经完成，则忽略此状态）。

• RESPONSE_SWITCHING_PROTOCOLS = 101 ---HTTP状态码 101 Switching Protocol . 发送以响应 Upgrade 客户端请求头。指示服务器正在切换到的协议。

• RESPONSE_PROCESSING = 102 ---HTTP状态码 102 Processing （网络视频）。指示服务器已接收并正在处理请求，但没有可用的响应。

• RESPONSE_OK = 200 ---HTTP状态码 200 OK . 请求已成功。成功请求的默认响应。含义因请求而异。获取：资源已被获取并在消息体中传输。头：实体头在消息体中。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 （网络视频）。多状态响应在多个状态代码可能适用的情况下传递有关多个资源的信息。

• RESPONSE_ALREADY_REPORTED = 208 ---HTTP状态码 208 Already Reported （网络视频）。在dav:propstat响应元素内使用，以避免重复枚举同一集合的多个绑定的内部成员。

• RESPONSE_IM_USED = 226 ---HTTP状态码 226 IM Used （网络视频）。服务器已经完成了对资源的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 header字段中的uri所示，该字段旨在提供对原始请求的间接响应。

• RESPONSE_NOT_MODIFIED = 304 ---HTTP状态码 304 Not Modified . 已收到条件GET或HEAD请求，如果不是因为条件评估为 false .

• 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来隐藏资源的存在。

• 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 . 服务器拒绝接受没有定义内容长度头的请求。

• RESPONSE_PRECONDITION_FAILED = 412 ---HTTP状态码 412 Precondition Failed . 请求头字段中给定的一个或多个条件的计算结果为 false 在服务器上测试时。

• RESPONSE_REQUEST_ENTITY_TOO_LARGE = 413 ---HTTP状态码 413 Entity Too Large . 服务器拒绝处理请求，因为请求负载大于服务器愿意或能够处理的负载。

• 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 I'm a Teapot”。产生的实体体可能短而结实。

• RESPONSE_MISDIRECTED_REQUEST = 421 ---HTTP状态码 421 Misdirected Request . 请求被定向到无法生成响应的服务器。这可以由未配置为为为请求URI中包含的方案和权限组合生成响应的服务器发送。

• RESPONSE_UNPROCESSABLE_ENTITY = 422 ---HTTP状态码 422 Unprocessable Entity （网络视频）。服务器了解请求实体的内容类型（因此415个不支持的媒体类型状态代码不合适），请求实体的语法正确（因此400个错误的请求状态代码不合适），但无法处理包含的指令。

• RESPONSE_LOCKED = 423 ---HTTP状态码 423 Locked （网络视频）。方法的源或目标资源被锁定。

• RESPONSE_FAILED_DEPENDENCY = 424 ---HTTP状态码 424 Failed Dependency （网络视频）。无法对资源执行该方法，因为请求的操作依赖于另一个操作，而该操作失败。

• 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 . 客户端需要进行身份验证才能获得网络访问。

描述

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

注： 此客户端只需要连接一次主机（请参见 connect_to_host ）发送多个请求。因此，采用URL的方法通常只采用主机后面的部分，而不是完整的URL，因为客户机已经连接到主机。见 request 为了一个完整的例子和开始。

A 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）。

教程

• HTTP客户端类

• SSL证书

属性描述

• bool blocking_mode_enabled

违约	假
设定器	设置“阻塞”模式（值）
吸气剂	_blocking_mode_enabled（）是否已启用？

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

• StreamPeer connection

设定器	设置连接（值）
吸气剂	获取连接（）

用于此客户端的连接。

方法说明

• void close ( )

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

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

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

主机不应具有http://prepended，但如果提供，它将除去协议标识符。

如果没有 port 被指定（或 -1 使用时），HTTP自动设置为80，HTTPS自动设置为443（如果 use_ssl 已启用）。

verify_host 将检查主机的SSL标识（如果设置为） true .

• int get_response_body_length ( ) const

返回响应的正文长度。

• int get_response_code ( ) const

返回响应的HTTP状态代码。

• PoolStringArray get_response_headers ( )

返回响应头。

• Dictionary get_response_headers_as_dictionary ( )

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

例子：

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

• Status get_status ( ) const

返回A STATUS_* 枚举常量。需要打电话 poll 以获取状态更新。

• bool has_response ( ) const

如果 true ，这个 HTTPClient 有可用的响应。

• bool is_response_chunked ( ) const

如果 true ，这个 HTTPClient 有一个分块的响应。

• Error poll ( )

需要调用此函数才能处理任何请求。检查结果 get_status

• String query_string_from_dict ( Dictionary fields )

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

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

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

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

• PoolByteArray read_response_body_chunk ( )

从响应中读取一个块。

• Error request ( Method method, String url, PoolStringArray headers, String body="" )

向连接的主机发送请求。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 = ["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, String url, PoolStringArray headers, PoolByteArray body )

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

头是HTTP请求头。有关可用的HTTP方法，请参阅 METHOD_* .

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

• void set_read_chunk_size ( int bytes )

设置所用缓冲区的大小以及每次迭代要读取的最大字节数。看见 read_response_body_chunk