名前¶

Net::HTTP - 低レベル HTTP 接続 (クライアント)

概要¶

 use Net::HTTP;
 my $s = Net::HTTP->new(Host => "www.perl.com") || die $@;
 $s->write_request(GET => "/", 'User-Agent' => "Mozilla/5.0");
 my($code, $mess, %h) = $s->read_response_headers;

 while (1) {
    my $buf;
    my $n = $s->read_entity_body($buf, 1024);
    die "read failed: $!" unless defined $n;
    last unless $n;
    print $buf;
 }

説明¶

Net::HTTP クラスは低レベル HTTP クライアントです。 一つの Net::HTTP クラスの実体は一つの HTTP サーバへの接続を表現します。 HTTP プロトコルは RFC 2616 に記述されています。 Net::HTTP クラスは HTTP/1.0 と HTTP/1.1 に対応しています。

Net::HTTP は IO::Socket::INET のサブクラスです。 後述するメソッドと、ソケットからの直接の読み書きを混ぜることができます。 これは、何をしようとしているのかを分かっていない限り、いい考えでは ありません。

(IO::Socket::INET のものに加えて)以下のメソッドが提供されます:

$s = Net::HTTP->new( %options )

The Net::HTTP constructor method takes the same options as IO::Socket::INET's as well as these:

Net::HTTP コンストラクタメソッドは IO::Socket::INET と同様 以下のオプションを取ります:

  Host:            Initial host attribute value
  KeepAlive:       Initial keep_alive attribute value
  SendTE:          Initial send_te attribute_value
  HTTPVersion:     Initial http_version attribute value
  PeerHTTPVersion: Initial peer_http_version attribute value
  MaxLineLength:   Initial max_line_length attribute value
  MaxHeaderLines:  Initial max_header_lines attribute value

The Host option is also the default for IO::Socket::INET's PeerAddr. The PeerPort defaults to 80 if not provided.

また、Host オプションはのデフォルトは IO::Socket::INET の PeerAddr です。 PeerPort が提供されなかった場合のデフォルトは 80 です。

The Listen option provided by IO::Socket::INET's constructor method is not allowed.

IO::Socket::INET のコンストラクタメソッドで提供されている Listen オプションは使えません。

If unable to connect to the given HTTP server then the constructor returns undef and $@ contains the reason. After a successful connect, a Net:HTTP object is returned.

指定された HTTP サーバに接続できない場合、コンストラクタは undef を 返し、$@ に理由が入ります。 接続に成功した後は、Net:HTTP オブジェクトが返されます。

$s->host

Get/set the default value of the Host header to send. The $host must not be set to an empty string (or undef) for HTTP/1.1.

送信する Host ヘッダのデフォルト値を取得/設定します。 HTTP/1.1 では $host は空文字列 (あるいは undef)は設定できません。

$s->keep_alive

Get/set the keep-alive value. If this value is TRUE then the request will be sent with headers indicating that the server should try to keep the connection open so that multiple requests can be sent.

keep-alive の値を取得/設定できます。 この値が TRUE の場合、サーバは接続を開いたまま維持しようとするので 複数のリクエストを送ることができることを示すヘッダを付けてリクエストが 送られます。

The actual headers set will depend on the value of the http_version and peer_http_version attributes.

実際のヘッダ集合は http_version と peer_http_version 属性に 依存します。

$s->send_te

Get/set the a value indicating if the request will be sent with a "TE" header to indicate the transfer encodings that the server can choose to use. If the Compress::Zlib module is installed then this will announce that this client accept both the deflate and gzip encodings.

サーバが使うことを選べる転送エンコーディングを示す "TE" ヘッダ付きで リクエストが送られるかどうかを示す値を取得/設定します。 Compress::Zlib モジュールがインストールされている場合は、この クライアントは deflate と gzip のエンコーディングの両方を 受け付けることを通知します。

$s->http_version

Get/set the HTTP version number that this client should announce. This value can only be set to "1.0" or "1.1". The default is "1.1".

クライアントが告げる HTTP のバージョン番号を取得/設定します。 この値は "1.0" か "1.1" だけが設定できます。 デフォルトは "1.1" です。

$s->peer_http_version

Get/set the protocol version number of our peer. This value will initially be "1.0", but will be updated by a successful read_response_headers() method call.

相手のプロトコルバージョン番号を取得/設定します。 この値は最初は "1.0" ですが、read_response_headers() メソッド呼び出しが 成功することで更新されます。

$s->max_line_length

Get/set a limit on the length of response line and response header lines. The default is 4096. A value of 0 means no limit.

レスポンス行とレスポンスヘッダ行の長さの制限を取得/設定できます。 デフォルトは 4096 です。 値 0 は無制限を意味します。

$s->max_header_length

Get/set a limit on the number of headers lines that a response can have. The default is 128. A value of 0 means no limit.

レスポンスがもつことのできるヘッダ行の数の制限を設定/取得します。 デフォルトは 128 です。 値 0 は無制限を意味します。

$s->format_request($method, $uri, %headers, [$content])

Format a request message and return it as a string. If the headers do not include a Host header, then a header is inserted with the value of the host attribute. Headers like Connection and Keep-Alive might also be added depending on the status of the keep_alive attribute.

リクエストメッセージを整形して文字列として返します。 ヘッダに Host がない場合、host 属性の値が挿入されます。 Connection や Keep-Alive のようなヘッダも、 keep_alive 属性の状態によって追加されるかもしれません。

If $content is given (and it is non-empty), then a Content-Length header is automatically added unless it was already present.

$content が指定された (かつ空白でない) 場合、(既にない限り) Content-Length ヘッダが追加されます。

$s->write_request($method, $uri, %headers, [$content])

Format and send a request message. Arguments are the same as for format_request(). Returns true if successful.

リクエストメッセージを整形して送信します。 引数は format_request() と同じです。 成功すると真を返します。

$s->format_chunk( $data )

Returns the string to be written for the given chunk of data.

与えられたデータの塊のために書かれた文字列を返します。

$s->write_chunk($data)

Will write a new chunk of request entity body data. This method should only be used if the Transfer-Encoding header with a value of chunked was sent in the request. Note, writing zero-length data is a no-op. Use the write_chunk_eof() method to signal end of entity body data.

リクエストエンティティボディデータの新しい塊を書き込みます。 このメソッドは Transfer-Encoding ヘッダに chunked を設定したリクエストを 送った場合にのみ使うべきです。 長さ 0 のデータを書き込んでも何も起こらないことに注意してください。 エンティティボディデータの終わりを知らせるには write_chunk_eof() メソッドを 使います。

Returns true if successful.

成功すると真を返します。

$s->format_chunk_eof( %trailers )

Returns the string to be written for signaling EOF when a Transfer-Encoding of chunked is used.

chunked の Transfer-Encoding を使っているときに、EOF を 知らせるために書かれる文字列を返します。

$s->write_chunk_eof( %trailers )

Will write eof marker for chunked data and optional trailers. Note that trailers should not really be used unless is was signaled with a Trailer header.

塊のデータとオプションの末尾につけるヘッダのためにファイル終端マーカを 書き込みます。 末尾に付けるヘッダは実際には Trailer ヘッダで通知されるまで 使われません。

Returns true if successful.

成功すると真を返します。

($code, $mess, %headers) = $s->read_response_headers( %opts )

Read response headers from server and return it. The $code is the 3 digit HTTP status code (see HTTP::Status) and $mess is the textual message that came with it. Headers are then returned as key/value pairs. Since key letter casing is not normalized and the same key can even occur multiple times, assigning these values directly to a hash is not wise. Only the $code is returned if this method is called in scalar context.

サーバからレスポンスヘッダを読み込んで返します。 $code は 3 桁の HTTP ステータスコード (HTTP::Status 参照)、 $mess はそのテキストメッセージです。 それからヘッダがキー/値の組で返されます。 キーの大文字小文字は正規化されず、同じキーが複数回現れる可能性があるので、 これらの値を直接ヘッダに代入することは賢明ではありません。 このメソッドがスカラコンテキストで呼び出されると、$code だけが返されます。

As a side effect this method updates the 'peer_http_version' attribute.

副作用として、このメソッドは 'peer_http_version' 属性を更新します。

Options might be passed in as key/value pairs. There are currently only two options supported; laxed and junk_out.

オプションはキー/値の組で渡せます。 現在二つのオプション (laxed と junk_out) だけに対応しています。

The laxed option will make read_response_headers() more forgiving towards servers that have not learned how to speak HTTP properly. The laxed option is a boolean flag, and is enabled by passing in a TRUE value. The junk_out option can be used to capture bad header lines when laxed is enabled. The value should be an array reference. Bad header lines will be pushed onto the array.

laxed オプションは、read_response_headers() を、 HTTP の正しい話し方を学んでいないサーバに対してより寛容ににします。 laxed オプションは真偽値フラグで、TRUE 値を渡すことで有効になります。 junk_out オプションは、laxed が有効の時に間違ったヘッダ行を 捕捉するのに使われます。 値は配列リファレンスです。 間違ったヘッダ行はこの配列に push されます。

The laxed option must be specified in order to communicate with pre-HTTP/1.0 servers that don't describe the response outcome or the data they send back with a header block. For these servers peer_http_version is set to "0.9" and this method returns (200, "Assumed OK").

laxed オプションは、レスポンスやヘッダブロックを返さない、HTTP/1.0 以前の サーバと通信するために指定しなければなりません。 これらのサーバのために peer_http_version は "0.9" に設定され、 このメソッドは (200, "Assumed OK") を返します。

The method will raise an exception (die) if the server does not speak proper HTTP or if the max_line_length or max_header_length limits are reached. If the laxed option is turned on and max_line_length and max_header_length checks are turned off, then no exception will be raised and this method will always return a response code.

このメソッドは、サーバが適切な HTTP を話さなかったり max_line_length や max_header_length の制限に達した場合に 例外を発生させます (die します)。 laxed オプションを有効にして max_line_length と max_header_length のチェックを無効にすると、例外が発生することは なくなり、このメソッドは常にレスポンスコードが返されます。

$n = $s->read_entity_body($buf, $size);

Reads chunks of the entity body content. Basically the same interface as for read() and sysread(), but the buffer offset argument is not supported yet. This method should only be called after a successful read_response_headers() call.

エンティティボディの内容のチャンクを読み込みます。 基本的に read() および sysread() と同じインターフェースですが、バッファ オフセット引数はまだ対応していません。 このメソッドは、read_response_headers() 呼び出しに成功した後にのみ 呼び出されるべきです。

The return value will be undef on read errors, 0 on EOF, -1 if no data could be returned this time, otherwise the number of bytes assigned to $buf. The $buf is set to "" when the return value is -1.

返り値は、読み込みエラー時は undef、EOF なら 0、今回データが 返されなければ -1、それ以外は $buf に代入されたバイト数を示します。 返り値が -1 の場合は $buf には "" が設定されます。

You normally want to retry this call if this function returns either -1 or undef with $! as EINTR or EAGAIN (see Errno). EINTR can happen if the application catches signals and EAGAIN can happen if you made the socket non-blocking.

この関数が -1 を返すか、undef が返されて $! が EINTR か EAGAIN (Errno 参照) の場合、普通はこの呼び出しを繰り返したいはずです。 EINTR はアプリケーションがシグナルを受けたときに起こることがあり、 EAGAIN はソケットを非ブロッキングにしたときに起こることがあります。

This method will raise exceptions (die) if the server does not speak proper HTTP. This can only happen when reading chunked data.

このメソッドは、サーバが適切な HTTP を話さない場合は例外を 起こします(die します)。 これはデータの塊を読み込み中にのみ起こることがあります。

%headers = $s->get_trailers

After read_entity_body() has returned 0 to indicate end of the entity body, you might call this method to pick up any trailers.

エンティティボディの終わりを示すために read_entity_body() が 0 を 返した後、末尾に付けるヘッダを取得するためにこのメソッドを呼び出すかも しれません。

$s->_rbuf

Get/set the read buffer content. The read_response_headers() and read_entity_body() methods use an internal buffer which they will look for data before they actually sysread more from the socket itself. If they read too much, the remaining data will be left in this buffer.

読み込みバッファ内容を取得/設定します。 read_response_headers() メソッドと read_entity_body() メソッドは 実際にソケット地震から sysread する前にデータを探す内部バッファを使います。 もし読み込みすぎた場合、残りのデータはこのバッファに残ります。

$s->_rbuf_length

Returns the number of bytes in the read buffer. This should always be the same as:

読み込みバッファのバイト数を返します。 これは常に以下と同じです:

    length($s->_rbuf)

but might be more efficient.

しかしもっと効果的かもしれません。

サブクラス化¶

read_response_headers() と read_entity_body() は、もっとデータが必要な 場合は sysread() メソッドを起動します。 サブクラスは、読み込みをどのように行うかを制御するためにこのメソッドを オーバーライドしたいかもしれません。

オブジェクト自身はグロブです。 サブクラスは http_ と io_ を接頭辞使ったハッシュキー名は 避けるべきです。

SEE ALSO¶

LWP, IO::Socket::INET, Net::HTTP::NB

コピーライト¶

Copyright 2001-2003 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.