library net/http

要約

汎用データ転送プロトコル HTTP を扱うライブラリです。実装は [RFC2616] に基きます。

使用例

ウェブサーバからドキュメントを得る (GET)

例1: GET して 表示するだけ

require 'net/http'
Net::HTTP.get_print 'www.example.com', '/index.html'

例2: URI を使う

require 'net/http'
require 'uri'
Net::HTTP.get_print URI.parse('http://www.example.com/index.html')

例3: より汎用的な例

require 'net/http'
require 'uri'

url = URI.parse('http://www.example.com/index.html')
res = Net::HTTP.start(url.host, url.port) {|http|
  http.get('/index.html')
}
puts res.body

例4: 上の例よりさらに汎用的な例

require 'net/http'

url = URI.parse('http://www.example.com/index.html')
req = Net::HTTP::Get.new(url.path)
res = Net::HTTP.start(url.host, url.port) {|http|
  http.request(req)
}
puts res.body

フォームの情報を送信する (POST)

require 'net/http'
require 'uri'

#例1: POSTするだけ
res = Net::HTTP.post_form(URI.parse('http://www.example.com/search'),
                          {'q'=>'ruby', 'max'=>'50'})
puts res.body

#例2: 認証付きで POST する
res = Net::HTTP.post_form(URI.parse('http://jack:pass@www.example.com/todo.cgi'),
                          {'from'=>'2005-01-01', 'to'=>'2005-03-31'})
puts res.body

#例3: より細かく制御する
url = URI.parse('http://www.example.com/todo.cgi')
req = Net::HTTP::Post.new(url.path)
req.basic_auth 'jack', 'pass'
req.set_form_data({'from'=>'2005-01-01', 'to'=>'2005-03-31'}, ';')
res = Net::HTTP.new(url.host, url.port).start {|http| http.request(req) }
case res
when Net::HTTPSuccess, Net::HTTPRedirection
  # OK
else
  res.value
end

プロクシ経由のアクセス

Net::HTTP は http_proxy 環境変数が存在するならば自動的にその URI を利用してプロクシを利用します。http_proxyを利用したくないならば Net::HTTP.newNet::HTTP.start の proxy_addr 引数に nil を渡してください。

Net::HTTP.newNet::HTTP.start の proxy_addr や proxy_port を指定することでプログラムからプロクシを指定することもできます。

require 'net/http'

proxy_addr = 'your.proxy.host'
proxy_port = 8080

Net::HTTP.new('example.com', nil, proxy_addr, proxy_port).start { |http|
  # always proxy via your.proxy.addr:8080
}

プロクシの認証をユーザ名とパスワードですることもできます。詳しくは Net::HTTP.new を参照してください。

リダイレクトに対応する

以下の例の fetch はリダイレクトに対応しています。 limit 回数以上リダイレクトしたらエラーにします。

require 'net/http'
require 'uri'

def fetch(uri_str, limit = 10)
  # You should choose better exception.
  raise ArgumentError, 'HTTP redirect too deep' if limit == 0

  response = Net::HTTP.get_response(URI.parse(uri_str))
  case response
  when Net::HTTPSuccess
    response
  when Net::HTTPRedirection
    fetch(response['location'], limit - 1)
  else
    response.value
  end
end

print fetch('http://www.example.org')

より詳しくは Net::HTTPResponseNet::HTTPSuccessNet::HTTPRedirection を参照してください。

Basic 認証

require 'net/http'

Net::HTTP.start('www.example.com') {|http|
  req = Net::HTTP::Get.new('/secret-page.html')
  req.basic_auth 'account', 'password'
  response = http.request(req)
  print response.body
}

フォームの値の区切り文字について

POSTで application/x-www-form-urlencoded として複数のフォームの値を送る場合、現在広く行なわれているのは、 name0=value0&name1=value1 のようにアンパサンド (`&') で区切るやりかたです。この方法は、[RFC1866] Hypertext Markup Language - 2.0 で初めて公式に登場し、 HTML 4.01 Specification の 17.13.4 Form content types でもそのように書かれています。

ところが、同じ HTML 4.01 Specification の B.2.2 Ampersands in URI attribute values では、この `&' がSGMLの文字実体参照で用いられることが指摘されており、 CGIやサーバの実装者に対し `&' の代わりにセミコロン `;' をサポートすることを奨めています。

しかし、実際には `;' を解釈しないCGIやサーバもまだまだ見受けられるためこのリファレンスマニュアルでは例として `&' を用いました。

なお Ruby 標準の cgi ライブラリでは '&' と ';' の両方サポートしていますので、 cgi ライブラリを使って CGI スクリプトを書く場合はこれらの違いを気にする必要はありません。

クラス

HTTPSession

Alias of Net::HTTP

Net::HTTP

HTTP のクライアントのためのクラスです。

Net::HTTPGenericRequest

Net::HTTPRequest のスーパークラスです。このクラスは直接は使わないでください。

  Net::HTTPRequest

HTTP リクエストを抽象化するクラスです。

   Net::HTTP::Copy

HTTP の COPY リクエストを表すクラスです。

   Net::HTTP::Delete

HTTP の DELETE リクエストを表すクラスです。

   Net::HTTP::Get

HTTP の GET リクエストを表すクラスです。

   Net::HTTP::Head

HTTP の HEAD リクエストを表すクラスです。

   Net::HTTP::Lock

HTTP の LOCK リクエストを表すクラスです。

   Net::HTTP::Mkcol

HTTP の MKCOL リクエストを表すクラスです。

   Net::HTTP::Move

HTTP の MOVE リクエストを表すクラスです。

   Net::HTTP::Options

HTTP の OPTIONS リクエストを表すクラスです。

   Net::HTTP::Patch

HTTP の PATCH リクエストを表すクラスです。

   Net::HTTP::Post

HTTP の POST リクエストを表すクラスです。

   Net::HTTP::Propfind

HTTP の PROPFIND リクエストを表すクラスです。

   Net::HTTP::Proppatch

HTTP の PROPPATCH リクエストを表すクラスです。

   Net::HTTP::Put

HTTP の PUT リクエストを表すクラスです。

   Net::HTTP::Trace

HTTP の TRACE リクエストを表すクラスです。

   Net::HTTP::Unlock

HTTP の UNLOCK リクエストを表すクラスです。

Net::HTTPResponse

HTTP レスポンスを表現するクラスです。 Net::HTTP クラスは実際には HTTPResponse のサブクラスを返します。

  Net::HTTPClientError

HTTP レスポンス 4xx (Client Error) を表現するクラスです。

   Net::HTTPBadRequest

HTTP レスポンス 400 (Bad Request) を表現するクラスです。

   Net::HTTPConflict

HTTP レスポンス 409 (Conflict) を表現するクラスです。

   Net::HTTPExpectationFailed

HTTP レスポンス 417 (Expectation Failed) を表現するクラスです。

   Net::HTTPFailedDependency

HTTP レスポンス 424 (Failed Dependency) を表現するクラスです。

   Net::HTTPForbidden

HTTP レスポンス 403 (Forbidden) を表現するクラスです。

   Net::HTTPGone

HTTP レスポンス 410 (Gone) を表現するクラスです。

   Net::HTTPLengthRequired

HTTP レスポンス 411 (Length Required) を表現するクラスです。

   Net::HTTPLocked

HTTP レスポンス 423 (Locked) を表現するクラスです。

   Net::HTTPMethodNotAllowed

HTTP レスポンス 405 (Method Not Allowed) を表現するクラスです。

   Net::HTTPNotAcceptable

HTTP レスポンス 406 (Not Acceptable) を表現するクラスです。

   Net::HTTPNotFound

HTTP レスポンス 404 (Not Found) を表現するクラスです。

   Net::HTTPPaymentRequired

HTTP レスポンス 402 (Payment Required) を表現するクラスです。

   Net::HTTPPreconditionFailed

HTTP レスポンス 412 (Precondition Failed) を表現するクラスです。

   Net::HTTPPreconditionRequired

HTTP レスポンス 428 (Precondition Required) を表現するクラスです。

   Net::HTTPProxyAuthenticationRequired

HTTP レスポンス 407 (Proxy Authentication Required) を表現するクラスです。

   Net::HTTPRequestEntityTooLarge

HTTP レスポンス 413 (Payload Too Large) を表現するクラスです。

   Net::HTTPRequestHeaderFieldsTooLarge

HTTP レスポンス 431 (Request Header Fields Too Large) を表現するクラスです。

   Net::HTTPRequestTimeOut

HTTP レスポンス 408 (Request Timeout) を表現するクラスです。

   Net::HTTPRequestURITooLarge

Alias of Net::HTTPRequestURITooLong

   Net::HTTPRequestURITooLong

HTTP レスポンス 414 (URI Too Large) を表現するクラスです。

   Net::HTTPRequestedRangeNotSatisfiable

HTTP レスポンス 416 (Range Not Satisfiable) を表現するクラスです。

   Net::HTTPTooManyRequests

HTTP レスポンス 429 (Too Many Requests) を表現するクラスです。

   Net::HTTPUnauthorized

HTTP レスポンス 401 (Unauthorized) を表現するクラスです。

   Net::HTTPUnavailableForLegalReasons

HTTP レスポンス 451 (Unavailable For Legal Reasons) を表現するクラスです。

   Net::HTTPUnprocessableEntity

HTTP レスポンス 422 (Unprocessable Entity) を表現するクラスです。

   Net::HTTPUnsupportedMediaType

HTTP レスポンス 415 (Unsupported Media Type) を表現するクラスです。

   Net::HTTPUpgradeRequired

HTTP レスポンス 426 (Upgrade Required) を表現するクラスです。

  Net::HTTPInformation

HTTP レスポンス 1xx (Informational) を表現するクラスです。

   Net::HTTPContinue

HTTP レスポンス 100 (Continue) を表現するクラスです。

   Net::HTTPSwitchProtocol

HTTP レスポンス 101 (Switching Protocols) を表現するクラスです。

  Net::HTTPRedirection

HTTP レスポンス 3xx (Redirection) を表現するクラスです。

   Net::HTTPFound

HTTP レスポンス 302 (Found) を表現するクラスです。

   Net::HTTPMovedPermanently

HTTP レスポンス 301 (Moved Permanently) を表現するクラスです。

   Net::HTTPMovedTemporarily

Alias of Net::HTTPFound

   Net::HTTPMultipleChoice

Alias of Net::HTTPMultipleChoices

   Net::HTTPMultipleChoices

HTTP レスポンス 300 (Multiple Choices) を表現するクラスです。

   Net::HTTPNotModified

HTTP レスポンス 304 (Not Modified) を表現するクラスです。

   Net::HTTPPermanentRedirect

HTTP レスポンス 308 (Permanent Redirect) を表現するクラスです。

   Net::HTTPSeeOther

HTTP レスポンス 303 (See Other) を表現するクラスです。

   Net::HTTPTemporaryRedirect

HTTP レスポンス 307 (Temporary Redirect) を表現するクラスです。

   Net::HTTPUseProxy

HTTP レスポンス 305 (Use Proxy) を表現するクラスです。

  Net::HTTPServerError

HTTP レスポンス 5xx (Server Error) を表現するクラスです。

   Net::HTTPBadGateway

HTTP レスポンス 502 (Bad Gateway) を表現するクラスです。

   Net::HTTPGatewayTimeOut

HTTP レスポンス 504 (Gateway Timeout) を表現するクラスです。

   Net::HTTPInsufficientStorage

HTTP レスポンス 507 (Insufficient Storage) を表現するクラスです。

   Net::HTTPInternalServerError

HTTP レスポンス 500 (Internal Server Error) を表現するクラスです。

   Net::HTTPNetworkAuthenticationRequired

HTTP レスポンス 511 (Network Authentication Required) を表現するクラスです。

   Net::HTTPNotImplemented

HTTP レスポンス 501 (Not Implemented) を表現するクラスです。

   Net::HTTPServiceUnavailable

HTTP レスポンス 503 (Service Unavailable) を表現するクラスです。

   Net::HTTPVersionNotSupported

HTTP レスポンス 505 (HTTP Version not supported) を表現するクラスです。

  Net::HTTPSuccess

HTTP レスポンス 2xx (Success) を表現するクラスです。

   Net::HTTPAccepted

HTTP レスポンス 202 (Accepted) を表現するクラスです。

   Net::HTTPCreated

HTTP レスポンス 201 (Created) を表現するクラスです。

   Net::HTTPIMUsed

HTTP レスポンス 226 (IM Used) を表現するクラスです。

   Net::HTTPMultiStatus

HTTP レスポンス 207 (Multi-Status) を表現するクラスです。

   Net::HTTPNoContent

HTTP レスポンス 204 (No Content) を表現するクラスです。

   Net::HTTPNonAuthoritativeInformation

HTTP レスポンス 203 (Non-Authoritative Information) を表現するクラスです。

   Net::HTTPOK

HTTP レスポンス 200 (OK) を表現するクラスです。

   Net::HTTPPartialContent

HTTP レスポンス 206 (Partial Content) を表現するクラスです。

   Net::HTTPResetContent

HTTP レスポンス 205 (Reset Content) を表現するクラスです。

  Net::HTTPUnknownResponse

このライブラリが知らないレスポンスを表現するクラスです。

モジュール

Net::HTTPExceptions

HTTP 例外クラスです。

Net::HTTPHeader

HTTP ヘッダのためのモジュールです。

例外クラス

Net::HTTPBadResponse

HTTP のレスポンスが不正であった場合に発生する例外です。

Net::HTTPHeaderSyntaxError

HTTP ヘッダの内容が不正である場合に発生する例外です。

Net::HTTPError

HTTP ステータスコード 1xx を受け取ったという例外です。または、ステータスコードが未知のものである場合もこれに対応します。

Net::HTTPFatalError

HTTP ステータスコード 5xx を受け取ったという例外です。

Net::HTTPRetriableError

HTTP ステータスコード 3xx を受け取ったという例外です。

Net::HTTPServerException

HTTP ステータスコード 4xx を受け取ったという例外です。