HTTP::Request::Common

Hippo2000 (2000/7/28)

HTTP::Request::Commonモジュールなのです。

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

名前

HTTP::Request::Common - 汎用のHTTP::Request オブジェクトの組み立て

概要

  use HTTP::Request::Common;
  $ua = LWP::UserAgent->new;
  $ua->request(GET 'http://www.sn.no/');
  $ua->request(POST 'http://somewhere/foo', [foo => bar, bar => foo]);

説明

このモジュールは新しく作成された HTTP::Request オブジェクトを返す関数を提供します。これらの関数はこれらの一般的なリクエストのための標準のHTTP::Requestコンストラクタよりも、通常より使いやすいものです。以下の関数が提供されます。

GET $url, Header => Value,...

GET()関数はGETメソッドと指定されたURLで初期化されたHTTP::Requestオブジェクトを返します。追加の引数無しでは、それは実質的に以下の呼び出しと同じです。

  HTTP::Request->;new(GET => $url)

しかし散らかりは少ないです。LWP::UserAgent->request()メソッドと一緒に使われるとき、それはよりよく読みます：

  my $ua = new LWP::UserAgent;
  my $res = $ua->request(GET 'http://www.sn.no')
  if ($res->is_success) { ...

オプションの引数としていくつかのキー／値の組を指定することにより、リクエストでのヘッダの値を初期化することも出来ます。例えば：

  $ua->request(GET 'http://www.sn.no',
                   If_Match => 'foo',
                   From     => 'gisle@aas.no',
              );

'Content'というヘッダ・キーは特殊です。そしてそれがあると、その値はヘッダの設定の代りに、内容（content）部分を初期化します。

HEAD $url, [Header => Value,...]

GET()と同様。ただしリクエストでのメソッドはHEAD。

PUT $url, [Header => Value,...]

GET()と同様。ただしリクエストでのメソッドはPUT。

POST $url, [$form_ref], [Header => Value,...]

これはPOSTをメソッドとして最もGET()のように機能します。しかしこの関数は2番目のオプションの配列またはハッシュ・リファレンスのパラメータ($form_ref)を取ります。この引数はフォーム・コンテントのためのキー／値の組を渡すために使うことが出来ます。デフォルトではapplication/x-www-form-urlencodedコンテント・タイプを使ってリクエストを初期化します。つまり以下のようにしてHTML<form>POSTすることをエミュレートすることができます：

  POST 'http://www.perl.org/survey.cgi',
       [ name   => 'Gisle Aas',
         email  => 'gisle@aas.no',
         gender => 'M',
         born   => '1964',
         perc   => '3%',
       ];

これは以下のようなHTTP::Request オブジェクトを作成します：

  POST http://www.perl.org/survey.cgi
  Content-Length: 66
  Content-Type: application/x-www-form-urlencoded

  name=Gisle%20Aas&email=gisle%40aas.no&gender=M&born=1964&perc=3%25

POST メソッドはRFC1867で示された Form-based File Upload のために使われるmultipart/form-dataコンテントもサポートします。リクエスト・ヘッダの１つとして'form-data'のコンテント・タイプを指定することにより、このコンテント・フォーマットを利用することが出来ます。もし$form_refの中の値の1つが配列リファレンスであれば、それは以下の解釈でファイル部分の指定であるように扱われます：

  [ $file, $filename, Header => Value... ]

配列での先頭の値($file)はオープンするファイルの名前です。このファイルは読みこまれ、その内容がリクエストに入れられます。もしファイルをオープンできなければルーチンはcroakします。コンテントを直接指定したければ$fileの値をundefにしてください。$filenameはリクエストで報告されるファイル名です。この値が未定義であれば、$fileの基本名が使われます。リクエストになにもファイル欲しくなければ、$filenameにから文字列を指定することができます。

上記の例として~/.profileをsurveyに送信することが以下のようにして実現できます：

  POST 'http://www.perl.org/survey.cgi',
       Content_Type => 'form-data',
       Content      => [ name  => 'Gisle Aas',
                         email => 'gisle@aas.no',
                         gender => 'M',
                         born   => '1964',
                         init   => ["$ENV{HOME}/.profile"],
                       ]

これはおおむね以下のようなHTTP::Requestオブジェクトを作成します（バウンダリと~/.profileは違っていることでしょう）：

  POST http://www.perl.org/survey.cgi
  Content-Length: 388
  Content-Type: multipart/form-data; boundary="6G+f"

  --6G+f
  Content-Disposition: form-data; name="name"
  
  Gisle Aas
  --6G+f
  Content-Disposition: form-data; name="email"
  
  gisle@aas.no
  --6G+f
  Content-Disposition: form-data; name="gender"
  
  M
  --6G+f
  Content-Disposition: form-data; name="born"
  
  1964
  --6G+f
  Content-Disposition: form-data; name="init"; filename=".profile"
  Content-Type: text/plain
  
  PATH=/local/perl/bin:$PATH
  export PATH

  --6G+f--

（エクスポート可能な）$DYNAMIC_FILE変数をTRUEに設定すると、content属性としてサブルーチン・クロージャでrequestオブジェクトを取得します。このサブルーチンは命令のなかのすべてのファイルの内容を読みこみ、それを適切なチャンクにいれて返します。これにより大量のメモリを使わずに任意の大きなファイルをアップロードすることができます。お望みであれば/dev/audioのような無限大のファイルをアップロードすることすら可能です。もう１つの違いは、この機能を使うと、リクエストのために定義されたContent-Lengthヘッダがないということです。すべてのサーバ（またはサーバ・アプリケーション）がどうであるというわけではありません。

参考資料

HTTP::Request, LWP::UserAgent

著作権

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

ホーム　Perlの小技　HTTP

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

HTTP::Request::Common

目次

名前

概要

説明

参考資料

著作権