名前¶

lwpcook - libwww-perl クックブック

説明¶

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

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

GET¶

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

  use LWP::Simple;
  $doc = get 'http://search.cpan.org/dist/libwww-perl/';

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

  perl -MLWP::Simple -e 'getprint "http://search.cpan.org/dist/libwww-perl/"'

あるいは最新の 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.cpan.org/SITES.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://search.cpan.org/dist/libwww-perl/');
  $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() 関数は実際に文書のメタ情報のリストを返します。 返されるリストの最初の三つの値は文書のタイプ、文書の 大きさ、文書の年齢 (age) です。

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

POST¶

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

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

  my $req = HTTP::Request->new(
      POST => 'http://rt.cpan.org/Public/Dist/Display.html');
  $req->content_type('application/x-www-form-urlencoded');
  $req->content('Status=Active&Name=libwww-perl');

  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://rt.cpan.org/Public/Dist/Display.html',
                [ Status => 'Active', Name => 'libwww-perl' ];

  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:password@proxy.myorg.com');

 $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://no.yahoo.com/"));
  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://search.cpan.org/distlibwww-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.cpan.org/authors/Gisle_Aas/libwww-perl-6.02.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.