This is an old revision of the document!
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 が動作しているマシン以外からのアクセスを許可するためには、このオプションを「はい」にしなければいけません。
注意: Windows 版インストーラを使用して UI::XMLRPC モジュールをインストールした場合、これらの Perl コンポーネントは自動的にインストールされます。
以下の Perl モジュールは POPFile が動作しているマシンにインストールしなければいけません。さらに、SOAP::Lite モジュールは Perl クライアントを使って XMLRPC 経由で POPFile にアクセスするすべてのクライアントマシンにもインストールする必要があります。
ppm >install SOAP-Lite
とします。
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
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
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
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 接続を受け付けるように 設定する必要があります。これは、セキュリティ タブではいに設定することで行います。
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
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);
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” と読み替えてください。
Should you find anything in the documentation that is incomplete, unclear, outdated or just plain wrong, please let us know and leave a note in the Documentation Forum.