ブログ  前の記事  次の記事  2007-08-12 

たけまる / Perl - Atompub 0.0.1 リリース


2007-08-12

_ Perl - Atompub 0.0.1 リリース [perl][atompub]

Atompub モジュールの使い方シリーズ

(2007-09-12 追記) このエントリは,v0.1.0 [2007-09-12-1] の変更に合
わせて修正済みです

[2007-07-31-1] で予定していたように,Atompub 0.0.1 をリリースしま
した.

Atompub

Atompub には,Atom Publishing Protocol (AtomPub) を実装したクライ
アント (Atompub::Client) とサーバ (Atompub::Server) が含まれていま
す.この実装は,先日行われた InteropTokyo [2007-07-30-1] でテスト
されていますので,大きな問題なく動作すると思います.

このエントリでは,Atompub::Client モジュールの使い方を紹介します.

サーバの機能を単体モジュールとして実装するのは難しいので,
Atompub::Server には,mod_perl として動作させるためのハンドラや認
証処理のみを実装しました.残りのサーバ機能は,後日 Catalyst プラグ
インとしてリリースする予定です.

(2007-09-13 追記) Catalyst::Controller::Atompub をリリースしました [2007-09-13-1]


■ コレクション情報の取得

AtomPub は,"Entry Resource (Atom エントリ, ブログの記事など)" だ
けでなく,"Media Resource (バイナリデータ, 画像など)" をやりとり
することができます.エントリやメディアが置かれる場所を "コレクショ
ン" といいます.まずは,コレクションの情報を取得します.

まず,Atompub::Client オブジェクトを準備します.

use Atompub::Client;
my $client = Atompub::Client->new;

次に,サービス文書を取得します.このブログが書かれているホストでテ
スト用の Atom サーバを動かしていますので,そこから取得することにし
ます.必要に応じて,ユーザ名とパスワードを設定してください.
Atompub::Client は Basic 認証と WSSE 認証に対応しています.

$client->username('foo');
$client->password('foo');

my $service
    = $client->getService( 'http://teahut.sakura.ne.jp:3000/service' );

サービス文書にはコレクションの一覧とその情報が記載されています.コ
レクションに含まれるリソースの "メディアタイプ (app:accept)" や
"カテゴリ" を取得します.次のようなコードで一覧を出力できます.

for my $workspace ( $service->workspaces ) {
    print $workspace->title, "\n";
    for my $collection( $workspace->collections ) {
        print '- ', $collection->title, "\n";
        print '  URI: ', $collection->href, "\n";
        print '  Accept: ', join( ',', $collection->accepts ), "\n";
        print '  Category: ', join( ',', map { $_->term } $collection->categories->category ), "\n";
    }
}

以下に出力例を示します.2 つめのコレクションには "image/" があるこ
とから,画像のためのコレクションであるとわかります.1 つめのコレクショ
ンのようにメディアタイプが省略されたときは,エントリが対象となりま
す.

MyBlog
- Diary
  URI: http://teahut.sakura.ne.jp:3000/entrycollection
  Accept: 
  Category: animal,vegetable,mineral
- Photo
  URI: http://teahut.sakura.ne.jp:3000/mediacollection
  Accept: image/png,image/jpeg,image/gif
  Category:

■ Entry Resource (Atom エントリ) の追加と削除

まず,1 つめのコレクションにエントリを追加します.コレクションの
URI を取得します.
my @workspaces = $service->workspaces;
my @collections = $workspace[0]->collections;
my $collection_uri = $collections[0]->href;

次に,エントリを作成します.
my $entry = XML::Atom::Entry->new;
$entry->title('New Entry');
$entry->content('Content of my entry.');

Slug を使って,作成されるエントリの URI を指定することができます.
ここでは,"new-entry" を指定します.
my $slug = 'new-entry';

エントリを送信し,コレクションに追加します.
my $edit_uri = $client->createEntry( $collection_uri, $entry, $slug ) || die;

成功すると,エントリを編集するための Edit URI が返されます.Slug
を指定していれば,Edit URI に反映されているかもしれません (サーバ
の実装によります).Edit URI を使ってエントリを取得してみます.
my $entry = $client->getEntry( $edit_uri );

Edit URI は取得したエントリにも含まれています.エントリを編集して
更新します.
$entry->title('New Entry ver.2');
$client->updateEntry( $entry->edit_link, $entry ) || die;

同じようにして,削除もできます.
$client->deleteEntry( $edit_uri ) || die;

コレクションに含まれるエントリ一覧 (Atom フィード) を取得するとき
には,次のようにします.
my $feed = $client->getFeed( $collection_uri ) || die;

■ Media Resource (バイナリファイル) の追加と削除

Media Resource を追加します.2 つめのコレクションの URI を取得しま
す.
@workspaces = $service->workspaces;
@collections = $workspace[0]->collections;
$collection_uri = $collections[1]->href;	# コレクション URI

画像ファイル (sample1.gif) を送信します.Slug は 'new-image' としま
した.
$edit_uri
    = $client->createMedia( $collection_uri, 'sample1.gif',
                            'image/gif', 'new-image' ) || die;

Media Resource を追加すると,エントリが自動生成されます.この エン
トリを,Media Resource へのリンクを持つエントリということで,Media
Link Entry と呼びます.ここで返された $entry_uri は,Media Link
Entry の URI になります.

Media Link Entry には,rel="edit-media" である link 要素があり,
Media Resource の更新や削除に用いられます.Media Resource を更新し
てみます.
$entry = $client->getEntry( $edit_uri );
my $edit_media_uri = $entry->edit_media_link;

$client->updateMedia( $edit_media_uri, 'sample2.gif', 'image/gif' ) || die;

同じようにして,削除もできます.
$client->deleteMedia( $edit_media_uri ) || die;

Media Link Entry の一覧を取得することはできますが,Media Resource
の一覧を取得することはできません.

my $feed = $client->getFeed( $collection_uri ) || die;

■ HTTP レスポンスやリソースへのアクセサ

上記コードより詳細な情報を得るためのアクセサです.
アクセサ 対象
request HTTP::Request
response HTTP::Response
resource XML::Atom::Entry or byte string

たとえば,Entry を作成 (POST) したときに,サーバから返された Entry
を取得するにはこのようにします.
my $uri        = $client->createEntry( $collection_uri, $entry_post, $slug );
my $entry_recv = $client->resource; # XML::Atom::Entry

Media Resource を GET したときに,Content-Type を得るには次のよう
にします.
my $media = $client->getMedia( $edit_uri );
my $type  = $client->response->content_type; # Content-Type header

■ Atom Publishing Protocol について

Atom Publishing Protocol については,次のページが参考になります.

たけまる / Atom Publishing Protocol のメモ
IBM Atom 出版プロトコルを知る、第1回: Atom 出版プロトコルを使って… - Japan

一言メッセージをこっそり送信できます (非公開)
 今年の西暦→
Referrer (Inside): [2007-11-27-1] [2007-11-26-1] [2007-10-22-1] [2007-09-27-1] [2007-09-13-1] [2007-09-12-1] [2007-07-26-1]