XML-RPC

XML-RPC

XML-RPC が有効になると、多くの異なるプログラム言語で書かれた外部プログラムがこのサービスを使って POPFile と連携することができるようになります。POPFile の API は、0.22.0 のリリースで初めて一緒に提供された UI::XMLRPC モジュールをとおして提供されます。UI::XMLRPC モジュールは、標準的な POPFile インストレーションでは必要のない、いくつかの追加 Perl コンポーネントを必要とします。

API とメソッドについての詳細は、このページで見ることができます。

XML-RPC についての全般的な情報については、 XMLRPC.com で見ることができます。（訳注：リンク先は英語です）

Windows 版のインストーラは、UI::XMLRPC モジュールをオプションのコンポーネントとして扱っています（デフォルトではインストールされません）。オプションの UI::XMLRPC モジュールがインストールされる場合、Windows 版のインストーラはこのモジュールが必要とする追加 Perl コンポーネントもインストールします。

XMLRPC を使用して POPFile にアクセスするクライアントは、どんなマシンでも動かすことができ、またどんなプログラム言語でも使用することができます（訳注：リンク先は英語です）。クライアントは提供されていませんので、自分で作らなければいけません。Perl、Python、Delphi、NSBasic/CE で書かれたクライアントの例が下に記載されています。

接続待ちポート

XML-RPC の接続待ちポートは POPFile の設定タブにあるモジュールオプションの欄で設定することができます。この設定は UI::XMLRPC.pm モジュールがインストールされ、POPFile が再起動してモジュールの存在を認識するまで表示されませんので注意してください。

セキュリティ

インストールされると、POPFile UI のセキュリティタブのサーバ欄の下に新しいセキュリティオプションが追加されます。” リモートマシンからの XML-RPC 接続を認める (POPFile の再起動が必要)” というオプションがあらわれるでしょう。POPFile が動作しているマシン以外からのアクセスを許可するためには、このオプションを「はい」にしなければいけません。

必要な Perl モジュール

注意: Windows 版インストーラを使用して UI::XMLRPC モジュールをインストールした場合、これらの Perl コンポーネントは自動的にインストールされます。

以下の Perl モジュールは POPFile が動作しているマシンにインストールしなければいけません。さらに、SOAP::Lite モジュールは Perl クライアントを使って XMLRPC 経由で POPFile にアクセスするすべてのクライアントマシンにもインストールする必要があります。

XMLRPC.pm は POPFile がインストールされたディレクトリの UI ディレクトリにインストールしなければいけません。これは CVS のここから入手することができます。このファイルを、XMLRPC.pm というファイル名で保存してください。このモジュールを認識させるためには、POPFile を再起動しなければいけません。

XML-RPC の機能を使用するためには XMLRPC::Lite を含んでいる SOAP::Lite がインストールされている必要があります。SOAP::Lite モジュールは、 CPAN で入手することができます。Activestate Perl を使用している場合は ppm からインストールすることができます。例えば、

   ppm
   >install SOAP-Lite

とします。

サンプルコード

簡単な例

Perl の例 1

use strict;
use XMLRPC::Lite;

my $sk = XMLRPC::Lite ->proxy('http://localhost:8081/RPC2')
         -> call('POPFile/API.get_session_key','admin',//)
         -> result;

print XMLRPC::Lite ->proxy('http://localhost:8081/RPC2')
      -> call('POPFile/API.classify',$sk,'spam.txt')
      -> result;

XMLRPC::Lite ->proxy('http://localhost:8081/RPC2')
      -> call('POPFile/API.release_session_key',$sk);

上記のソースを testxml.pl というファイル名で保存し、正しく設定されたシステムでテスト用のメッセージ 'spam.txt' に対して実行すれば、次のような結果が出力されるでしょう:

   perl testxml.pl
   spam

Python の例 1

from xmlrpclib import ServerProxy
POPFile = ServerProxy("http://localhost:8081")
pf = POPFile.POPFile.API	# naming shortcut to make things easier
key = pf.get_session_key("admin","")
print pf.classify(key, "spam.txt")
pf.release_session_key(key)

上記のソースを testxml.py というファイル名で保存し、正しく設定されたシステムでテスト用のメッセージ 'spam.txt' に対して実行すれば、次のような結果が出力されるでしょう:

   python testxml.py
   spam

Delphi の例

program popdelphi;
{$APPTYPE CONSOLE}

uses
  sysutils, xmlrpctypes, xmlrpcclient;

var
  caller: TCaller;
  func: TFunction;
  rslt: TResult;
  SessionKey: String;
  MessageBucket: String;

begin
  caller := TCaller.Create;
  caller.EndPoint := '/RPC2';
  caller.HostName := '127.0.0.1';
  caller.HostPort := 8081;
  func := TFunction.Create;

  func.ObjectMethod := 'POPFile/API.get_session_key';
  func.AddParam('admin');
  func.AddParam(//);

  rslt := caller.Execute(func);
  SessionKey := rslt.GetString;

  func.ObjectMethod := 'POPFile/API.classify';
  func.AddParam(SessionKey);
  func.AddParam(ExpandFileName(ParamStr(1)));

  rslt := caller.Execute(func);
  MessageBucket := rslt.GetString;
  Writeln(MessageBucket);

  func.ObjectMethod := 'POPFile/API.release_session_key';
  func.AddParam(SessionKey);

  caller.Free;
  func.Free;
end.

上記のソースの実装では、 Delphi XML-RPC library にある xmlrpctypes と xmlrpcclient を使用しています。 Indy - Internet Direct Components についても必要になるでしょう。

上記のソースを保存し、コンパイルすれば、popdelphi.exe ができるでしょう。これを DOS 窓で実行し、メッセージのファイル名を引数として渡し、正しく設定されたシステムを使用していれば、次のような結果が出力されるでしょう:

   popdelphi popfile99.msg
   spam

NSBasic/CE for Windows CE Example

 AddObject "PocketXMLRPC.Factory","xmlrpc"
 Set popfile = xmlrpc.proxy("http://192.168.200.1:8081/RPC2","POPFile/API.")
 sessionKey = popfile.get_session_key("admin", "")
 message = MsgBox("POPFile Session Key is " & sessionKey, vbInformation, "POPFile Message")
 Print popfile.classify(sessionKey,"C:\spam.txt")
 popfile.release_session_key(sessionKey)

この実装では、 NS Basic/CE for Windows CE を使用しています。 PocketHTTP と PocketXML-RPC COM コンポーネントも必要になります。

覚えておきましょう、ここでは、localhost にアクセスしているのではなく、POPFile をインストールしたのとは別のマシンを使用しています。そのため、モバイルマシンが、POPFile が稼働しているマシンの有効なネットワーク IPアドレスをさす必要があります。上記の例では、192.168.200.1 が POPFile が稼働しているあなたのデスクトップ PC のIP アドレスです。あなたのモバイルマシンがブルートゥースや無線LANを経由して、XMLRPC インターフェースにアクセスすることになります。また、 リモートのマシンから、XML-RPC 接続を受け付けるように 設定する必要があります。これは、セキュリティ タブではいに設定することで行います。

応用例

Perl の応用例 1 (もっと複雑なエラーチェック)

use strict;
use XMLRPC::Lite;

my $xml= XMLRPC::Lite
   -> proxy('http://localhost:8081/RPC2')->on_fault(sub{});

# 
# POPFile からセッションキーを得る
#
   
my $sk = $xml->call("POPFile/API.get_session_key",'admin',//);
my $key = $sk->result;
my $method = "POPFile/API.$ARGV[0]";
my @params = @ARGV[1..10];
   
unshift @params,$key;

my $can = $xml->can($method);
my $res = eval {$xml->call($method,@params)};
   
if ($@) {
    print join("\n","syntax error: " ,$@);
    exit(1);
} elsif ($can && !UNIVERSAL::isa($res => 'XMLRPC::SOM')) {
    print $res;
} elsif (defined($res) && $res->fault) {
    print join ("\n","XMLRPC FAULT: ", @{$res->fault}{'faultCode','faultString'});
    exit(1);
} elsif (!$xml->transport->is_success) {
    print join ("\n","TRANSPORT ERROR: ", $xml->transport->status);  
} else  {
    print join ("\n",$res->paramsall);
}

#
# セッションキーを解放する
#

$xml->call("POPFile/API.release_session_key",$key);

#
# All Done
#

exit(0);

上記のソースを testxml.pl というファイル名で保存し、コマンドラインパラメータとともに実行すれば、指定した API の実行結果が返ってきます。

   perl testxml.pl get_bucket_parameter spam count
   9418

   perl testxml.pl get_bucket_parameter spam fpcount
   24

   perl testxml.pl get_bucket_parameter spam fncount
   43

   perl testxml.pl get_bucket_color spam
   red

   perl testxml.pl get_bucket_word_count spam
   37135

   perl testxml.pl get_bucket_unique_count spam
   9407

   perl testxml.pl get_buckets
   magnet
   normal
   spam

応用例 2

pipe.pl を XMLRPC のクライアントとして実装します。

  -!/usr/bin/perl
use strict;
use XMLRPC::Lite;

  - 安全な一時ファイルを使用したいのですが、このスクリプトはふつうひとりのユーザとして動くでしょう
use File::Temp qw/tempfile tempdir/;

  - アクセスすることができるフォルダはスクリプトが終了したときに削除されるでしょう
my $temp_dir = tempdir( CLEANUP => 1);

  - フルパスが指定された一時ファイル
my ($fh_in, $filename_in) = tempfile('popfileinXXXXXXX', SUFFIX => ".msg", UNLINK => 1 , DIR => $temp_dir);

  - パイプとして動くため、標準入力 (STDIN) から読み込みます
while (<STDIN>) {
	print $fh_in $_;
}

  - POPFile は、ファイルが閉じられていることを前提とします
close $fh_in;

  - 安全な出力ファイルを作成します
my ($fh_out, $filename_out) = tempfile('popfileoutXXXXXXX', SUFFIX => ".msg", UNLINK => 1, DIR => $temp_dir);

  - XMLRPC のプロキシ
my $xmlrpc = XMLRPC::Lite ->proxy('http://localhost:8086/RPC2');

  - POPFile に挨拶して、セッションキーを取得します
my $sk = $xmlrpc-> call('POPFile/API.get_session_key','admin',//)
		-> result;

  - ここで仕事をします
$xmlrpc-> call('POPFile/API.handle_message',$sk,$filename_in,$filename_out)
		-> result;

  - POPFile にお別れをします
$xmlrpc-> call('POPFile/API.release_session_key',$sk);

  - パイプとして動くために、標準出力 (STDOUT) に書き込みます
while (<$fh_out>) {
	print $_;
}

  - 終了します。File::Temp が（一時ファイルを）片付けてくれます
exit(0);

POPFile XML-RPC の API

UI::XMLRPC モジュールを通して、POPFile の API ( POPFile::API モジュールで定義されています) すべてにアクセスすることができます。 API の文法についての詳しいドキュメントについては、POPFile と一緒に配布されている Classifier::Bayes モジュールを参照してください。

すべての API を使用するためには、まず get_session_key API を使用してセッションキーを取得しなければいけません。終了するときには、release_session_key を使ってキーを解放すべきです。

XML-RPC に存在するメソッドは下記のとおりです:

サブルーチン名		使用方法
get_session_key		call('POPFile/API.get_session_key','admin',//) セッションキーを返します
release_session_key		call('POPFile/API.release_session_key','session_key') セッションキーを解放します
classify		call('POPFile/API.classify', 'session_key', 'filename') バケツ名を返します。ファイル名(filename)は POPFile が起動しているマシンの popfile ディレクトリに存在しなければいけない（あるいはフルパスが指定されなくてはいけません）ことに注意してください。
classify_and_modify		ファイルハンドルを必要とするため、XmlRpc では動作しません。代わりに handle_message を使用してください。
handle_message		call('POPFile/API.handle_message', 'session_key', 'inputfilename', 'outputfilename') バケツ名を返します。classify に似ていますが、POPFile の履歴にメッセージを追加し、POPFile の追加ヘッダとともにメッセージを出力ファイルに書き込みます。この命令には既知の問題がありますので注意してください。現在のところ、処理するメッセージの最後に . と 0x0d0a を追加します。
get_buckets		call('POPFile/API.get_buckets','session_key') バケツ名の配列を返します
get_bucket_word_count		call('POPFile/API.get_bucket_word_count', 'session_key', 'bucketname') （指定された）バケツの単語数を返します
get_bucket_word_list		call('POPFile/API.get_bucket_word_list', 'session_key', 'bucketname') （指定された）バケツに含まれる単語の配列を返します
get_word_count		call('POPFile/API.get_word_count','session_key') すべてのバケツに含まれる単語数の合計を返します
get_bucket_unique_count		call('POPFile/API.get_bucket_unique_count', 'session_key', 'bucketname') （指定された）バケツに含まれる固有単語数を返します
get_bucket_color		call('POPFile/API.get_bucket_color', 'session_key', 'bucketname') （指定されたバケツの）色を文字列で返します
set_bucket_color		call('POPFile/API.set_bucket_color', 'session_key', 'bucketname', 'colorstring') （指定されたバケツの）色を設定し、文字列で返します
get_bucket_parameter		call('POPFile/API.get_bucket_parameter', 'session_key', 'bucketname', 'parameter') （指定されたバケツの）パラメータの値を返します。パラメータは count、fpcount、fncount のいずれかひとつです
set_bucket_parameter		call('POPFile/API.set_bucket_parameter', 'session_key', 'bucketname', 'parameter', 'value') （指定されたバケツの）パラメータの値を設定します。なにも返しません。パラメータは count、fpcount、fncount のいずれかひとつです
get_html_colored_message		注意: get_html_colored_message は間違って 0.22 で削除されてしまいましたが、0.22.1 では戻っています。 call('POPFile/API.get_html_colored_message', 'session_key', 'filename') 色を付けたメッセージを含んだ文字列が返ります。ファイル名(filename)は popfile ディレクトリに存在するか、フルパスが指定される必要があることに注意してください
create_bucket		call('POPFile/API.create_bucket', 'session_key', 'bucketname') なにも返しません
delete_bucket		call('POPFile/API.delete_bucket', 'session_key', 'bucketname') 常に 1 を返します
rename_bucket		call('POPFile/API.rename_bucket', 'session_key', 'bucketname', 'newname') 失敗したら 0 を、成功したら 1 を返します
add_message_to_bucket		call('POPFile/API.add_message_to_bucket', 'session_key', 'bucketname', 'filename') 失敗したら 0 を、成功したら 1 を返します。ファイル名(filename)は popfile ディレクトリに存在するか、フルパスが指定される必要があることに注意してください。
remove_message_from_bucket		call('POPFile/API.remove_message_from_bucket', 'session_key', 'bucketname', 'filename') 失敗したら 0 を、成功したら 1 を返します。ファイル名(filename)は popfile ディレクトリに存在するか、フルパスが指定される必要があることに注意してください
get_buckets_with_magnets		call('POPFile/API.get_buckets_with_magnets', 'session_key',) バケツ名とマグネットの配列を返します
get_magnet_types_in_bucket		call('POPFile/API.get_magnet_types_in_bucket', 'session_key', 'bucketname') （指定された）バケツに対するマグネットタイプの配列を返します
clear_bucket		call('POPFile/API.clear_bucket', 'session_key', 'bucketname') バケツを空にします。なにも返しません
clear_magnets		call('POPFile/API.clear_magnets','session_key',) なにも返しません
get_magnets		call('POPFile/API.get_magnets', 'session_key', 'bucketname','type') （指定された）バケツについて特定のタイプのマグネットの配列を返します
create_magnet		call('POPFile/API.create_magnet', 'session_key', 'bucketname', 'magnettype','magnetvalue') なにも返しません
get_magnet_types		call('POPFile/API.get_magnet_types','session_key') POPFile がサポートしているマグネットタイプの配列を返します
delete_magnet		call('POPFile/API.delete_magnet', 'session_key', 'bucketname', 'magnettype','magnetvalue') なにも返しません
get_stopword_list		call('POPFile/API.get_stopword_list','session_key') 無視する文字列（stop words）の配列を返します
add_stopword		call('POPFile/API.add_stopword', 'session_key', 'mystopword') 失敗したら 0 を、成功したら 1 を返します
remove_stopword		call('POPFile/API.remove_stopword', 'session_key', 'mystopword') 失敗したら 0 を、成功したら 1 を返します

注意: 上記の API の呼び出しにおいて、'session_key' は get_session_key API で取得することができるキーを使用します。

POPFile の古いバージョンでは、”Classifier/Bayes” を “POPFile/API” と読み替えてください。

原文