HTTPClient
低级别的超文本传输协议客户端。
描述
超文本传输协议客户端,有时称为“用户代理”。用于发出 HTTP 请求,以下载网络内容、上传文件和其他数据,或与各种服务进行通信,以及其他情况。更高级的替代方案请参阅 :ref:`HTTPRequest<class_HTTPRequest>` 节点 。
注意:这个客户端只需要连接主机一次就可以发送多个请求,参阅 connect_to_host。因此,获取 URL 的方法通常只获取主机后面的部分,而不是完整的 URL,因为客户端已经连接到了一个主机。参阅 request以获得完整的例子,并开始使用。
HTTPClient
应该在多个请求中重复使用,或者连接到不同的主机,而不是每个请求创建一个客户端。它支持 SSL 和 SSL 服务器证书验证。HTTP 状态代码在 2xx 范围内表示成功,3xx 表示重定向,即“请在这里重试”,4xx 表示请求出了问题,5xx 表示服务器端出了问题。
关于 HTTP 的更多信息,请参阅 https://developer.mozilla.org/en-US/docs/Web/HTTP,或者阅读 RFC 2616,直接从源头上了解:https://tools.ietf.org/html/rfc2616。
注意:当从导出到 HTML5 的项目中执行 HTTP 请求时,请记住远程服务器可能由于 CORS 而不允许来自站外的请求。如果是你托管的服务器,应该修改其后台,为其添加 Access-Control-Allow-Origin:*
HTTP 头。
注意:SSL/TLS 支持目前仅限于 TLS 1.0、TLS 1.1 和 TLS 1.2。试图连接到一个只有 TLS 1.3 的服务器将返回一个错误。
警告:目前不支持 SSL/TLS 证书撤销和证书绑定。撤销的证书只要在其他方面是有效的,就可以接受。如果这是个问题,你可能想使用自动管理的有效期短的证书。
教程
属性
| ||
|
方法
void | close ( ) |
connect_to_host ( String host, int port=-1, bool use_ssl=false, bool verify_host=true ) | |
get_response_body_length ( ) const | |
get_response_code ( ) const | |
get_status ( ) const | |
has_response ( ) const | |
is_response_chunked ( ) const | |
poll ( ) | |
query_string_from_dict ( Dictionary fields ) | |
request ( Method method, String url, PoolStringArray headers, String body=”” ) | |
request_raw ( Method method, String url, PoolStringArray headers, PoolByteArray body ) | |
void | set_http_proxy ( String host, int port ) |
void | set_https_proxy ( String host, int port ) |
枚举
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:描述操作结果的资源已通过消息体发送。TRACE:消息体包含服务器所收到的请求消息。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
。客户端如果发送范围(Range)报头就会收到该响应码,用于将下载拆分成多个数据流。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,也可能是 URL 有效但资源本身不存在。也有可能在客户端未提供认证信息时代替 403 返回,从而达到隐藏资源存在性的目的。RESPONSE_METHOD_NOT_ALLOWED = 405 —- HTTP 状态码
405 Method Not Allowed
。服务器理解请求所使用的 HTTP 方法,但该方法已被禁止使用。例如:API 可能禁止 DELETE 资源。GET 和 HEAD 这两个方法是必须的,所以不能被禁用,也不应该返回该错误码。RESPONSE_NOT_ACCEPTABLE = 406 —- HTTP 状态码
406 Not Acceptable
。根据请求中主动注明的交涉报头字段,目标资源没有用户代理所能接受的表示。用于内容交涉过程。RESPONSE_PROXY_AUTHENTICATION_REQUIRED = 407 —- HTTP 状态码
407 Proxy Authentication Required
。类似于 401 Unauthorized,表示客户端需要在提供认证信息后使用代理。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 Percondition 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
。请求的 Range 报头中指定的所有范围都与所选资源的有效范围不重合,或者拒绝处理该范围的集合。拒绝的可能原因是存在无效的范围,或者存在过多细小或者重叠的范围。RESPONSE_EXPECTATION_FAILED = 417 —- HTTP 状态码
417 Expectation Failed
。请求的 Expect 报头中给出的预期无法被任何内部服务器满足。RESPONSE_IM_A_TEAPOT = 418 —- HTTP 状态码
418 I'm A Teapot
。想要尝试用茶壶煮咖啡就会得到错误码“418 因为我是个茶壶”,得到的实体大概又矮又胖。这个错误是对1998年愚人节玩笑的超文本咖啡壶控制协议的引用。RESPONSE_MISDIRECTED_REQUEST = 421 —- HTTP 状态码
421 Misdirected Request
。请求被重定向到了一台无法生成响应的服务器。如果一台服务器没有针对请求 URI 的协议类型和主机身份配置响应,就有可能返回这个代码。RESPONSE_UNPROCESSABLE_ENTITY = 422 —- HTTP 状态码
422 Unprocessable Entity
(WebDAV)。服务器能够理解请求实体的内容类型(所以不适用 415 Unsupported Media Type 状态码),请求实体的语法也是正确的(所以不适用 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
。服务器在处理“Depth: infinity”请求时遇到了死循环并终止了操作。该状态表示该操作整体失败。RESPONSE_NOT_EXTENDED = 510 —- HTTP 状态码
510 Not Extended
。请求未满足访问该资源的策略。服务器应当将所需信息返回给客户端,以便其提交后续请求。RESPONSE_NETWORK_AUTH_REQUIRED = 511 —- HTTP 状态码
511 Network Authentication Required
。客户端需要身份认证才能访问网络。
属性说明
- bool blocking_mode_enabled
Default |
|
Setter | set_blocking_mode(value) |
Getter | is_blocking_mode_enabled() |
为 true
时,执行会阻塞至从响应中读取所有数据为止。
- StreamPeer connection
Setter | set_connection(value) |
Getter | get_connection() |
该客户端所使用的连接。
- int read_chunk_size
Default |
|
Setter | set_read_chunk_size(value) |
Getter | get_read_chunk_size() |
使用的缓冲区大小,即每次迭代读取的最大字节数。见 read_response_body_chunk。
方法说明
- void close ( )
关闭当前连接,允许重用此HTTPClient
。
连接到主机。需要在发送任何请求前执行。
主机不应该带有 http:// 前缀,如果有的话协议标识符会被剥离。
如果未指定 port
(或者使用的是 -1
),默认 HTTP 会使用 80,HTTPS(启用了 use_ssl
)会使用 443。
verify_host
设为 true
时会检查主机的 SSL 身份。
- int get_response_body_length ( ) const
返回响应体长度。
注意:部分 Web 服务器可能不发送响应体长度,此时返回值将为 -1
。如果使用分块传输编码,响应体的长度也将为 -1
。
- int get_response_code ( ) const
返回响应的 HTTP 状态码。
- PoolStringArray get_response_headers ( )
返回响应报头。
- Dictionary get_response_headers_as_dictionary ( )
返回所有响应报头,是 { "报头字段名称": "字段取值1; 字段取值2" }
格式的字典,字典的键和值均保持服务器所发送的大小写。字段取值为简单的 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 ( Dictionary fields )
根据所提供的字典生成 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": [22, 33, 44]}
var query_string = http_client.query_string_from_dict(fields)
# 返回 "single=123¬_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 代理服务器发送请求时应为绝对 URL。进行 METHOD_OPTIONS 请求时,还允许使用 *
。进行 METHOD_CONNECT 请求时,应为身份组件(主机:端口
)。
Headers 参数是 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)
注意: method
为 METHOD_GET 时会忽略 request_data
参数。这是因为 GET 方法不能包含请求数据。作为变通,可以把请求数据通过 URL 的请求字符串传递。例子见 String.http_escape。
- Error request_raw ( Method method, String url, PoolStringArray headers, PoolByteArray body )
向连接的主机发送原始请求。
URL参数通常只是主机后面的部分,所以对于http://somehost.com/index.php
,它是/index.php
。当向HTTP代理服务器发送请求时,它应该是一个绝对的URL。对于METHOD_OPTIONS请求,允许*
。对于METHOD_CONNECT请求,应该是标准组件,host:port
。
头信息是HTTP请求头信息。关于可用的HTTP方法,参阅Method。
以字节数组的形式发送原始正文数据,不以任何方式进行编码。
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.