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 にアクセスするクライアントは、どんなマシンでも動かすことができ、また どんな プログラム言語 でも使用することができます(訳注:リンク先は英語です)。クライアントは提供されていませんので、自分で作らなければいけません。PerlPythonDelphiNSBasic/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 にある xmlrpctypesxmlrpcclient を使用しています。 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 ([email protected]) {
    print join("\n","syntax error: " ,[email protected]);
    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')

バケツ名の配列を返します (「unclassified」バケツを除く)

get_pseudo_buckets
call('POPFile/API.get_pseudo_buckets', 'session_key')

疑似バケツの名前の配列を返します (「unclassified」バケツ)

get_all_buckets
call('POPFile/API.get_all_buckets', 'session_key')

すべてのバケツの名前の配列を返します (「unclassified」バケツを含む)

is_bucket
call('POPFile/API.is_bucket','session_key', 'bucketname')

バケツが存在する場合 1 を返し、存在しない場合、あるいはバケツが疑似バケツ (「unclassified」バケツ) の場合 0 を返します

is_pseudo_bucket
call('POPFile/API.is_pseudo_bucket', 'session_key', 'bucketname')

バケツが存在し、かつ疑似バケツ (「unclassified」バケツ) である場合 1 を返し、バケツが存在しない、あるいはバケツが疑似バケツでない場合 0 を返します

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_bucket_word_prefixes
call('POPFile/API.get_bucket_word_prefixes', 'session_key', 'bucketname')

(指定された)バケツに含まれる単語の頭文字の配列を返します

get_count_for_word
call('POPFile/API.get_count_for_word', 'session_key', 'bucketname', 'someword')

(指定された)バケツに含まれる (指定された) 単語の数を返します

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')

(指定されたバケツの)色を文字列で返します 注意: この API の使用は推奨されません。代わりに get_bucket_parameter に「color」パラメータをつけて使用してください

set_bucket_color
call('POPFile/API.set_bucket_color', 'session_key', 'bucketname', 'colorstring')

(指定されたバケツの)色を設定します。成功すれば 1 を返します。注意: この API の使用は推奨されません。代わりに set_bucket_parameter に「color」パラメータをつけて使用してください

get_bucket_parameter
call('POPFile/API.get_bucket_parameter', 'session_key', 'bucketname', 'parameter')

(指定されたバケツの)パラメータの値を返します。パラメータは count (分類数)、fpcount (誤検出)、fncount (見逃し)、subject (件名の変更)、xtc (X-Text-Classification ヘッダ)、xpl (X-POPFile-Link ヘッダ)、quarantine (隔離)、color (バケツの色) のいずれかひとつです

set_bucket_parameter
call('POPFile/API.set_bucket_parameter', 'session_key', 'bucketname', 'parameter', 'value')

(指定されたバケツの)パラメータの値を設定します。成功すれば 1 を返します。パラメータは count (分類数)、fpcount (誤検出)、fncount (見逃し)、subject (件名の変更)、xtc (X-Text-Classification ヘッダ)、xpl (X-POPFile-Link ヘッダ)、quarantine (隔離)、color (バケツの色) のいずれかひとつです

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')

成功すれば 1 を返します

delete_bucket
call('POPFile/API.delete_bucket', 'session_key', 'bucketname')

成功すれば 1 を返します。「unclassified」バケツを削除することはできないことに注意してください

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')

メールファイルを用いて POPFile を鍛えます(メールファイルを指定されたバケツに再分類します)。失敗したら 0 を、成功したら 1 を返します。ファイル名(filename)は popfile ディレクトリに存在するか、フルパスが指定される必要があることに注意してください

add_messages_to_bucket
call('POPFile/API.add_messages_to_bucket', 'session_key', 'bucketname', 'filelist')

複数のメールファイルを用いて POPFile を鍛えます(メールファイルを指定されたバケツに再分類します)。失敗したら 0 を、成功したら 1 を返します。ファイル(filelist)は popfile ディレクトリに存在するか、フルパスが指定される必要があることに注意してください

remove_message_from_bucket
call('POPFile/API.remove_message_from_bucket', 'session_key', 'bucketname', 'filename')

POPFile のトレーニングを取り消します。失敗したら 0 を、成功したら 1 を返します。ファイル名(filename)は popfile ディレクトリに存在するか、フルパスが指定される必要があることに注意してください

magnet_count
call('POPFile/API.magnet_count', 'session_key',)

すべてのバケツに登録されているマグネットの数の合計を返します

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')

バケツを空にします。成功すれば 1 を返します

clear_magnets
call('POPFile/API.clear_magnets','session_key')

すべてのマグネットを削除します。成功すれば 1 を返します

get_magnets
call('POPFile/API.get_magnets', 'session_key', 'bucketname','type')

(指定された)バケツについて特定のタイプのマグネットの配列を返します

create_magnet
call('POPFile/API.create_magnet', 'session_key', 'bucketname', 'magnettype', 'magnetvalue')

新しいマグネットを作成します。成功すれば 1 を返します

get_magnet_types
call('POPFile/API.get_magnet_types', 'session_key')

POPFile がサポートしているマグネットタイプとメールヘッダのハッシュリストを返します

delete_magnet
call('POPFile/API.delete_magnet', 'session_key', 'bucketname', 'magnettype', 'magnetvalue')

マグネットを削除します。成功すれば 1 を返します

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” の代わりに使用してください。

原文

 
jp/popfilemodules/xmlrpc.txt · Last modified: 2009/09/25 18:11 by amatubu

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.

Recent changes RSS feed Donate Driven by DokuWiki
The content of this wiki is protected by the GNU Fee Documentation License