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.new や Net::HTTP.start の proxy_addr 引数に nil を渡してください。

Net::HTTP.new や Net::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::HTTPResponse、 Net::HTTPSuccess、 Net::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 を受け取ったという例外です。