名前¶

HTTP::Response - HTTP 形式のレスポンスメッセージ

概要¶

レスポンスオブジェクトは LWP::UserAgent の request() から返されます:

    # ...
    $response = $ua->request($request)
    if ($response->is_success) {
        print $response->decoded_content;
    }
    else {
        print STDERR $response->status_line, "\n";
    }

説明¶

HTTP::Response クラスは HTTP 形式のレスポンスをカプセル化します。 レスポンスはレスポンス行、いくつかのヘッダ、そして内容の本体(content body)で 構成されます。 LWP ライブラリは HTTP プロトコルでないスキームにも、HTTP 形式のレスポンスを 使っていることに注意してください。 このクラスのインタンスは通常 LWP::UserAgent の request() メソッドで 作成されてかえされます。

HTTP::Response は HTTP::Message のサブクラスなので、そのメソッドを 継承しています。 以下の追加のメソッドが利用できます:

$r = HTTP::Response->new( $code )

$r = HTTP::Response->new( $code, $msg )

$r = HTTP::Response->new( $code, $msg, $header )

$r = HTTP::Response->new( $code, $msg, $header, $content )

Constructs a new HTTP::Response object describing a response with response code $code and optional message $msg. The optional $header argument should be a reference to an HTTP::Headers object or a plain array reference of key/value pairs. The optional $content argument should be a string of bytes. The meaning these arguments are described below.

応答コード $code で、オプションのメッセージ $msg を記述する、新しい HTTP::Response オブジェクトを組みたてます。 オプションの $header 引数は HTTP::Headers オブジェクトへのリファレンスか キー/値の組への通常の配列リファレンスです。 オプションの $content 引数はバイト並びです。 これらの引数の意味は以下に記述します。

$r = HTTP::Response->parse( $str )

This constructs a new response object by parsing the given string.

これは与えられた文字列をパースすることによって新しい レスポンスオブジェクトを構築します。

$r->code

$r->code( $code )

This is used to get/set the code attribute. The code is a 3 digit number that encode the overall outcome of an HTTP response. The HTTP::Status module provide constants that provide mnemonic names for the code attribute.

これはコード属性を取得/設定するために使われます。 コードは、HTTP レスポンスの結果をエンコードした 3 桁の 10 進数です。 HTTP::Status モジュールは、コード属性に対する覚えやすい名前を示す 定数を提供します。

$r->message

$r->message( $message )

This is used to get/set the message attribute. The message is a short human readable single line string that explains the response code.

これはメッセージ属性を取得/設定するために使われます。 メッセージは短く、人が読める、応答コードを説明する 1 行の文字列です。

$r->header( $field )

$r->header( $field => $value )

This is used to get/set header values and it is inherited from HTTP::Headers via HTTP::Message. See HTTP::Headers for details and other similar methods that can be used to access the headers.

これはヘッダの値を取得/設定するために使われるもので、 HTTP::Headers から HTTP::Message 経由で継承されたものです。 詳細や、ヘッダにアクセスするために使えるその他の似たような メソッドについては HTTP::Headers を参照してください。

$r->content

$r->content( $bytes )

This is used to get/set the raw content and it is inherited from the HTTP::Message base class. See HTTP::Message for details and other methods that can be used to access the content.

これは生の内容を取得/設定するために使われます; これは HTTP::Message 基底クラスから継承しています。 詳細と、内容にアクセスするために使えるその他のメソッドについては HTTP::Message を参照してください。

$r->decoded_content( %options )

This will return the content after any Content-Encoding and charsets have been decoded. See HTTP::Message for details.

これは、Content-Encoding と文字集合をデコードした後の内容を 返します。 詳しくは HTTP::Message を参照してください。

$r->request

$r->request( $request )

This is used to get/set the request attribute. The request attribute is a reference to the the request that caused this response. It does not have to be the same request passed to the $ua->request() method, because there might have been redirects and authorization retries in between.

これは request 属性を取得/設定するために使われます。 request 属性はこのレスポンスを発生したリクエストへのリファレンスです。 これは $ua->request() メソッドに渡されたものと同じ リクエストである必要はありません。 というのもその間にリダイレクトや認証のリトライがあったかもしれないからです。

$r->previous

$r->previous( $response )

This is used to get/set the previous attribute. The previous attribute is used to link together chains of responses. You get chains of responses if the first response is redirect or unauthorized. The value is undef if this is the first response in a chain.

これは previous 属性を取得/設定するために使われます。 previous 属性はレスポンスのチェーンをたどるために使われます。 最初のレスポンスがリダイレトクトまたは認証されていなければ、 レスポンスのチェーンを取得します。 もしこれがチェーンの中の最初のレスポンスの場合は値は undef になります。

Note that the method $r->redirects is provided as a more convenient way to access the response chain.

Note that the method $r->redirects メソッドはレスポンスのチェーンにアクセスするための より便利な方法を提供していることに注意してください。

$r->status_line

Returns the string "<code> <message>". If the message attribute is not set then the official name of <code> (see HTTP::Status) is substituted.

文字列 "<code> <message>" を返します。 もし message 属性が設定されていなければ、<code>の公式の名前 （HTTP::Status を参照してください）に置き換えられます。

$r->base

Returns the base URI for this response. The return value will be a reference to a URI object.

このレスポンスの基本 URI を返します。 戻り値は URI オブジェクトへのリファレンスになります。

The base URI is obtained from one the following sources (in priority order):

基本 URI は以下のいずれかの情報源から（この優先順で）取得されます：

1. Embedded in the document content, for instance <BASE HREF="..."> in HTML documents.

   ドキュメント内容に埋め込まれたもの; 例えば HTML ドキュメント内での <BASE HREF="...">。

2. A "Content-Base:" or a "Content-Location:" header in the response.

   レスポンスでの "Content-Base:" または "Content-Locatin:" ヘッダ。

   For backwards compatibility with older HTTP implementations we will also look for the "Base:" header.

   古い HTTP 実装との後方互換性のため、"Base:" ヘッダも探します。

3. The URI used to request this response. This might not be the original URI that was passed to $ua->request() method, because we might have received some redirect responses first.

   このレスポンスを要求した URI。 これは $ua->request() メソッドに渡された、元の URI でないかもしれません。 というのもレスポンスの前に、いくつかのリダイレクトを 受信しているかもしれないからです。

If none of these sources provide an absolute URI, undef is returned.

これらのソースのいずれも絶対 URI を提供していない場合、undef が返されます。

When the LWP protocol modules produce the HTTP::Response object, then any base URI embedded in the document (step 1) will already have initialized the "Content-Base:" header. This means that this method only performs the last 2 steps (the content is not always available either).

LWP プロトコルモジュールが HTTP::Response オブジェクトを作成すると、 ドキュメントに埋め込まれたなんらかの基 本URI(step 1)が、 "Content-Base:" ヘッダを初期化しているでしょう。 つまりこのメソッドは残り 2 つのステップだけを行います （どちらも内容は常に使えるわけではありません）。

$r->filename

Returns a filename for this response. Note that doing sanity checks on the returned filename (eg. removing characters that cannot be used on the target filesystem where the filename would be used, and laundering it for security purposes) are the caller's responsibility; the only related thing done by this method is that it makes a simple attempt to return a plain filename with no preceding path segments.

このレスポンスのファイル名を返します。 返されたファイル名の妥当性チェック (つまり、ファイル名が使われる ファイルシステムで使えない文字の除去や、セキュリティ目的での サニタイズ) は呼び出し側の責任です; これに関してこのメソッドが行う 唯一のことは、先頭にパス区切り文字のない単純なファイル名を返そうと することだけです。

The filename is obtained from one the following sources (in priority order):

ファイル名は以下の情報源の一つから取得します (優先順):

1. A "Content-Disposition:" header in the response. Proper decoding of RFC 2047 encoded filenames requires the MIME::QuotedPrint (for "Q" encoding), MIME::Base64 (for "B" encoding), and Encode modules.

   レスポンスの "Content-Disposition:" ヘッダ。 RFC 2047 のエンコードされたファイル名を適切にデコードするには、 ("Q" エンコーディング用の) MIME::QuotedPrint、 ("B" エンコーディング用の) MIME::Base64、 そして Encode モジュールが必要です。

2. A "Content-Location:" header in the response.

   レスポンスの "Content-Location:" ヘッダ。

3. The URI used to request this response. This might not be the original URI that was passed to $ua->request() method, because we might have received some redirect responses first.

   このレスポンスのリクエストに使われた URI。 これは $ua->request() メソッドに渡された元の URI ではないかもしれません; なぜなら先にリダイレクトレスポンスを受け取っているかもしれないからです。

If a filename cannot be derived from any of these sources, undef is returned.

これらの情報源のどれからもファイル名を得られなかった場合、undef が 返されます。

$r->as_string

$r->as_string( $eol )

Returns a textual representation of the response.

レスポンスのテキストによる表現を返します。

$r->is_info

$r->is_success

$r->is_redirect

$r->is_error

These methods indicate if the response was informational, successful, a redirection, or an error. See HTTP::Status for the meaning of these.

これらのメソッドはレスポンスが情報的(informational)であるか、 成功したか、リダイレクトであるか、エラーであるかを示します。 これらの意味については HTTP::Status を参照してください。

$r->error_as_HTML

Returns a string containing a complete HTML document indicating what error occurred. This method should only be called when $r->is_error is TRUE.

何のエラーが発生したかを示す完全なHTMLドキュメントが入っている 文字列を返します。 このメソッドは $r->is_error が真のときだけ呼ばれるべきです。

$r->redirects

Returns the list of redirect responses that lead up to this response by following the $r->previous chain. The list order is oldest first.

$r->previous のチェーンをたどることで、このレスポンスまでの リダイレクトレスポンスのリストを返します。 リストの順序は古いものが最初です。

In scalar context return the number of redirect responses leading up to this one.

スカラコンテキストでは、このレスポンスまでのリダイレクトレスポンスの 数を返します。

$r->current_age

Calculates the "current age" of the response as specified by RFC 2616 section 13.2.3. The age of a response is the time since it was sent by the origin server. The returned value is a number representing the age in seconds.

RFC 2616 section 13.2.3 によって指定されたレスポンスの 「現在の年齢」("current age")を計算します。 レスポンスの年齢は元のサーバによって送信されてからの時間です。 返される値は、年齢を秒で表した数字です。

$r->freshness_lifetime( %opt )

Calculates the "freshness lifetime" of the response as specified by RFC 2616 section 13.2.4. The "freshness lifetime" is the length of time between the generation of a response and its expiration time. The returned value is the number of seconds until expiry.

RFC 2616 section 13.2.4 で指定された、そのレスポンスの「新鮮保持期間」 ("freshness lifetime")を計算します。 「新鮮保持期間」はレスポンスが生成されてから破棄されるまでの時間の長さです。 返される値は破棄されるまでの秒数です。

If the response does not contain an "Expires" or a "Cache-Control" header, then this function will apply some simple heuristic based on the "Last-Modified" header to determine a suitable lifetime. The following options might be passed to control the heuristics:

もし "Expires" または"Cache-Control" ヘッダがレスポンスに入っていなければ、 適切な期間を決めるため、この関数は "Last-Modified" ヘッダをベースに単純な ヒューリスティックを適用します。 以下のオプションを渡すことでヒューリスティックを制御できます:

heuristic_expiry => $bool

If passed as a FALSE value, don't apply heuristics and just return undef when "Expires" or "Cache-Control" is lacking.

偽の値を渡すと、ヒューリスティックは適用せず、 "Expires" か "Cache-Control" がない場合は単に undef を返します。

h_lastmod_fraction => $num

This number represent the fraction of the difference since the "Last-Modified" timestamp to make the expiry time. The default is 0.10, the suggested typical setting of 10% in RFC 2616.

この数値は、破棄時刻を作るための、"Last-Modified" タイムスタンプからの 差分の分数を表現します。 デフォルトは 0.10 で、RFC 2616 で推奨されている典型的な設定である 10% です。

h_min => $sec

This is the lower limit of the heuristic expiry age to use. The default is 60 (1 minute).

これは使われるヒューリスティック破棄年齢の下限です。 デフォルトは 60 (1 分) です。

h_max => $sec

This is the upper limit of the heuristic expiry age to use. The default is 86400 (24 hours).

これは使われるヒューリスティック破棄年齢の上限です。 デフォルトは 86400 (24 時間) です。

h_default => $sec

This is the expiry age to use when nothing else applies. The default is 3600 (1 hour) or "h_min" if greater.

これは他に何も適用されないときの破棄年齢です。 デフォルトは 3600 (1 時間) か "h_min" の大きい方です。

$r->is_fresh( %opt )

Returns TRUE if the response is fresh, based on the values of freshness_lifetime() and current_age(). If the response is no longer fresh, then it has to be re-fetched or re-validated by the origin server.

freshness_lifetime() と current_age() の値をベースに、レスポンスが 新鮮であれば真を返します。 レスポンスがもはや新鮮でなければ、もう一度取り出されるか、 元のサーバによって再評価される必要があります。

Options might be passed to control expiry heuristics, see the description of freshness_lifetime().

オプションは破棄ヒューリスティックを制御するために渡されます; freshness_lifetime() の記述を参照してください。

$r->fresh_until( %opt )

Returns the time (seconds since epoch) when this entity is no longer fresh.

このエンティティがもはや新鮮ではなくなる時刻(期限からの秒数)を返します。

Options might be passed to control expiry heuristics, see the description of freshness_lifetime().

オプションは破棄ヒューリスティックを制御するために渡されます; freshness_lifetime() の記述を参照してください。

SEE ALSO¶

HTTP::Headers, HTTP::Message, HTTP::Status, HTTP::Request

コピーライト¶

Copyright 1995-2004 Gisle Aas.

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