LWP::UserAgent

Hippo2000 (2000/7/28)

LWP::UserAgentモジュールなのです。

作者はGisle Aasさんです。メールで許可をいただきました。

2001/6/21：山宮隆さんからの指摘を受けて、余分な「；」を削除しました。

目次

• 名前
• 概要
• 説明
• メソッド
• 参考資料
• 著作権

名前

LWP::UserAgent - WWW ユーザ・エージェント クラス

概要

 require LWP::UserAgent;
 $ua = LWP::UserAgent->new;

 $request = HTTP::Request->new('GET', 'file://localhost/etc/motd');

 $response = $ua->request($request); # or
 $response = $ua->request($request, '/tmp/sss'); # or
 $response = $ua->request($request, \&callback, 4096);

 sub callback { my($data, $response, $protocol) = @_; .... }

説明

LWP::UserAgentは単純なWorld-Wide Web ユーザ・エージェントをPerlで実装するクラスです。それはHTTP::Request、HTTP::Response、そしてlibwww-perl ライブラリの残りの中核を形成するLWP::Protocolクラスをまとめます。単純化のため、このクラスを直接、WWWリクエストを実行するために使うことが出来ます。代りにアプリケーション独自の動きのためにサブクラス化することもできます。

通常の使用では、アプリケーションはUserAgentクラスを作成し、タイムアウト、プロキシー、名前などのための値でそれを設定します。次に実行されるために必要があるリクエストのためにHTTP::Requestのインスタンスを作成します。そしてこのリクエストはUserAgent request()メソッドに渡されます。これは対応するプロトコルを使ってそれを発行し、HTTP::Responseオブジェクトを返します。

このライブラリの基本的なアプローチはHTTP式通信をすべてのプロトコルスキームに使うことです。つまりgopherやftpリクエストでもHTTP::Responseオブジェクトを受け取るということです。HTTP式通信により似せるため、gopherメニューとfileのディレクトリはHTMLドキュメントに変換されます。

request()メソッドはレスポンスの内容をメモリ、ファイルへの格納、サブルーチン呼び出しの繰り返しの３つのうちの1つの方法で処理することが出来ます。request()への2番目の引数として渡された値の種類によってどれか１つを選びます。

メモリ上の場合は内容をresponseオブジェクトのスカラ'content'属性に格納することで、さらに解析する必要があるかもしれない小さなHTML応答に適しています。この変数は2番目の引数がなければ（あるいはundefであれば）使われます。

ファイル名の場合はファイル名が入っているスカラをrequest()の2番目の引数として必要とします。そして大量のメモリを必要せず、直接ファイルに書かれる必要がある大きなWWWオブジェクトに向いています。この場合request()から返されるresponseオブジェクトは空のcontent属性を持っています。もしrequestが失敗すれば、contentは空ではないかもしれません、そしてファイルは触られないでしょう。

サブルーチンの場合には、request()への2番目の引数としてコールバック・ルーチンへのリファレンスを必要とします。そして3番目の引数としてオプションのチャンクサイズを取ることも出来ます。この変数は"パイプラインの"処理を構築するために使われます。それは受取られたチャンクの処理をすべてのデータ届く前に始められます。コールバック関数は3つの引数で呼ばれます：このときに受信されたデータ、responseオブジェクトへのリファレンス、protocolオブジェクトへのリファレンスです。request()から返されるresponseオブジェクトは空のcontentを持ちます。requestが失敗すると、コールバック・ルーチンが呼ばれ、response->contentは空でないかもしれません。

requestはコールバック・ルーチンでdie()を呼ぶことによって中断させることが出来ます。dieメッセージは"X-Died"という特別なヘッダ・フィールドとして利用することが出来ます。

またこのライブラリはサブルーチン・リファレンスをrequestオブジェクトでのcontentとして使うことも許しています。このサブルーチンは呼ばれたときに内容（content）を返さなければなりません（おそらく細切れの）。もう内容がなければ、空の文字列を返さなければなりません。

メソッド

以下のメソッドを使うことが出来ます：

$ua = LWP::UserAgent->new;

UserAgentのためのコンストラクタ。LWP::UserAgent オブジェクトへのリファレンスを返します。

$ua->simple_request($request, [$arg [, $size]])

このメソッドはユーザのために1回のWWWリクエストを発行し、受信したレスポンスを返します。$requestは少なくともmethod()とuri()属性は定義された値を持つHTTP::Requestオブジェクトへのリファレンスでなければなりません。

$argはスカラであれば、レスポンスが格納されるファイル名として取られます。

$argがサブルーチンへのリファレンスであれば、内容のチャンクが受信されるとこのルーチンが呼ばれます。オプションの$size引数は適切なチャンク・サイズのためのヒントとして取られます。

$argが省略されると、内容はresponseオブジェクト自身に格納されます。

$ua->request($request, $arg [, $size])

リダイレクトとセキュリティを含めて、リクエストを処理します。このメソッドは実際にはいくつかの別の簡単なリクエストを送信するかもしれません。

引数はsimple_request()のものと同じです。

$ua->redirect_ok

このメソッドはなにかリダイレクトをしようとする前に、request()によって呼ばれます。それはリダイレクトをすることが許されているのであればtrueを返さなければなりません。サブクラスはこれをオーバーライドしたいかもしれません。

デフォルトの実装ではPOSTリクエストではFALSEを、それ以外にはTRUEを返します。

$ua->credentials($netloc, $realm, $uname, $pass)

realmのために使われるユーザ名、パスワードを設定します。代わりにget_basic_credentials()メソッドを特殊化するのにより便利です。

$ua->get_basic_credentials($realm, $uri, [$proxy])

基本認証(Basic Authentication)またはダイジェスト認証(Digest Authentication)により保護されているRealmのためのcredenialの取り出しのためにrequest()によって呼ばれます。

リストにあるユーザ名とパスワードを返さなければなりません。認証解決の試みを中断させるためにはundefを返してください。

この実装は単に既に格納されているメンバー変数のセットをチェックします。サブクラスはこのモジュールを上書きできます。例えばユーザにユーザ名／パスワードを尋ねるなど。この例はこのライブラリと一緒に配布されるlwp-requestプログラムにあります。

$ua->agent([$product_id])

ネットワーク上でユーザ・エージェントを識別するために使われるproductトークンを取得／設定します。エージェントの値はリクエストの"User-Agaent"ヘッダとして送信されます。デフォルトのエージェント名は"libwww-perl/#.##"で、"#.##"はこのライブラリのバージョンで置き換えられます。

　

user agent文字列は１つもしくはそれ以上の、オプションで"/"文字で区切られたバージョン番号がついた単純な製品識別子です。例を以下に示します：

  $ua->agent('Checkbot/0.4 ' . $ua->agent);
  $ua->agent('Mozilla/5.0');

$ua->from([$email_address])

リクエストしているユーザーエージェントを制御している人間であるユーザのインターネット e-mailアドレスを取得／設定します。アドレスはRFCで定義されているように、機械で利用できなければなりません。fromの値はリクエストでの"From"ヘッダとして送信されます。デフォルトはありません。例：

  $ua->from('gaas@cpan.org');

$ua->timeout([$secs])

秒単位でタイムアウト(timeout)を取得／設定します。デフォルトのtimeout()の値は180秒、つまり3分です。

$ua->cookie_jar([$cookies])

利用するためにHTTP::Cookies オブジェクトを取得／設定します。デフォルトではなにもcookie_jarを持ちません。つまり自動的には"Cookie"ヘッダをリクエストに追加しません。

$ua->parse_head([$boolean])

HTMLドキュメントの<head>セクションからレスポンス・ヘッダを初期化すべきかどうかを示す値を取得／設定します。デフォルトはTRUEです。何をしているのかわからなければ、これをoffに変えないで下さい。

$ua->max_size([$bytes])

レスポンスの内容(content)の大きさの制限を取得／設定します。デフォルトはundefで、これは制限なしを意味します。大きさの制限を越えているために、戻されたレスポンスの内容(content)が一部だけであれば、"X-Content-Range"ヘッダがレスポンスに追加されます。

$ua->clone;

LWP::UserAgentオブジェクトのコピーを返します。

$ua->is_protocol_supported($scheme)

ライブラリが指定されたスキームを現在、サポートしているかどうかを聞くために使うことができます。スキームには('http'や'ftp'）文字列やURIオブジェクト・リファレンスを指定できます。

$ua->mirror($url, $file)

If-Modified-Sinceを使い、Content-Lengthをチェックしながら、URLによって識別されるドキュメントを取得し、格納します。レスポンス(response)オブジェクトへのリファレンスを返します。

$ua->proxy(...)

そのスキームのためのプロキシーURLを設定／取得します：

 $ua->proxy(['http', 'ftp'], 'http://proxy.sn.no:8001/');
 $ua->proxy('gopher', 'http://proxy.sn.no:8001/');

最初の形式はそのURLがメソッドの最初に引数のリストに入っているアクセス・メソッド、つまり'http'と'ftp'のプロキシーのために使われることを指定します。

2番目の形式は１つのアクセス機能のためのプロキシーURLを指定するための短縮した形式を示しています。

$ua->env_proxy()

*_proxy環境変数からプロキシー設定をロードします。以下のように指定するかもしれません（shでの書き方）：

  gopher_proxy=http://proxy.my.place/
  wais_proxy=http://proxy.my.place/
  no_proxy="localhost,my.domain"
  export gopher_proxy wais_proxy no_proxy

Cshまたはtcshユーザは、これらの環境変数を定義するためにsetenvコマンドを使わなければなりません。

$ua->no_proxy($domain,...)

与えられたドメインへのリクエストをプロキシーしません。何もドメインを指定しないでno_proxyを呼ぶと、ドメインのリストをクリアします。

 $ua->no_proxy('localhost', 'no', ...);

参考資料

libwww-perl5の一通りの概要は LWP をご覧下さい。使い方の例についてはlwp-request と lwp-mirror をご覧下さい。

著作権（=COPYRIGHT)

Copyright 1995-2000 Gisle Aas.

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

ホーム　Perlの小技　LWP

ご意見、ご質問はこちらの掲示板で受け付けています。
またメールは河馬屋(Nifty)にお願いします。