模块 Gem::Net

常量

HTTPGatewayTimeOut

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

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

参考

HTTPMovedTemporarily

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

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

参考

HTTPMultipleChoice

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

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

参考

HTTPRequestEntityTooLarge

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

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

参考

HTTPRequestTimeOut

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

服务器等待请求超时。

参考

HTTPRequestURITooLarge

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

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

参考

HTTPRequestURITooLong

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

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

参考

HTTPRequestedRangeNotSatisfiable

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

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

参考

HTTPSession

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

关于示例¶ ↑

策略¶ ↑

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

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

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

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

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

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

Gem::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 Gem::URI::Generic 对象表示互联网 URI。它提供了 scheme、hostname、path、query 和 fragment 等方法。

方案¶ ↑

互联网 Gem::URI 有一个方案。

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

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

主机名¶ ↑

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

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

路径¶ ↑

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

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

查询¶ ↑

特定于主机的查询将名称/值对添加到 URI

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

片段¶ ↑

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

请求标头¶ ↑

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

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

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

请参阅请求字段，查看标准请求字段和常用请求字段列表。主机也可能接受其他自定义字段。

HTTP 会话¶ ↑

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

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

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

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

如果您需要向单个主机（和端口）发出许多请求，请考虑使用带有块的单例方法 Gem::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。

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

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

http = Gem::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：返回 Gem::Net::HTTPResponse 对象。

发送 POST 请求的此类方法

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

HTTP 请求和响应¶ ↑

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

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

遵循重定向¶ ↑

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

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

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

  res = Gem::Net::HTTP.get_response(Gem::URI(uri))
  case res
  when Gem::Net::HTTPSuccess     # Any success class.
    res
  when Gem::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 = Gem::Net::HTTP::Get.new(uri)
req.basic_auth('user', 'pass')
res = Gem::Net::HTTP.start(hostname) do |http|
  http.request(req)
end

流式响应正文¶ ↑

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

Gem::Net::HTTP.start(hostname) do |http|
  req = Gem::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¶ ↑

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

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

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

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

代理服务器¶ ↑

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

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

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

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

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

http = Gem::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 = Gem::Net::HTTP.new(hostname, nil, 'proxy.example', 8000, 'pname', 'ppass')
# => #<Gem::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' 设置为 Gem::URI 字符串时，返回的 http 将以该 URI 处的服务器作为其代理；请注意，Gem::URI 字符串必须具有诸如 'http' 或 'https' 之类的协议

ENV['http_proxy'] = 'http://example.com'
http = Gem::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

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

ENV['http_proxy'] = 'http://pname:[email protected]:8000'
http = Gem::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"

筛选代理¶ ↑

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

拒绝某个地址

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

拒绝某些域或子域

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

拒绝某些地址和端口组合

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

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

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

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

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

压缩和解压缩¶ ↑

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

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

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

这会请求服务器在有响应正文的情况下对其进行 zip 编码；服务器不是必须这样做。

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

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

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

这里有什么¶ ↑

首先，其他地方有什么。类 Gem::Net::HTTP

继承自类 Object。

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

Gem::Net::HTTP 对象¶ ↑

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

会话¶ ↑

::start：在新 Gem::Net::HTTP 对象中开始新会话。
#started?（别名为 #active?）：返回是否在会话中。
#finish：结束活动会话。
#start：在现有 Gem::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 (别名为 #get2): 发送 GET 请求并形成响应对象；如果给定块，则使用该对象调用该块，否则返回该对象。
#request_head (别名为 #head2): 发送 HEAD 请求并形成响应对象；如果给定块，则使用该对象调用该块，否则返回该对象。
#request_post (别名为 #post2): 发送 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 (别名为 #proxyaddr): 返回代理地址。
#proxy_from_env?: 返回是否从环境变量获取代理。
:proxy_from_env=: 设置是否从环境变量获取代理。
:proxy_pass: 返回代理密码。
:proxy_pass=: 设置代理密码。
:proxy_port: 返回代理端口。
:proxy_port=: 设置代理端口。
#proxy_user: 返回代理用户名。
:proxy_user=: 设置代理用户。

`Security`¶ ↑

: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`¶ ↑

::version_1_2? (别名为 ::is_version_1_2? 和 ::version_1_2): 返回 true；为兼容性保留。

调试¶ ↑

#set_debug_output: 设置调试输出流。