requires=
classes=Net=HTTP,HTTPSession,Net=HTTPHeader,Net=HTTPGenericRequest,Net=HTTPRequest,Net=HTTP=Head,Net=HTTP=Get,Net=HTTP=Post,Net=HTTP=Put,Net=HTTP=Copy,Net=HTTP=Delete,Net=HTTP=Lock,Net=HTTP=Mkcol,Net=HTTP=Move,Net=HTTP=Options,Net=HTTP=Propfind,Net=HTTP=Proppatch,Net=HTTP=Trace,Net=HTTP=Unlock,Net=HTTPResponse,Net=HTTPUnknownResponse,Net=HTTPInformation,Net=HTTPSuccess,Net=HTTPRedirection,Net=HTTPClientError,Net=HTTPServerError,Net=HTTPContinue,Net=HTTPSwitchProtocol,Net=HTTPOK,Net=HTTPCreated,Net=HTTPAccepted,Net=HTTPNonAuthoritativeInformation,Net=HTTPNoContent,Net=HTTPResetContent,Net=HTTPPartialContent,Net=HTTPMultipleChoice,Net=HTTPMovedPermanently,Net=HTTPFound,Net=HTTPMovedTemporarily,Net=HTTPSeeOther,Net=HTTPNotModified,Net=HTTPUseProxy,Net=HTTPTemporaryRedirect,Net=HTTPBadRequest,Net=HTTPUnauthorized,Net=HTTPPaymentRequired,Net=HTTPForbidden,Net=HTTPNotFound,Net=HTTPMethodNotAllowed,Net=HTTPNotAcceptable,Net=HTTPProxyAuthenticationRequired,Net=HTTPRequestTimeOut,Net=HTTPConflict,Net=HTTPGone,Net=HTTPLengthRequired,Net=HTTPPreconditionFailed,Net=HTTPRequestEntityTooLarge,Net=HTTPRequestURITooLong,Net=HTTPRequestURITooLarge,Net=HTTPUnsupportedMediaType,Net=HTTPRequestedRangeNotSatisfiable,Net=HTTPExpectationFailed,Net=HTTPInternalServerError,Net=HTTPNotImplemented,Net=HTTPBadGateway,Net=HTTPServiceUnavailable,Net=HTTPGatewayTimeOut,Net=HTTPVersionNotSupported,Net=HTTPExceptions,Net=HTTPError,Net=HTTPRetriableError,Net=HTTPServerException,Net=HTTPFatalError,Net=HTTPBadResponse,Net=HTTPHeaderSyntaxError
methods=
sublibraries=
is_sublibrary=false
category=Network

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

=== 使用例

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

例1: GET して 表示するだけ
  require 'net/http'
  Net::HTTP.get_print 'www.example.com', '/index.html'

例2: [[c: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

==== プロクシ経由のアクセス

[[m:Net::HTTP.Proxy]] はプロクシ経由での接続を行なうクラスを
生成して返します。このクラスは [[c:Net::HTTP]] と同じ
メソッドを持ち、同じように動作をします。ただし
接続する際には常にプロクシ経由となります。
  require 'net/http'
  
  proxy_addr = 'your.proxy.host'
  proxy_port = 8080
          :
  Net::HTTP::Proxy(proxy_addr, proxy_port).start('www.example.com') {|http|
    # always connect to your.proxy.addr:8080
          :
  }

また [[m:Net::HTTP.Proxy]] は第一引数が nil だと 
Net::HTTP 自身を返すので
上のコードのように書いておけばプロクシなしの場合にも対応できます。

[[m:Net::HTTP.Proxy]] にはユーザ名とパスワードを取る
オプション引数があり、以下のようにして
プロクシの認証をすることができます。
  proxy_host = 'your.proxy.host'
  proxy_port = 8080
  uri = URI.parse(ENV['http_proxy'])
  proxy_user, proxy_pass = uri.userinfo.split(/:/) if uri.userinfo
  Net::HTTP::Proxy(proxy_host, proxy_port,
                   proxy_user, proxy_pass).start('www.example.com') {|http|
    # always connect to your.proxy.addr:8080 using specified username and password
          :
  }
このライブラリは環境変数 HTTP_PROXY を一切考慮しないこと
に注意してください。プロクシを使いたい場合は上の例のように
明示的に取り扱わなければなりません。

==== リダイレクトに対応する
以下の例の 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')

より詳しくは [[c:Net::HTTPResponse]]、 [[c:Net::HTTPSuccess]]、
[[c: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 のようにアンパサンド
(`&') で区切るやりかたです。
この方法は、[[RFC:1866]] 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 標準の [[lib:cgi]] ライブラリでは '&' と ';' の両方サポートしていますので、
[[lib:cgi]] ライブラリを使って CGI スクリプトを書く場合はこれらの違いを気にする
必要はありません。

=== 新しい仕様への変更と移行措置について

net/http 1.1 の挙動を使いたい場合には[[m:Net::HTTP.version_1_1]] を呼ん
でください。その後 [[m:Net::HTTP.version_1_2]] を呼ぶと挙動が 1.2 に戻
ります。

  # example
  Net::HTTP.start {|http1| ...(http1 has 1.2 features)... }
  
  Net::HTTP.version_1_1
  Net::HTTP.start {|http2| ...(http2 has 1.1 features)... }
  
  Net::HTTP.version_1_2
  Net::HTTP.start {|http3| ...(http3 has 1.2 features)... }

ただし、この機能はスレッドセーフではありません。
つまり、複数スレッドでそれぞれに version_1_1 や version_1_2 を呼んだ場合、
次に生成する Net::HTTP オブジェクトがどちらのバージョンになるかは保証できません。
アプリケーション全体でどちらかのバージョンに固定する必要があります。

通常この機能は使わないはずです。1.2固定で利用してください。
