模块 Net

常量

HTTPGatewayTimeOut

Gateway Timeout 响应（状态码 504）的响应类。

服务器充当网关或代理，但未及时收到上游服务器的响应。

此类还（间接）包括模块 Net::HTTPHeader，该模块提供了对其获取标头的方法的访问权限。

参考

HTTPMovedTemporarily

Found 响应（状态码 302）的响应类。

Found 响应表示客户端应查看（浏览至）另一个 URL。

此类还（间接）包括模块 Net::HTTPHeader，该模块提供了对其获取标头的方法的访问权限。

参考

HTTPMultipleChoice

Multiple Choices 响应（状态码 300）的响应类。

Multiple Choices 响应表示服务器为客户端可选择的资源提供多个选项。

此类还（间接）包括模块 Net::HTTPHeader，该模块提供了对其获取标头的方法的访问权限。

参考

HTTPRequestEntityTooLarge

Payload Too Large 响应（状态码 413）的响应类。

请求大于服务器愿意或能够处理的大小。

此类还（间接）包括模块 Net::HTTPHeader，该模块提供了对其获取标头的方法的访问权限。

参考

HTTPRequestTimeOut

Request Timeout 响应（状态码 408）的响应类。

服务器等待请求超时。

此类还（间接）包括模块 Net::HTTPHeader，该模块提供了对其获取标头的方法的访问权限。

参考

HTTPRequestURITooLarge

URI Too Long 响应（状态码 414）的响应类。

提供的 URI 太长，服务器无法处理。

此类还（间接）包括模块 Net::HTTPHeader，该模块提供了对其获取标头的方法的访问权限。

参考

HTTPRequestURITooLong

URI Too Long 响应（状态码 414）的响应类。

提供的 URI 太长，服务器无法处理。

此类还（间接）包括模块 Net::HTTPHeader，该模块提供了对其获取标头的方法的访问权限。

参考

HTTPRequestedRangeNotSatisfiable

Range Not Satisfiable 响应（状态码 416）的响应类。

请求实体具有服务器或资源不支持的媒体类型。

此类还（间接）包括模块 Net::HTTPHeader，该模块提供了对其获取标头的方法的访问权限。

参考

HTTPSession

类 Net::HTTP 提供了一个丰富的库，该库在客户端-服务器模型中实现了客户端，该模型使用 HTTP 请求-响应协议。有关 HTTP 的信息，请参阅

关于示例¶ ↑

此处的示例假设已要求使用 net/http（这也需要 uri）

require 'net/http'

此处的许多代码示例都使用以下示例网站

某些示例还假定以下变量

uri = URI('https://jsonplaceholder.typicode.com/')
uri.freeze # Examples may not modify.
hostname = uri.hostname # => "jsonplaceholder.typicode.com"
path = uri.path         # => "/"
port = uri.port         # => 443

以便可以将示例请求编写为

Net::HTTP.get(uri)
Net::HTTP.get(hostname, '/index.html')
Net::HTTP.start(hostname) do |http|
  http.get('/todos/1')
  http.get('/todos/2')
end

需要修改 URI 的示例首先复制 uri，然后修改副本

_uri = uri.dup
_uri.path = '/todos/1'

策略¶ ↑

如果您只发出少量 GET 请求，请考虑使用 OpenURI。

如果您只发出少量各种类型的请求，请考虑使用此类中的各种单例便捷方法。以下每个方法都会自动启动并完成一个会话，该会话发送单个请求

# Return string response body.
Net::HTTP.get(hostname, path)
Net::HTTP.get(uri)

# Write string response body to $stdout.
Net::HTTP.get_print(hostname, path)
Net::HTTP.get_print(uri)

# Return response as Net::HTTPResponse object.
Net::HTTP.get_response(hostname, path)
Net::HTTP.get_response(uri)
data = '{"title": "foo", "body": "bar", "userId": 1}'
Net::HTTP.post(uri, data)
params = {title: 'foo', body: 'bar', userId: 1}
Net::HTTP.post_form(uri, params)
data = '{"title": "foo", "body": "bar", "userId": 1}'
Net::HTTP.put(uri, data)

如果性能很重要，请考虑使用会话，这会降低请求开销。此会话具有用于 HTTP 方法和 WebDAV 方法的多个请求

Net::HTTP.start(hostname) do |http|
  # Session started automatically before block execution.
  http.get(path)
  http.head(path)
  body = 'Some text'
  http.post(path, body)  # Can also have a block.
  http.put(path, body)
  http.delete(path)
  http.options(path)
  http.trace(path)
  http.patch(path, body) # Can also have a block.
  http.copy(path)
  http.lock(path, body)
  http.mkcol(path, body)
  http.move(path)
  http.propfind(path, body)
  http.proppatch(path, body)
  http.unlock(path, body)
  # Session finished automatically at block exit.
end

上面引用的方法是便捷方法，它们通过其少量参数，允许对请求进行最小的控制。为了更好地控制，请考虑使用请求对象。

URI¶ ↑

在互联网上，URI（统一资源标识符）是一个字符串，用于标识特定的资源。它由以下部分或全部组成：方案、主机名、路径、查询和片段；请参阅 URI 语法。

Ruby URI::Generic 对象表示互联网 URI。它提供了 scheme、hostname、path、query 和 fragment 等方法。

方案¶ ↑

互联网 URI 具有方案。

Net::HTTP 中支持的两个方案是 'https' 和 'http'

uri.scheme                       # => "https"
URI('http://example.com').scheme # => "http"

主机名¶ ↑

主机名标识可以向其发送请求的服务器（主机）

hostname = uri.hostname # => "jsonplaceholder.typicode.com"
Net::HTTP.start(hostname) do |http|
  # Some HTTP stuff.
end

路径¶ ↑

主机特定的路径标识主机上的资源

_uri = uri.dup
_uri.path = '/todos/1'
hostname = _uri.hostname
path = _uri.path
Net::HTTP.get(hostname, path)

查询¶ ↑

主机特定的查询向 URI 添加名称/值对

_uri = uri.dup
params = {userId: 1, completed: false}
_uri.query = URI.encode_www_form(params)
_uri # => #<URI::HTTPS https://jsonplaceholder.typicode.com?userId=1&completed=false>
Net::HTTP.get(_uri)

片段¶ ↑

URI 片段在 Net::HTTP 中不起作用；无论是否包含片段，都会返回相同的数据。

请求标头¶ ↑

请求标头可用于将附加信息传递给主机，类似于在方法调用中传递的参数；每个标头都是名称/值对。

将请求发送到主机的每个 Net::HTTP 方法都有可选参数 headers，其中标头表示为字段名称/值对的哈希

headers = {Accept: 'application/json', Connection: 'Keep-Alive'}
Net::HTTP.get(uri, headers)

请参阅请求字段中的标准请求字段和常见请求字段列表。主机也可能接受其他自定义字段。

HTTP 会话¶ ↑

会话是服务器（主机）和客户端之间的连接，该连接

由实例方法 Net::HTTP#start 开始。
可能包含任意数量的请求。
由实例方法 Net::HTTP#finish 结束。

请参阅策略中的示例会话。

使用 Net::HTTP.start 的会话¶ ↑

如果您需要向单个主机（和端口）发出多个请求，请考虑使用带有块的单例方法 Net::HTTP.start；该方法通过以下方式自动处理会话

在块执行之前调用 start。
执行块。
在块执行之后调用 finish。

在块中，您可以使用以下实例方法，每个方法都会发送单个请求

HTTP 方法:
- get, request_get: GET。
- head, request_head: HEAD。
- post, request_post: POST。
- delete: DELETE。
- options: OPTIONS。
- trace: TRACE。
- patch: PATCH。
WebDAV 方法:
- copy: COPY。
- lock: LOCK。
- mkcol: MKCOL。
- move: MOVE。
- propfind: PROPFIND。
- proppatch: PROPPATCH。
- unlock: UNLOCK。

使用 Net::HTTP.start 和 Net::HTTP.finish 的会话¶ ↑

您可以使用 start 和 finish 方法手动管理会话

http = Net::HTTP.new(hostname)
http.start
http.get('/todos/1')
http.get('/todos/2')
http.delete('/posts/1')
http.finish # Needed to free resources.

单请求会话¶ ↑

某些便捷方法通过以下方式自动处理会话

创建 HTTP 对象
启动会话。
发送单个请求。
完成会话。
销毁对象。

发送 GET 请求的此类方法

::get：返回字符串响应正文。
::get_print：将字符串响应正文写入 $stdout。
::get_response：返回 Net::HTTPResponse 对象。

发送 POST 请求的此类方法

::post：将数据发布到主机。
::post_form：将表单数据发布到主机。

HTTP 请求和响应¶ ↑

上面的许多方法都是便捷方法，每个方法都会发送一个请求并返回一个字符串，而无需直接使用 Net::HTTPRequest 和 Net::HTTPResponse 对象。

但是，您可以直接创建一个请求对象，发送请求并检索响应对象；请参阅

跟踪重定向¶ ↑

每个返回的响应都是 Net::HTTPResponse 子类的实例。请参阅响应类层次结构。

特别是，类 Net::HTTPRedirection 是所有重定向类的父类。这允许您制作一个 case 语句来正确处理重定向

def fetch(uri, limit = 10)
  # You should choose a better exception.
  raise ArgumentError, 'Too many HTTP redirects' if limit == 0

  res = Net::HTTP.get_response(URI(uri))
  case res
  when Net::HTTPSuccess     # Any success class.
    res
  when Net::HTTPRedirection # Any redirection class.
    location = res['Location']
    warn "Redirected to #{location}"
    fetch(location, limit - 1)
  else                      # Any other class.
    res.value
  end
end

fetch(uri)

基本身份验证¶ ↑

基本身份验证是根据 RFC2617 执行的

req = Net::HTTP::Get.new(uri)
req.basic_auth('user', 'pass')
res = Net::HTTP.start(hostname) do |http|
  http.request(req)
end

流式响应正文¶ ↑

默认情况下，Net::HTTP 会将整个响应读取到内存中。如果要处理大文件或希望实现进度条，则可以将正文直接流式传输到 IO。

Net::HTTP.start(hostname) do |http|
  req = Net::HTTP::Get.new(uri)
  http.request(req) do |res|
    open('t.tmp', 'w') do |f|
      res.read_body do |chunk|
        f.write chunk
      end
    end
  end
end

HTTPS¶ ↑

通过 Net::HTTP#use_ssl= 为 HTTP 连接启用 HTTPS

Net::HTTP.start(hostname, :use_ssl => true) do |http|
  req = Net::HTTP::Get.new(uri)
  res = http.request(req)
end

或者，如果您只想发出 GET 请求，则可以传入一个具有 HTTPS URL 的 URI 对象。如果 URI 对象具有 'https' URI 方案，则 Net::HTTP 会自动开启 TLS 验证

uri # => #<URI::HTTPS https://jsonplaceholder.typicode.com/>
Net::HTTP.get(uri)

代理服务器¶ ↑

HTTP 对象可以具有代理服务器。

您可以使用方法 Net::HTTP.new 或方法 Net::HTTP.start 创建具有代理服务器的 HTTP 对象。

可以使用参数 p_addr 或环境变量 'http_proxy' 定义代理。

使用参数 `p_addr` 作为字符串的代理¶ ↑

当参数 p_addr 是字符串主机名时，返回的 http 将具有给定主机作为其代理

http = Net::HTTP.new(hostname, nil, 'proxy.example')
http.proxy?          # => true
http.proxy_from_env? # => false
http.proxy_address   # => "proxy.example"
# These use default values.
http.proxy_port      # => 80
http.proxy_user      # => nil
http.proxy_pass      # => nil

还可以提供代理的端口、用户名和密码

http = Net::HTTP.new(hostname, nil, 'proxy.example', 8000, 'pname', 'ppass')
# => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false>
http.proxy?          # => true
http.proxy_from_env? # => false
http.proxy_address   # => "proxy.example"
http.proxy_port      # => 8000
http.proxy_user      # => "pname"
http.proxy_pass      # => "ppass"

使用 '`ENV['http_proxy']`' 的代理¶ ↑

当环境变量 'http_proxy' 设置为 URI 字符串时，返回的 http 将以该 URI 中的服务器作为其代理；请注意，URI 字符串必须具有诸如 'http' 或 'https' 之类的协议

ENV['http_proxy'] = 'http://example.com'
http = Net::HTTP.new(hostname)
http.proxy?          # => true
http.proxy_from_env? # => true
http.proxy_address   # => "example.com"
# These use default values.
http.proxy_port      # => 80
http.proxy_user      # => nil
http.proxy_pass      # => nil

URI 字符串可以包含代理用户名、密码和端口号

ENV['http_proxy'] = 'http://pname:ppass@example.com:8000'
http = Net::HTTP.new(hostname)
http.proxy?          # => true
http.proxy_from_env? # => true
http.proxy_address   # => "example.com"
http.proxy_port      # => 8000
http.proxy_user      # => "pname"
http.proxy_pass      # => "ppass"

筛选代理¶ ↑

使用方法 Net::HTTP.new（而不是 Net::HTTP.start），您可以使用参数 p_no_proxy 来筛选代理

拒绝某个地址

http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example')
http.proxy_address # => nil

拒绝某些域或子域

http = Net::HTTP.new('example.com', nil, 'my.proxy.example', 8000, 'pname', 'ppass', 'proxy.example')
http.proxy_address # => nil

拒绝某些地址和端口组合

http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:1234')
http.proxy_address # => "proxy.example"

http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:8000')
http.proxy_address # => nil

拒绝使用逗号分隔的上述类型的列表

http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'my.proxy,proxy.example:8000')
http.proxy_address # => nil

http = Net::HTTP.new('example.com', nil, 'my.proxy', 8000, 'pname', 'ppass', 'my.proxy,proxy.example:8000')
http.proxy_address # => nil

压缩和解压缩¶ ↑

Net::HTTP 在发送之前不会压缩请求的正文。

默认情况下，Net::HTTP 会将标头 'Accept-Encoding' 添加到新的请求对象

Net::HTTP::Get.new(uri)['Accept-Encoding']
# => "gzip;q=1.0,deflate;q=0.6,identity;q=0.3"

这会请求服务器压缩响应正文（如果有的话）；服务器并非必须这样做。

如果响应具有标头 'Content-Range'，则 Net::HTTP 不会自动解压缩响应正文。

否则，解压缩（或不解压缩）取决于标头 Content-Encoding 的值

'deflate'、'gzip' 或 'x-gzip'：解压缩正文并删除标头。
'none' 或 'identity'：不解压缩正文，但删除标头。
任何其他值：保持正文和标头不变。

这里有什么¶ ↑

首先，看看其他地方。Class Net::HTTP

继承自 class Object。

这是方法和属性的分类摘要。

Net::HTTP 对象¶ ↑

::new: 创建一个新的实例。
#inspect: 返回 self 的字符串表示形式。

会话¶ ↑

::start: 在一个新的 Net::HTTP 对象中开始一个新的会话。
#started?: 返回是否在会话中。
#finish: 结束活动会话。
#start: 在现有的 Net::HTTP 对象 (self) 中开始一个新的会话。

连接¶ ↑

:continue_timeout: 返回 continue 超时时间。
#continue_timeout=: 设置 continue 超时秒数。
:keep_alive_timeout: 返回 keep-alive 超时时间。
:keep_alive_timeout=: 设置 keep-alive 超时时间。
:max_retries: 返回最大重试次数。
#max_retries=: 设置最大重试次数。
:open_timeout: 返回打开超时时间。
:open_timeout=: 设置打开超时时间。
:read_timeout: 返回打开超时时间。
:read_timeout=: 设置读取超时时间。
:ssl_timeout: 返回 ssl 超时时间。
:ssl_timeout=: 设置 ssl 超时时间。
:write_timeout: 返回写入超时时间。
write_timeout=: 设置写入超时时间。

请求¶ ↑

::get: 发送 GET 请求并返回字符串响应体。
::get_print: 发送 GET 请求并将字符串响应体写入 $stdout。
::get_response: 发送 GET 请求并返回响应对象。
::post_form: 发送带有表单数据的 POST 请求并返回响应对象。
::post: 发送带有数据的 POST 请求并返回响应对象。
::put: 发送带有数据的 PUT 请求并返回响应对象。
#copy: 发送 COPY 请求并返回响应对象。
#delete: 发送 DELETE 请求并返回响应对象。
#get: 发送 GET 请求并返回响应对象。
#head: 发送 HEAD 请求并返回响应对象。
#lock: 发送 LOCK 请求并返回响应对象。
#mkcol: 发送 MKCOL 请求并返回响应对象。
#move: 发送 MOVE 请求并返回响应对象。
#options: 发送 OPTIONS 请求并返回响应对象。
#patch: 发送 PATCH 请求并返回响应对象。
#post: 发送 POST 请求并返回响应对象。
#propfind: 发送 PROPFIND 请求并返回响应对象。
#proppatch: 发送 PROPPATCH 请求并返回响应对象。
#put: 发送 PUT 请求并返回响应对象。
#request: 发送请求并返回响应对象。
#request_get: 发送 GET 请求并生成一个响应对象；如果给定了代码块，则使用该对象调用该代码块，否则返回该对象。
#request_head: 发送 HEAD 请求并生成一个响应对象；如果给定了代码块，则使用该对象调用该代码块，否则返回该对象。
#request_post: 发送 POST 请求并生成一个响应对象；如果给定了代码块，则使用该对象调用该代码块，否则返回该对象。
#send_request: 发送请求并返回响应对象。
#trace: 发送 TRACE 请求并返回响应对象。
#unlock: 发送 UNLOCK 请求并返回响应对象。

响应¶ ↑

:close_on_empty_response: 返回是否在空响应时关闭连接。
:close_on_empty_response=: 设置是否在空响应时关闭连接。
:ignore_eof: 返回在使用 Content-Length 标头读取响应体时是否忽略文件结束符。
:ignore_eof=: 设置在使用 Content-Length 标头读取响应体时是否忽略文件结束符。
:response_body_encoding: 返回用于响应体的编码。
#response_body_encoding=: 设置响应体编码。

代理¶ ↑

:proxy_address: 返回代理地址。
:proxy_address=: 设置代理地址。
::proxy_class?: 返回 self 是否为代理类。
#proxy?: 返回 self 是否有代理。
#proxy_address: 返回代理地址。
#proxy_from_env?: 返回是否从环境变量中获取代理。
:proxy_from_env=: 设置是否从环境变量中获取代理。
:proxy_pass: 返回代理密码。
:proxy_pass=: 设置代理密码。
:proxy_port: 返回代理端口。
:proxy_port=: 设置代理端口。
#proxy_user: 返回代理用户名。
:proxy_user=: 设置代理用户。

安全¶ ↑

:ca_file: 返回 CA 证书文件的路径。
:ca_file=: 设置 CA 证书文件的路径。
:ca_path: 返回包含证书文件的 CA 目录的路径。
:ca_path=: 设置包含证书文件的 CA 目录的路径。
:cert: 返回用于客户端证书的 OpenSSL::X509::Certificate 对象。
:cert=: 设置用于客户端证书的 OpenSSL::X509::Certificate 对象。
:cert_store: 返回用于验证对等证书的 X509::Store。
:cert_store=: 设置用于验证对等证书的 X509::Store。
:ciphers: 返回可用的 SSL 密码。
:ciphers=: 设置可用的 SSL 密码。
:extra_chain_cert: 返回要添加到证书链中的额外 X509 证书。
:extra_chain_cert=: 设置要添加到证书链中的额外 X509 证书。
:key: 返回 OpenSSL::PKey::RSA 或 OpenSSL::PKey::DSA 对象。
:key=: 设置 OpenSSL::PKey::RSA 或 OpenSSL::PKey::DSA 对象。
:max_version: 返回最大 SSL 版本。
:max_version=: 设置最大 SSL 版本。
:min_version: 返回最小 SSL 版本。
:min_version=: 设置最小 SSL 版本。
#peer_cert: 返回会话套接字对等方的 X509 证书链。
:ssl_version: 返回 SSL 版本。
:ssl_version=: 设置 SSL 版本。
#use_ssl=: 设置新会话是否使用传输层安全协议。
#use_ssl?: 返回 self 是否使用 SSL。
:verify_callback: 返回服务器证书验证的回调。
:verify_callback=: 设置服务器证书验证的回调。
:verify_depth: 返回证书链验证的最大深度。
:verify_depth=: 设置证书链验证的最大深度。
:verify_hostname: 返回在 SSL/TLS 会话开始时用于服务器证书验证的标志。
:verify_hostname=: 设置在 SSL/TLS 会话开始时用于服务器证书验证的标志。
:verify_mode: 返回在 SSL/TLS 会话开始时用于服务器证书验证的标志。
:verify_mode=: 设置在 SSL/TLS 会话开始时用于服务器证书验证的标志。

地址和端口¶ ↑

:address: 返回字符串主机名或主机 IP。
::default_port: 返回整数 80，用于 HTTP 请求的默认端口。
::http_default_port: 返回整数 80，用于 HTTP 请求的默认端口。
::https_default_port: 返回整数 443，用于 HTTPS 请求的默认端口。
#ipaddr: 返回连接的 IP 地址。
#ipaddr=: 设置连接的 IP 地址。
:local_host: 返回用于建立连接的字符串本地主机。
:local_host=: 设置用于建立连接的字符串本地主机。
:local_port: 返回用于建立连接的整数本地端口。
:local_port=: 设置用于建立连接的整数本地端口。
:port: 返回整数端口号。

HTTP 版本¶ ↑

::version_1_2? (别名为 ::version_1_2): 返回 true；保留以实现兼容性。

调试¶ ↑

#set_debug_output: 设置调试的输出流。

模块 Net

关于示例¶ ↑

策略¶ ↑

URI¶ ↑

方案¶ ↑

主机名¶ ↑

路径¶ ↑

查询¶ ↑

片段¶ ↑

请求标头¶ ↑

HTTP 会话¶ ↑

使用 Net::HTTP.start 的会话¶ ↑

使用 Net::HTTP.start 和 Net::HTTP.finish 的会话¶ ↑

单请求会话¶ ↑

HTTP 请求和响应¶ ↑

跟踪重定向¶ ↑

基本身份验证¶ ↑

流式响应正文¶ ↑

HTTPS¶ ↑

代理服务器¶ ↑

使用参数 p_addr 作为字符串的代理¶ ↑

使用 'ENV['http_proxy']' 的代理¶ ↑

筛选代理¶ ↑

压缩和解压缩¶ ↑

这里有什么¶ ↑

Net::HTTP 对象¶ ↑

会话¶ ↑

连接¶ ↑

请求¶ ↑

响应¶ ↑

代理¶ ↑

安全¶ ↑

地址和端口¶ ↑

HTTP 版本¶ ↑

调试¶ ↑

使用参数 `p_addr` 作为字符串的代理¶ ↑

使用 '`ENV['http_proxy']`' 的代理¶ ↑