名前¶

lwpcook - libwww-perl クックブック

説明¶

このドキュメントには、libwww-perl ライブラリの典型的な使い方を示す いくつかのサンプルが入っています。 詳細については各モジュールのドキュメントをご覧下さい。

すべてのサンプルは実行可能なプログラムのはずです。 ほとんどの場合、プログラムテキストを perl に直接パイプすることによって コード部分をテストすることができます。

GET¶

ネットからドキュメントを取り出すだけなら、このライブラリを使って 簡単にできます。 LWP::Simple モジュールは、URL 引数で指定されたドキュメントを返す get() 関数を提供しています:

  use LWP::Simple;
  $doc = get 'http://www.linpro.no/lwp/';

あるいは、getprint() 関数を使ったperlワンライナーならば:

  perl -MLWP::Simple -e 'getprint "http://www.linpro.no/lwp/"'

あるいは最新の perl をこのコマンドを実行して取り出すというのはいかがです?:

  perl -MLWP::Simple -e '
    getstore "ftp://ftp.sunet.se/pub/lang/perl/CPAN/src/latest.tar.gz",
             "perl.tar.gz"'

まずは以下のようなコマンドを実行することで、あなたに一番近い CPAN サイトを 見つけ出したいかもしれませんね:

  perl -MLWP::Simple -e 'getprint "http://www.perl.com/perl/CPAN/CPAN.html"'

この簡単なもので十分! LWP オブジェクト指向インターフェースは、サーバへのリクエストをさらに 制御できます。 このインタフェースを使うと、ヘッダの送信や返されたレスポンスを どのように扱いたいかについてすべて制御できます:

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;
  $ua->agent("$0/0.1 " . $ua->agent);
  # $ua->agent("Mozilla/8.0") # pretend we are very capable browser

  $req = HTTP::Request->new(GET => 'http://www.linpro.no/lwp');
  $req->header('Accept' => 'text/html');

  # send request
  $res = $ua->request($req);

  # check the outcome
  if ($res->is_success) {
     print $res->decoded_content;
  }
  else {
     print "Error: " . $res->status_line . "\n";
  }

ライブラリと一緒に配布されるlwp-requestプログラム（別名 GET）も、 WWW サーバからのドキュメント取り出しに使うことができます。

HEAD¶

ドキュメントがあるか (つまり URL が正しいか) をチェックしたいだけであれば、 以下のようなコードを実行してみてください:

  use LWP::Simple;

  if (head($url)) {
     # ok document exists
  }

head() 関数は本当にドキュメントのメタ情報のリストを返します。 返されるリストの最初の3つの値はドキュメントのタイプ、ドキュメントの 大きさ、ドキュメントの年齢 (age) です。

リクエストをもっと制御したり、返された値のすべてのヘッダの値に アクセスするためには、上記のGETで説明したオブジェクト指向インターフェースを つかう必要があります。 単に s/GET/HEAD/g してください。

POST¶

WWW にデータをポストするために、単純な手続き型のインターフェースはありません。 これにはオブジェクト指向インタフェースを使わなければなりません。 最も通常の POST 処理はWWWフォームアプリケーションにアクセスすることです：

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

  my $req = HTTP::Request->new(POST => 'http://www.perl.com/cgi-bin/BugGlimpse');
  $req->content_type('application/x-www-form-urlencoded');
  $req->content('match=www&errors=0');

  my $res = $ua->request($req);
  print $res->as_string;

怠惰な人たちは適切な POST リクエストメッセージを構築するために HTTP::Request::Common モジュールを使います (それはすべてのエスケープすることを扱い、そして content_type のために 適切なデフォルトを持ちます):

  use HTTP::Request::Common qw(POST);
  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;

  my $req = POST 'http://www.perl.com/cgi-bin/BugGlimpse',
                [ search => 'www', errors => 0 ];

  print $ua->request($req)->as_string;

ライブラリと一緒に配布される lwp-request プログラム (別名 POST) も、 データのポストに使うことができます。

PROXIES¶

サイトによってはファイアーウォール機能やパフォーマンスを向上させるための たんなるキャッシュを実現するためにプロキシーを使っています。 libwww-perl ライブラリによって直接サポートされない (あるいはうまくサポートされていない:-)) プロトコルを通してリソースに アクセスするためにも,プロキシーを使うことができます。

リクエスト送信を開始する前に、プロキシー設定を初期化しなければなりません:

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;
  $ua->env_proxy; # initialize from environment variables
  # or
  $ua->proxy(ftp  => 'http://proxy.myorg.com');
  $ua->proxy(wais => 'http://proxy.myorg.com');
  $ua->no_proxy(qw(no se fi));

  my $req = HTTP::Request->new(GET => 'wais://xxx.com/');
  print $ua->request($req)->as_string;

LWP::Simple インターフェースはあなたに代わって自動的に env_proxy() を呼びます。 $ua->env_proxy メソッドを使うアプリケーションは、通常、$ua->proxy() と $ua->no_proxy メソッドは使いません。

プロキシーによっては、リクエストを通すためにユーザ名／パスワードを 送信することも要求することがあります。 以下のようにして、要求されるヘッダを追加することができます:

 use LWP::UserAgent;

 $ua = LWP::UserAgent->new;
 $ua->proxy(['http', 'ftp'] => 'http://username:[email protected]');

 $req = HTTP::Request->new('GET',"http://www.perl.com");

 $res = $ua->request($req);
 print $res->decoded_content if $res->is_success;

proxy.myorg.com, username, password をあなたのサイトに合わせて 置き換えてください。

保護されているドキュメントへのアクセス¶

基本認証によって保護されているドキュメントは以下のようにして簡単に アクセスできます:

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;
  $req = HTTP::Request->new(GET => 'http://www.linpro.no/secret/');
  $req->authorization_basic('aas', 'mypassword');
  print $ua->request($req)->as_string;

他の方法としては、get_basic_credentials() メソッドをオーバーライドする LWP::UserAgent のサブクラスを提供することがあります。 この例として lwp-request プログラムを調べてみてください。

クッキー¶

クッキーをもてあそぶことを好むサイトもあります。 デフォルトでは LWP は、それが訪れたサーバから提供されるクッキーを無視します。 クッキー容器を設定しておくと、LWP はクッキーを収集して、クッキーリクエストに 応答します。

  use LWP::UserAgent;
  use HTTP::Cookies;

  $ua = LWP::UserAgent->new;
  $ua->cookie_jar(HTTP::Cookies->new(file => "lwpcookies.txt",
                                     autosave => 1));

  # and then send requests just as you used to do
  $res = $ua->request(HTTP::Request->new(GET => "http://www.yahoo.no"));
  print $res->status_line, "\n";

保存するようにクッキーを送信するサイトに訪れると、ファイル lwpcookies.txt が大きくなります。

HTTPS¶

https 機能を持つ URL は http 機能を持つものと全く同じようにアクセスされます。 それは適切にインストールされている LWP のための SSL インタフェース モジュールにより提供されます (詳細は libwww-perl ディストリビューションに 含まれている README.SSL ファイルをご覧下さい)。 LWP のための SSL インタフェースが利用できなければ、そのような URL に アクセスすると、"501 Protocol scheme 'https' is not supported" エラーに なります。

以下に SSL を使っている WWW ページの取り出しと出力の例を示します:

  use LWP::UserAgent;

  my $ua = LWP::UserAgent->new;
  my $req = HTTP::Request->new(GET => 'https://www.helsinki.fi/');
  my $res = $ua->request($req);
  if ($res->is_success) {
      print $res->as_string;
  }
  else {
      print "Failed: ", $res->status_line, "\n";
  }

ミラーリング¶

WWW サーバからドキュメントをミラーしたければ、定期的に以下のようなコードを 実行してみてください:

  use LWP::Simple;

  %mirrors = (
     'http://www.sn.no/'             => 'sn.html',
     'http://www.perl.com/'          => 'perl.html',
     'http://www.sn.no/libwww-perl/' => 'lwp.html',
     'gopher://gopher.sn.no/'        => 'gopher.html',
  );

  while (($url, $localfile) = each(%mirrors)) {
     mirror($url, $localfile);
  }

もしくは perl ワンライナーとして：

  perl -MLWP::Simple -e 'mirror("http://www.perl.com/", "perl.html")';

更新されていなければ、ドキュメントは転送されません。

巨大なドキュメント¶

取り出したいドキュメントがメモリに入りきらないほど大きければ、 二つの代替案があります。 ドキュメント内容をファイルに書きこむようライブラリに 指示できます ($ua->request() の 2 番目の引数はファイル名になります):

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

  my $req = HTTP::Request->new(GET =>
                'http://www.linpro.no/lwp/libwww-perl-5.46.tar.gz');
  $res = $ua->request($req, "libwww-perl.tar.gz");
  if ($res->is_success) {
     print "ok\n";
  }
  else {
     print $res->status_line, "\n";
  }

あるいは、ドキュメントが届いたときに処理することができます ($ua->request() の 2 番目の引数はコードリファレンスになります):

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;
  $URL = 'ftp://ftp.unit.no/pub/rfc/rfc-index.txt';

  my $expected_length;
  my $bytes_received = 0;
  my $res =
     $ua->request(HTTP::Request->new(GET => $URL),
               sub {
                   my($chunk, $res) = @_;
                   $bytes_received += length($chunk);
                   unless (defined $expected_length) {
                      $expected_length = $res->content_length || 0;
                   }
                   if ($expected_length) {
                        printf STDERR "%d%% - ",
                                  100 * $bytes_received / $expected_length;
                   }
                   print STDERR "$bytes_received bytes received\n";

                   # XXX Should really do something with the chunk itself
                   # print $chunk;
               });
   print $res->status_line, "\n";

コピーライト¶

Copyright 1996-2001, Gisle Aas

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