trunk/doc/nguide-ja.html

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja" lang="ja">

<head>
<meta http-equiv="Content-Language" content="ja" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="author" content="Mikio Hirabayashi" />
<meta name="keywords" content="Hyper Estraier, Estraier, full-text search, API, Node, P2P" />
<meta name="description" content="API specifications of Hyper Estraier" />
<link rel="contents" href="./" />
<link rel="alternate" href="nguide-en.html" hreflang="en" title="the English version" />
<link rel="stylesheet" href="common.css" />
<link rel="icon" href="icon16.png" />
<link rev="made" href="mailto:mikio@users.sourceforge.net" />
<title>P2P Guide of Hyper Estraier Version 1 (Japanese)</title>
</head>

<body>

<h1>P2Pガイド</h1>

<div class="note">Copyright (C) 2004-2005 Mikio Hirabayashi</div>
<div class="note">Last Update: Tue, 07 Jun 2005 06:17:00 +0900</div>
<div class="navi">[<a href="nguide-en.html" hreflang="en">English</a>] [<a href="index.ja.html">HOME</a>]</div>

<hr />

<h2 id="tableofcontents">目次</h2>

<ol>
<li><a href="#introduction">はじめに</a></li>
<li><a href="#architecture">アーキテクチャ</a></li>
<li><a href="#tutorial">チュートリアル</a></li>
<li><a href="#estmaster">ノードマスタ用コマンド</a></li>
<li><a href="#protocol">プロトコル</a></li>
<li><a href="#nodeapi">ノードAPI</a></li>
<li><a href="#estcall">クライアント用コマンド</a></li>
<li><a href="#tips">助言</a></li>
</ol>

<hr />

<h2 id="introduction">はじめに</h2>

<p>この文書では、Hyper EstraierのP2P機構の詳細な使い方を説明します。<a href="uguide-ja.html">ユーザガイド</a>をまだお読みでない場合は先にそちらに目を通しておいてください。</p>

<p>estseek.cgiで検索を行う場合、起動する度にデータベースを立ち上げ直すので、処理効率が悪いです。また、estcmdでデータベースの更新作業を行っている間は、データベースがロックされてしまうので検索ができません。これらの問題に対処するために、Hyper EstraierはC/S（クライアント/サーバ）方式のサーバプログラムを提供します。データベースを内包したプロセスをシステムに常駐させておいて、それをネットワーク経由で操作するものです。C/S方式には以下の利点があります。</p>

<ul>
<li>サーバとクライアントを別々のマシン上で動作させることができます。</li>
<li>単一のサーバに対する複数のクライアントが並列に処理を行えます。</li>
<li>クライアントがクラッシュしてもデータベースが壊れません。</li>
<li>実装言語やAPIに依存しないでクライアントを実装できます。</li>
</ul>

<p>C/S間のプロトコルはHTTPベースなので、一般的なWebブラウザをクライアントにすることが可能です。もちろん、独自のクライアントを実装していただいてもかまいませんし、WebブラウザにJavaScriptやFlashなどの技術を組み合わせることもできるでしょう。</p>

<p>複数のサーバが相互に通信することよって、P2P（Peer to Peer）方式の分散処理を行うこともできます。100万件の文書のインデックスを管理する10個のサーバを連携させれば、1000万件の文書を扱う検索システムを構築することができるというわけです。サーバ同士は対等の関係であるため、クライアントはどのサーバにアクセスしてもサービスを享受することができますし、どれかのサーバがダウンしてもシステム全体が停止することはありません。また、サーバ間の信頼度を元に検索精度を向上させる仕組みも備わっています。</p>

<p>C/S間のプロトコルを隠蔽する「ノードAPI」も提供されます。ノードAPIを使えば、ネットワークに関する詳細な知識がなくても、クライアントのプログラムを実装することができます。この文書では、ノードAPIの使い方についても説明します。</p>

<hr />

<h2 id="architecture">アーキテクチャ</h2>

<p>ここでは、Hyper EstraierにおけるP2Pのアーキテクチャについて説明します。</p>

<h3>ノードマスタとノードサーバ</h3>

<p>多数のインデックスを管理することを想定した場合、インデックス毎にサーバを起動するのは非効率です。したがって、単一のプロセスおよび単一のポートで複数のインデックスを管轄できる「ノードマスタ」というプログラムが提供されます。ノードマスタ内の個々のインデックスは独立したサービスを提供するので、ノードマスタは複数のサーバの集合体とみなすこともできます。そこで、個々のインデックスを管轄する仮想的なサーバを「ノードサーバ」と呼ぶことにします。各ノードサーバには別々のURLが割り当てられます。ユーザが操作するアプリケーションはノードサーバのクライアントとして位置づけられますが、接続先のノードサーバについてはURLだけ知っていればよく、ノードサーバがどのノードマスタ上に存在しているかをアプリケーション側で意識する必要はありません。</p>

<div class="illust"><img src="nodeframe.png" width="720" height="350" alt="[framework]" /></div>

<p>「ノード（node）」という用語をここではP2P機構における「ピア（peer）」とほぼ同じ意味で使っています。クライアントは、ノードマスタそのものに接続してノードの管理を行うとともに、各々のノードサーバに接続してインデックスに対する検索や文書の登録などの操作を行うことができます。</p>

<h3>メタ検索と信頼度</h3>

<p>ノードサーバは別のノードサーバに対して一方的にリンクを張ることができます。クライアントがノードサーバに検索要求を出した場合、依頼を受けたノードサーバは自分がリンクを張っているノードサーバにもクエリを中継し、返された結果を自分のインデックスの結果とマージしてクライアントに返します。つまり、いわゆるメタ検索機能を全てのノードサーバが持つことによって、P2P型の分散処理を実現しているのです。</p>

<p>メタ検索は多階層的に行われます。経路の循環は自動的に検出されて抑止されますので、検索時には木構造のネットワークからデータを収集しているような挙動になります。この機構によって、検索対象となるノードの数は際限なく増やしていくことが可能になります。</p>

<div class="illust"><img src="metatree.png" width="720" height="400" alt="[tree of meta search]" /></div>

<p>ノード間の各リンクには、信頼度という数値が定義されます。ノードがメタ検索の結果をマージする際には、スコアの重みづけに信頼度が利用されます。信頼度が高いノードの結果は上位に来やすいということです。リンク作成や信頼度設定の指示はアプリケーションに任されますが、よく利用されるノードの信頼度を高めるように指示することによって、検索の精度が高めて行くことができます。</p>

<h3>認証</h3>

<p>クライアントがノードマスタやノードサーバに接続する際には、ユーザ名とパスワードを用いた認証が行われます。ユーザには、スーパーユーザと普通のユーザの2種類があります。前者はノードの管理やユーザの管理を行う権限を持つユーザで、後者はそれらの権限を持たないユーザです。また、ノードサーバの単位でも権限の付与が行われます。各ノードについて、インデックスの更新が可能な管理者ユーザのリストと、検索だけが可能な普通のユーザのリストが管理されます。なお、ノードマスタのスーパーユーザは配下のどのノードにも管理者としてアクセスできます。ユーザの管理はクライアントがノードマスタに指示を出すことで行います。</p>

<hr />

<h2 id="tutorial">チュートリアル</h2>

<p>P2Pの概念はなかなか難解なものですが、まずはコマンドを使ってみながら雰囲気を掴んで行きましょう。</p>

<h3>起動と終了</h3>

<p>ノードマスタを動作させる準備として、サーバルートディレクトリを作成します。設定ファイルやインデックスなどを格納するディレクトリです。以下のコマンドを実行すると、「casket」というディレクトリが作成されます。</p>

<pre>estmaster init casket
</pre>

<p>次に、ノードマスタを起動します。以下のようにします。</p>

<pre>estmaster start casket
</pre>

<p>ノードマスタを終了させる場合は、ノードマスタを実行している端末でCtrl-Dを入力するか、別の端末で以下のコマンドを実行します。</p>

<pre>estmaster stop casket
</pre>

<h3>管理用インターフェイス</h3>

<p>ノードマスタが起動しているならば、「http://localhost:1978/masterui」というURLにWebブラウザでアクセスすることで、管理用インターフェイスを使うことができます。アクセスするとユーザ名とパスワードを聞かれるダイアログが出ますので、「admin」「admin」と入力してください。すると、管理用のメニューが表示されます。</p>

<p>「Manage Master」経由で「SHUTDOWN」を選ぶとノードマスタを終了させられますが、今は放っておきましょう。</p>

<p>「Manage Users」を選んでください。今は「admin」というユーザでログインしていますが、新しいユーザを作っておきましょう。画面の下の方にある入力フォームに、右からユーザ名、パスワード、フラグ、本名、その他の情報を入力します。ユーザ名とパスワードは英数字とハイフンとアンダースコアで指定します。とりあえずは、「mikio」「oikim」「s」「平林幹雄」「管理用ユーザ」としてみましょう。フラグに「s」を入力しているのが重要なところです。そのユーザが管理者権限を持つことを指示しています。</p>

<p>もはや「admin」ユーザは不要です。セキュリティの問題となるので、消してしまいましょう。「admin」の欄にある「DELE」を選択して、確認の画面で「delete」を選択してください。</p>

<p>次に、「Manage Nodes」を選択してください。もう「admin」ユーザが消えてしまったので、再びユーザ名とパスワードを聞かれます。先ほどの「mikio」「oikim」を入力すると進むことができます。今度は新しいノードを作ります。画面の下の方にある入力フォームにノード名とラベルを指定します。ノード名は英数字とハイフンとアンダースコアで指定します。とりあえずは、「test1」「テスト用ノードその壱」というノードと、「test2」「テスト用ノードその弍」というノードを作ってください。</p>

<h3>文書の登録</h3>

<p>今度はコマンドラインの操作に戻ります。管理用インターフェイスの画面は閉じて構いません。ノードマスタを起動した端末はいろいろログが出て塞がれているでしょうから、別の端末を立ち上げてください。</p>

<p>ノードのインデックスに文書を登録してみましょう。登録対象の文書は文書ドラフト形式で表現する必要がありますので、予め以下のようなファイルを「data001.est」という名前で作成してください。</p>

<pre>@uri=data001
@title=Material Girl

Living in a material world
And I am a material girl
You know that we are living in a material world
And I am a material girl
</pre>

<p>「test1」ノードに文書を登録するには、以下のコマンドを実行します。インデックスの更新には管理者権限が必要なので、-authオプションで管理者のユーザ名とパスワードを指定しています。登録処理は一瞬で終わるので、本当に登録されているか疑いたくなるかもしれませんが、何もメッセージが出なければ成功ということです。</p>

<pre>estcall put -auth mikio oikim http://localhost:1978/node/test1 data001.est
</pre>

<p>メタ検索の説明のために、「test2」ノードにも文書を登録しておきましょう。以下のファイルを「data002.est」として作成してください。</p>

<pre>@uri=data002
@title=Liberian Girl

Liberian girl
You came and you changed My world
A love so brand new
</pre>

<p>そして、以下のコマンドを実行してください。</p>

<pre>estcall put -auth mikio oikim http://localhost:1978/node/test2 data002.est
</pre>

<p>文書ドラフト形式のファイルさえ作れば、リモートマシンからでも文書の登録ができるのがミソです。同じ要領で、いくつかの文書を登録してみてください。</p>

<h3>文書の検索</h3>

<p>では、登録した文書を対象とした検索を行ってみましょう。以下のコマンドを実行します。</p>

<pre>estcall search http://localhost:1978/node/test1 "material world"
</pre>

<p>すると、先ほど登録した文書の情報が表示されます。なお、日本語（UTF-8）が表示できない端末だと文字化けするかもしれません。</p>

<p>ノード間にリンクを張ることで、メタ検索を行うことができるようになります。試しに、「test1」から「test2」に対してリンクを張ってみましょう。リンク元のURL、リンク先のURL、表示用のラベル、信頼度の順で引数を指定します。</p>

<pre>estcall setlink -auth mikio oikim http://localhost:1978/node/test1 \
  http://localhost:1978/node/test2 TEST02 8000
</pre>

<p>ではまた検索してみましょう。今度は-dptオプションでメタ検索の深度を指定します。</p>

<pre>estcall search -dpt 1 http://localhost:1978/node/test1 "girl"
</pre>

<p>「test1」に対して検索したのに、「test2」の結果もマージされて表示されます。これがP2P型のメタ検索です。「test1」と「test2」が別々のコンピュータにあれば、分散処理ができるわけです。</p>

<p>リンクの信頼度を高くすると、リンク先のノードが返した結果の方が表示順位が上がります。以下のコマンドを実行してから、先ほどと同じコマンドで検索してみてください。ちゃんと順位が入れ替わっていますよね。</p>

<pre>estcall setlink -auth mikio oikim http://localhost:1978/node/test1 \
  http://localhost:1978/node/test2 TEST02 12000
</pre>

<p>検索結果をXML形式で取得することもできます。以下のコマンドを実行してみてください。XMLの詳しい書式についてはestresult.dtdをご覧ください。</p>

<pre>estcall search -dpt 1 -vx http://localhost:1978/node/test1 "girl"
</pre>

<p>コマンドラインで検索しても大して面白くないので、Webブラウザで検索できるインターフェイスも用意されています。「http://localhost:1978/node/test1/searchui」にアクセスしてみてください。</p>

<h3>アプリケーションの開発</h3>

<p>文書ドラフト形式のデータを作るのは面倒くさいし、付属の検索用インターフェイスもちょっと渋い感じですよね。しかし、ここから先はあなたの出番なのです。estcallコマンドやノードAPIを使って小粋なアプリケーションを作ってみてください。この文書の残りの項目では、そのための詳細な説明をします。</p>

<hr />

<h2 id="estmaster">ノードマスタ用コマンド</h2>

<p>ノードマスタを管理するためのコマンドとして「estmaster」が提供されます。ここではその仕様を説明します。</p>

<h3>書式</h3>

<p>estmasterは多くのサブコマンドの集合体です。サブコマンドの名前は第1引数で指定されます。その他の引数はサブコマンドの種類に応じて解釈されます。<var>rootdir</var> という引数はサーバルートディレクトリのパスです。サーバルートディレクトリとは、ノードマスタの動作に必要な設定ファイルなどを格納するディレクトリツリーのトップのことです。</p>

<dl>
<dt><kbd>estmaster init [-ex] <var>rootdir</var></kbd></dt>
<dd>サーバルートディレクトリを作成します。</dd>
<dd>-exを付けると、サンプルのユーザとノードを作成します。デフォルトでは、ユーザ名とパスワードがともに「admin」であるスーパーユーザのみが作成されます。</dd>
</dl>

<dl>
<dt><kbd>estmaster start [-bg] [-st] <var>rootdir</var></kbd></dt>
<dd>ノードマスタを起動します。</dd>
<dd>-bgをつけると、デーモンプロセスとしてバックグラウンドで実行します。</dd>
<dd>-stをつけると、マルチスレッドを使わずにシングルスレッドで動作します。</dd>
</dl>

<dl>
<dt><kbd>estmaster stop <var>rootdir</var></kbd></dt>
<dd>起動中のノードマスタを終了させます。</dd>
</dl>

<dl>
<dt><kbd>estmaster unittest <var>rootdir</var></kbd></dt>
<dd>ユニットテストを行います。</dd>
</dl>

<dl>
<dt><kbd>estmaster crypt <var>key</var> [<var>hash</var>]</kbd></dt>
<dd>指定した文字列の暗号用ハッシュ値を出力します。</dd>
<dd><var>key</var>は処理対象の文字列を指定します。</dd>
<dd><var>hash</var>を指定すると、キーとハッシュが対応するかどうかを判定します。</dd>
</dl>

<p>全てのサブコマンドは、処理が正常に終了した場合には0を、そうでない場合は1を終了ステータスにします。起動中のノードマスタに2（SIGINT）、3（SIGQUIT）、15（SIGTERM）のどれかのシグナルを送ることにより、データベースを閉じて正常終了させることができます。また、起動中のノードマスタにシグナル1（SIGHUP）を送ることにより、再起動して設定ファイルを読み込み直させることができます。</p>

<p>ノードマスタを終了させるにはコマンドラインによる方法や後述のネットワーク経由による方法がありますが、いずれにせよ、必ず規定の手順で終了させてください。さもなくばインデックスのデータが壊れる可能性があります。</p>

<h3>サーバルートディレクトリの構成</h3>

<p>サーバルートディレクトリは以下のファイルやディレクトリを格納しています。</p>

<ul>
<li><kbd>_conf</kbd> : 設定ファイル。詳細は後述します。</li>
<li><kbd>_user</kbd> : ユーザアカウントファイル。詳細は後述します。</li>
<li><kbd>_log</kbd> : ログファイル。サーバのイベントログや各クライアントのアクセスログを記録します。</li>
<li><kbd>_meta</kbd> : メタデータのデータベースファイル。重複起動防止のロック機構も兼ねます。</li>
<li><kbd>_pid</kbd> : プロセスIDファイル。起動中のノードマスタのプロセスIDが書かれます。</li>
<li><kbd>_stop</kbd> : 停止指示用ファイル。このファイルがあるとノードマスタは自分で停止しようとします。</li>
<li><kbd>_node/</kbd> : ノードディレクトリ。各ノードの転置インデックスを格納します。</li>
<li><kbd>_sess/</kbd> : セッションディレクトリ。各ユーザのセッション情報を格納します。現状では未使用です。</li>
</ul>

<p>設定ファイルやユーザアカウントは任意のエディタで書き換えることができます。ただし、ユーザアカウントファイルは起動中のノードマスタが停止する際に更新されますので、ユーザアカウントファイルの編集はノードマスタを止めてから行ってください。</p>

<p>estcmdで作成したデータベースをノードディレクトリに入れてからノードマスタを起動すると、そのデータベースをノードとして利用することができるようになります。</p>

<h3>設定ファイル</h3>

<p>設定ファイルは、変数名と値を「:」で区切った形式の行を並べたものです。デフォルトでは、設定ファイルは以下のような内容になっています。</p>

<pre>hostname: localhost
portnum: 1978
runmode: 1
authmode: 2
maxconn: 30
sessiontimeout: 600
searchtimeout: 8
searchdepth: 5
proxyhost:
proxyport:
loglevel: 2
docroot:
indexfile:
trustednodes:
denyuntrusted: 0
cachesize: 64
specialcache:
snipwwidth: 480
sniphwidth: 96
snipawidth: 96
</pre>

<p>それぞれの変数の機能を以下に示します。</p>

<ul>
<li><kbd>hostname</kbd> : サーバのホスト名を指定します。</li>
<li><kbd>portnum</kbd> : サーバのポート番号を指定します。</li>
<li><kbd>runmode</kbd> : 運用モードを指定します。1は通常モード、2は読み込み専用モードです。</li>
<li><kbd>authmode</kbd> : 認証モードを指定します。1は認証を一切しないモード、2は管理機能のみで認証を行うモード、3は全ての操作で認証を行うモードです。</li>
<li><kbd>maxconn</kbd> : 最大同時接続数を指定します。</li>
<li><kbd>sessiontimeout</kbd> : セッションのタイムアウトを秒単位で指定します。未実装です。</li>
<li><kbd>searchtimeout</kbd> : 検索処理のタイムアウトを秒単位で指定します。</li>
<li><kbd>searchdepth</kbd> : メタ検索の最大深度を指定します。</li>
<li><kbd>proxyhost</kbd> : プロクシサーバのホスト名を指定します。</li>
<li><kbd>proxyport</kbd> : プロクシサーバのポート番号を指定します。</li>
<li><kbd>loglevel</kbd> : ログのレベルを指定します。1ならデバッグ、2なら通常、3なら警告、4ならエラー、5なら無しです。</li>
<li><kbd>docroot</kbd> : 通常のWebサーバとして公開するディレクトリのパスを指定します。不要なら空文字列にします。</li>
<li><kbd>indexfile</kbd> : 通常のWebサーバとして公開する際のディレクトリのインデックスファイルの名前を指定します。不要なら空文字列にします。</li>
<li><kbd>trustednodes</kbd> : 認証を省略するノード（クライアント）のIPアドレスを10進数ドット付き表記で指定します。</li>
<li><kbd>denyuntrusted</kbd> : 正数なら上記のノード以外からのアクセスを拒絶します。</li>
<li><kbd>cachesize</kbd> : インデックス用キャッシュのサイズをメガバイト単位で指定します。</li>
<li><kbd>specialcache</kbd> : スペシャルキャッシュの属性名を指示します。</li>
<li><kbd>snipwwidth</kbd> : 検索結果の紹介文の全体の幅を指示します。</li>
<li><kbd>sniphwidth</kbd> : 検索結果の紹介文を作る際に文書の冒頭から取得する幅を指示します。</li>
<li><kbd>snipawidth</kbd> : 検索結果の紹介文を作る際に検索語の周辺から取得する幅を指示します。</li>
</ul>

<h3>ユーザアカウントファイル</h3>

<p>ユーザアカウントファイルは、ユーザ名、暗号化されたパスワード、フラグ、フルネーム、雑多な情報をタブ区切りで並べた行を並べたものです。文字コードはUTF-8です。デフォルトでは以下のような内容になっています。</p>

<pre>admin   21232f297a57a5a743894a0e4a801fc3        s       Carolus Magnus  Administrator
</pre>

<p>パスワードはMD5のハッシュ値で表現されます。フラグには、管理者であることを示す「s」とアクセス禁止者であることを示す「b」を用いることができます。フラグとフルネームと雑多な情報は省略可能です。</p>

<h3>内蔵ユーザインターフェイス</h3>

<p>Webブラウザで、ノードマスタの相対URL「/masterui」にアクセスすると、管理用のインターフェイスを使うことができます。管理用インターフェイスを使うには、スーパーユーザのアカウントでログインする必要があります。</p>

<p>Webブラウザで、ノードサーバのURLの後ろに「/searchui」をつけたURLにアクセスすると、検索用のインターフェイスを使うことができます。</p>

<hr />

<h2 id="protocol">プロトコル</h2>

<p>ノード間およびクライアント・ノード間の通信はHTTPベースのプロトコルに基づいて行われます。ここでは、その具体的な仕様について見て行きます。</p>

<h3>概要</h3>

<p>ノードマスタおよびノードサーバはHTTP/1.0を実装しています。現状では、HTTP/1.1特有の機能であるキープアライブ接続やチャンクエンコーディングや各種のネゴシエーションには対応していません。</p>

<p>HTTPのメソッドはGETでもPOSTでも構いませんが、情報を取得するだけの場合はGET、ノードマスタやノードサーバに更新が発生する場合はPOSTを使うことが推奨されます。パラメータの文字コードはUTF-8ですが、URLに含められない文字にはURLエンコード（application/x-www-form-urlencoded）を施す必要があります。GETメソッドで送れるデータのサイズは8000バイトまでです。ユーザ名とパスワードの受け渡しはHTTPのBasic認証機構を使って行われます。</p>

<p>処理が成功した場合は原則的に200または202のステータスコードが返ります。エラーの場合は、以下のステータスコードが返ります。</p>

<ul>
<li>400 : パラメータが不正です。</li>
<li>401 : 認証情報がないか、間違っています。</li>
<li>403 : 現在のアカウントにはアクセス権限がありません。</li>
<li>404 : 接続先のパスが存在しません。</li>
<li>500 : サーバに原因があるエラーが発生しました。</li>
</ul>

<p>検索等の操作ではメッセージボディに結果のデータが含まれます。データ形式はUTF-8のテキストですが、タブや改行で構造化されている場合もあります。操作の種類によって結果の解釈方法は変わります。</p>

<h3>ノードマスタの操作</h3>

<p>ノードマスタに対する操作は「/master」というパスに接続することで行います。例えばホスト名が「skyhigh.estraier.go.jp」でポートが「8888」の場合は、「http://skyhigh.estraier.go.jp:8888/master」に接続することになります。ノードマスタの操作はスーパーユーザのみが行えます。ノードマスタの操作はいくつかのサブコマンドからなりますが、サブコマンドの名前は「action」パラメータで指定します。その他のパラメータはサブコマンドによって変わります。パラメータの順番は任意です。</p>

<dl>
<dt><kbd>/master?action=shutdown</kbd></dt>
<dd>ノードマスタをシャットダウンします。</dd>
<dd>パラメータはありません。</dd>
<dd>成功すれば202のステータスコードが返信されます。</dd>
</dl>

<dl>
<dt><kbd>/master?action=userlist</kbd></dt>
<dd>ユーザアカウントのリストを取得します。</dd>
<dd>パラメータはありません。</dd>
<dd>成功すれば200のステータスコードとともにTSV形式のリストが返信されます。各行が各ユーザの情報を表し、ユーザ名、暗号化されたパスワード、フラグ、フルネーム、その他の情報をタブ区切りのフィールドとして表現します。</dd>
</dl>

<dl>
<dt><kbd>/master?action=useradd&amp;name=<var>str</var>&amp;passwd=<var>str</var>&amp;flags=<var>str</var>&amp;fname=<var>str</var>&amp;misc=<var>str</var></kbd></dt>
<dd>ユーザアカウントを追加します。</dd>
<dd><var>name</var>は新規のユーザ名を指定します。必須です。ユーザ名に利用できる文字はUS-ASCIIの英数字とハイフンとアンダーバーのみです。既存のユーザ名と重複していた場合はエラーになります。</dd>
<dd><var>passwd</var>はパスワードを指定します。必須です。</dd>
<dd><var>flags</var>はフラグを指定します。省略可能です。</dd>
<dd><var>fname</var>はフルネームを指定します。省略可能です。</dd>
<dd><var>misc</var>は雑多な情報を指定します。省略可能です。</dd>
<dd>成功すれば200のステータスコードが返信されます。</dd>
<dd>パスワードを送信することになるため、パラメータはPOSTメソッドで送信すべきです。</dd>
</dl>

<dl>
<dt><kbd>/master?action=userdel&amp;name=<var>str</var></kbd></dt>
<dd>ユーザアカウントを削除します。</dd>
<dd><var>name</var>はユーザ名を指定します。必須です。</dd>
<dd>成功すれば200のステータスコードが返信されます。</dd>
</dl>

<dl>
<dt><kbd>/master?action=nodelist</kbd></dt>
<dd>ノードサーバのリストを取得します。</dd>
<dd>パラメータはありません。</dd>
<dd>成功すれば200のステータスコードとともにTSV形式のリストが返信されます。各行が各ノードの情報を表し、ノード名、ラベル、登録文書数、登録語数、サイズをタブ区切りのフィールドとして表現します。</dd>
</dl>

<dl>
<dt><kbd>/master?action=nodeadd&amp;name=<var>str</var>&amp;label=<var>str</var></kbd></dt>
<dd>ノードサーバを追加します。</dd>
<dd><var>name</var>は新規のノード名を指定します。必須です。ノード名に利用できる文字はUS-ASCIIの英数字とハイフンとアンダーバーのみです。既存のノード名と重複していた場合はエラーになります。</dd>
<dd><var>label</var>はラベルを指定します。省略可能です。省略した場合はノード名と同じラベルが付けられます。</dd>
<dd>成功すれば200のステータスコードが返信されます。</dd>
</dl>

<dl>
<dt><kbd>/master?action=nodedel&amp;name=<var>str</var></kbd></dt>
<dd>ノードサーバを削除します。</dd>
<dd><var>name</var>はノード名を指定します。必須です。</dd>
<dd>成功すれば200のステータスコードが返信されます。</dd>
</dl>

<h3>ノードサーバの操作</h3>

<p>各ノードサーバに対する操作は「/node/」の後にノード名をつけたパスに接続することで行います。例えばホスト名が「skyhigh.estraier.go.jp」でポートが「8888」でノード名が「foo」の場合は、「http://skyhigh.estraier.go.jp:8888/node/foo」に接続することになります。ノードマスタの操作はいくつかのサブコマンドからなりますが、サブコマンドの名前はノード名の後に「/」を挟んで指定します。パラメータはサブコマンドによって変わります。パラメータの順番は任意です。ノードマスタの操作は検索系と更新系の二つに大別できますが、前者はどのユーザでも実行でき、後者はそのノードの管理者のみが実行できます。</p>

<dl>
<dt><kbd>/node/<var>name</var>/inform</kbd></dt>
<dd>ノードの情報を取得します。</dd>
<dd>パラメータはありません。</dd>
<dd>成功すれば200のステータスコードとともにTSV形式のデータが返信されます。第1行目は、ノード名、ラベル、登録文書数、登録語数、サイズをタブ区切りのフィールドとして表現したものです。空行を挟んで、次の空行までの各行は管理者のユーザ名のリストです。空行を挟んで、次の空行までの各行は一般ユーザのユーザ名のリストです。空行を挟んで、以降はリンク情報のリストです。リンク情報の各行はURLとラベルと信頼度をタブ区切りのフィールドで表現したものです。</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/search?phrase=<var>str</var>&amp;attr=<var>str</var>&amp;order=<var>str</var>&amp;max=<var>num</var>&amp;options=<var>num</var>&amp;depth=<var>num</var></kbd></dt>
<dd>検索を実行します。</dd>
<dd><var>phrase</var>は検索フレーズを指定します。省略可能です。書式はコアAPIのものと同じです。</dd>
<dd><var>attr</var>は属性条件を指定します。省略可能です。<var>attr1</var>から<var>attr9</var>を使って複数の属性条件を指定することも可能です。書式はコアAPIのものと同じです。</dd>
<dd><var>order</var>はソート条件を指定します。省略可能です。書式はコアAPIのものと同じです。</dd>
<dd><var>max</var>は取得件数を指定します。省略可能です。デフォルトは10です。</dd>
<dd><var>options</var>はオプションを指定します。省略可能です。値はコアAPIのものと同じです。</dd>
<dd><var>depth</var>はメタ検索の深度を指定します。省略可能です。デフォルトは0です。</dd>
<dd>成功すれば200のステータスコードとともに検索結果のデータが返信されます。詳細は後述します。</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/get_doc?id=<var>num</var>&amp;uri=<var>str</var></kbd></dt>
<dd>文書の情報を取得します。</dd>
<dd><var>id</var>は対象文書のID番号を指定します。省略可能です。</dd>
<dd><var>uri</var>は対象文書のURIを指定します。省略可能です。</dd>
<dd>成功すれば200のステータスコードとともに文書ドラフト形式のデータが返信されます。</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/get_doc_attr?id=<var>num</var>&amp;uri=<var>str</var>&amp;attr=<var>str</var></kbd></dt>
<dd>文書の属性値を取得します。</dd>
<dd><var>id</var>は対象文書のID番号を指定します。省略可能です。</dd>
<dd><var>uri</var>は対象文書のURIを指定します。省略可能です。</dd>
<dd><var>attr</var>は属性名を指定します。必須です。</dd>
<dd>成功すれば200のステータスコードとともに属性値のデータが返信されます。</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/uri_to_id?uri=<var>str</var></kbd></dt>
<dd>URIに対応する文書のID番号を取得します。</dd>
<dd><var>uri</var>は対象文書のURIを指定します。必須です。</dd>
<dd>成功すれば200のステータスコードとともに該当文書のID番号が返信されます。</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/put_doc?draft=<var>str</var></kbd></dt>
<dd>文書を登録します。管理者のみが利用できます。</dd>
<dd><var>draft</var>は対象文書の内容を文書ドラフト形式で指定します。必須です。</dd>
<dd>成功すれば200のステータスコードが返信されます。</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/out_doc?id=<var>num</var>&amp;uri=<var>str</var></kbd></dt>
<dd>文書を削除します。管理者のみが利用できます。</dd>
<dd><var>id</var>は対象文書のID番号を指定します。省略可能です。</dd>
<dd><var>uri</var>は対象文書のURIを指定します。省略可能です。</dd>
<dd>成功すれば200のステータスコードが返信されます。</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/_set_user?name=<var>str</var>&amp;mode=<var>num</var></kbd></dt>
<dd>ユーザのアクセス権限を設定します。管理者のみが利用できます。</dd>
<dd><var>name</var>はユーザ名を指定します。必須です。</dd>
<dd><var>mode</var>は操作内容を指定します。必須です。0なら指定したユーザのアクセス権限を剥奪します。1なら指定したユーザを管理者として登録します。2なら指定したユーザを一般ユーザとして登録します。</dd>
<dd>成功すれば200のステータスコードが返信されます。</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/_set_link?url=<var>str</var>&amp;label=<var>str</var>&amp;credit=<var>num</var></kbd></dt>
<dd>他のノードへのリンクを設定します。管理者のみが利用できます。</dd>
<dd><var>url</var>はリンク先のノードサーバのURLを指定します。必須です。既存のリンクと重複していた場合はラベルと信頼度が再設定されます。</dd>
<dd><var>label</var>はリンク先のノードサーバのラベルを指定します。必須です。</dd>
<dd><var>credit</var>はリンクの信頼度を指定します。省略可能です。省略した場合はリンクが削除されます。</dd>
<dd>成功すれば200のステータスコードが返信されます。</dd>
</dl>

<p>ノードマスタのスーパーユーザは各ノードの管理権限を持ちますが、各ノードの管理者はノードマスタのスーパーユーザとは限らないということに注意してください。また、各ノードの一般ユーザは、認証モードを3（all）にした場合にのみ意味を持ちます。</p>

<h3>検索結果の書式</h3>

<p>searchコマンドの結果のエンティティボディは、MIMEのマルチパートに似た形式をとります。以下に例を示します。</p>

<pre>--------[2387AD2E34554FFF]--------
VERSION 0.9
NODE    http://localhost:1978/node/sample1
HIT     2
HINT#1  give    2
DOCNUM  2
WORDNUM 31
TIME    0.001
LINK#0  http://localhost:1978/node/sample1      Sample1 10000   2       31      2731304 2
LINK#1  http://localhost:1978/node/sample2      Sample2 4000    3       125     8524522 1
VIEW    SNIPPET

--------[2387AD2E34554FFF]--------
#nodelabel=Sample Node One
#nodeurl=http://localhost:1978/node/sample1
@id=1
@uri=http://localhost/foo.html

You may my glories and my state dispose, But not my griefs; still am I king of those. (
Give    give
 it u

p, Yo!
Give    give
 it up, Yo!)

--------[2387AD2E34554FFF]--------
#nodelabel=Sample Node One
#nodeurl=http://localhost:1978/node/sample1
@id=2
@uri=http://localhost/bar.html

The faster I go, the behinder I get. (
Give    give
 it up, Yo!
Give    give
 it up, Yo!)

--------[2387AD2E34554FFF]--------:END
</pre>

<p>改行コードは単一のLFです。第1行目は区切り文字列の定義です。ここで定義された文字列の行で、パートが区切られます。最後の区切り文字列の末尾には「:END」という文字列がつきます。最初のパートはメタ部です。それ以降のパートは文書部です。</p>

<p>メタ部は、TSV形式をとります。各行の意味は第1フィールドの文字列で識別できます。以下の種類があります。</p>

<ul>
<li><kbd>VERSION</kbd> : プロトコルのバージョンを示します。</li>
<li><kbd>NODE</kbd> : ノードのURLを示します。</li>
<li><kbd>HIT</kbd> : 該当文書数の総計を示します。</li>
<li><kbd>HINT#<var>n</var></kbd> : 各検索語の該当数を示します。第2フィールドが語で、第3フィールドが該当数です。</li>
<li><kbd>DOCNUM</kbd> : 登録文書数の総計を示します。</li>
<li><kbd>WORDNUM</kbd> : 登録語数の総計を示します。</li>
<li><kbd>TIME</kbd> : 処理にかかった時間をミリ秒単位で示します。</li>
<li><kbd>LINK#<var>n</var></kbd> : 各ノードの情報を示します。第2フィールドはURL、第3フィールドはラベル、第4フィールドは信頼度、第5フィールドは登録文書数、第6フィールドは登録語数、第8フィールドはデータベースのサイズ、第8フィールドは該当文書数です。LINK#0はそのノード自身の情報を示します。</li>
<li><kbd>VIEW</kbd> : 文書パートの形式を示します。現状ではSNIPPETのみが定義されています。</li>
</ul>

<p>文書部は、該当文書の属性情報とスニペットを示します。最初の空行までが属性情報で、それ以降が紹介文です。属性情報の形式は文書ドラフトと同じです。紹介文の形式はTSVです。その各行は表示すべき文字列です。ほとんどの行は単一のフィールドしか持ちませんが、いくつかは二つのフィールドを持ちます。もし第2フィールドが存在したならば、第1フィールドはハイライトして表示すべき文字列で、第2フィールドはその正規化された文字列です。</p>

<p>searchコマンドやget_docコマンドの操作を行った際に返される文書情報には、以下の疑似属性が付加されます。</p>

<ul>
<li><kbd>#nodeurl</kbd> : その文書が登録されているノードのURL。</li>
<li><kbd>#nodelabel</kbd> : その文書が登録されているノードのラベル。</li>
</ul>

<h3>文書登録の特殊形式</h3>

<p>put_docコマンドでは大きなサイズのパラメータを送ることが多いですが、それをURLエンコードすると効率が悪くなります。POSTメソッドのContent-Typeヘッダの値を「text/x-estraier-draft」にすると、エンティティボディとして文書ドラフトそのものを送ることができます。例えば、以下のようなリクエストを送信します。</p>

<pre>POST /node/foo/put_doc HTTP/1.0
Content-Type: text/x-estraier-draft
Content-Length: 138

@uri=http://gogo.estraier.go.jp/sample.html
@title=Twinkle Twinkle Little Star

Twinkle, twinkle, little star,
How I wonder what you are.
</pre>

<hr />

<h2 id="nodeapi">ノードAPI</h2>

<p>ノードサーバを操作する際にHTTPを駆使するのが面倒な場合はノードAPIを使うと便利です。ここではその詳細について説明します。</p>

<h3>概要</h3>

<p>ノードAPIを使えば、TCP/IPやHTTPについての低レベルな処理を気にすることなく、ノードサーバと通信を行うことができます。コアAPIと比べると通信の分のオーバーヘッドがかかりますが、リモートホストから実行できたり、リーダやライタの区別を気にせずに並列処理ができるといった利点は重要です。</p>

<p>ノードAPIを使うアプリケーションのソースコードでは、estraier.hとestnode.hとcabin.hとstdlib.hをインクルードしてください。 </p>

<pre>#include &lt;estraier.h&gt;
#include &lt;estnode.h&gt;
#include &lt;cabin.h&gt;
#include &lt;stdlib.h&gt;
</pre>

<p>アプリケーションをビルドする際には、以下ようなコマンドを実行してください。コアAPIのビルド方法と全く同じです。</p>

<pre>gcc `estconfig --cflags` -o foobar foobar.c `estconfig --ldflags` `estconfig --libs`
</pre>

<p>ノードAPIを利用する際には、コアAPIで定義されている機能も利用することになりますので、<a href="pguide-ja.html">プログラミングガイド</a>をまだお読みでない場合は先にそちらに目を通しておいてください。</p>

<h3>初期化のためのAPI</h3>

<p>ノードAPIのネットワーク機能を使う前提として、プログラムの冒頭でネットワーク環境を初期化してください。また、プログラムが終了する際にはネットワーク環境を破棄してください。</p>

<p>ネットワーク環境を初期化するには、関数 `est_init_net_env' を用います。</p>

<dl>
<dt><kbd>int est_init_net_env(void);</kbd></dt>
<dd>戻り値は成功なら真、エラーなら偽です。</dd>
</dl>

<p>ネットワーク環境を破棄するには、関数 `est_free_net_env' を用います。</p>

<dl>
<dt><kbd>void est_free_net_env(void);</kbd></dt>
<dd>パラメータや戻り値はありません。</dd>
</dl>

<h3>ノードを扱うAPI</h3>

<p>構造体型 `ESTNODE' は、ノードとの接続を抽象化したものです。各ノードはURLで識別されます。`ESTNODE' の実体が直接参照されることはなく、必ずポインタを介して間接参照されます。このポインタおよびその参照先を総じてノード接続オブジェクトと呼びます。ノード接続オブジェクトは関数 `est_node_new' によって生成され、`est_node_delete' によって破棄されます。生成されたノード接続オブジェクトは必ず破棄してください。</p>

<p>ノード接続オブジェクトの典型的なライフサイクルを以下に示します。</p>

<pre>ESTNODE *node;

/* 生成する */
node = est_node_new("http://estraier.gov:1978/node/foo");

/* プロクシとタイムアウトと認証情報を設定する */
est_node_set_proxy(node, "proxy.qdbm.go.jp", 8080);
est_node_set_timeout(node, 5);
est_node_set_auth(node, "mikio", "oikim");

  /* ここで文書を登録したり、検索を行ったりする */

/* 破棄する */
est_node_delete(node);
</pre>

<p>ノード接続オブジェクトを生成するには、関数 `est_node_new' を用います。</p>

<dl>
<dt><kbd>ESTNODE *est_node_new(const char *<var>url</var>);</kbd></dt>
<dd>`url' はノードのURLを指定します。戻り値はノード接続オブジェクトです。</dd>
</dl>

<p>ノード接続オブジェクトを破棄するには、関数 `est_node_delete' を用います。</p>

<dl>
<dt><kbd>void est_node_delete(ESTNODE *<var>node</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。</dd>
</dl>

<p>ノード接続で直前に起きたステータスコードを取得するには、関数 `est_node_status' を用います。</p>

<dl>
<dt><kbd>int est_node_status(ESTNODE *<var>node</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。戻り値はノード接続で直前に起きたステータスコードです。-1は接続に失敗したことを意味します。</dd>
</dl>

<p>ノード接続オブジェクトにプロクシの情報を設定するには、関数 `est_node_set_proxy' を用います。</p>

<dl>
<dt><kbd>void est_node_set_proxy(ESTNODE *<var>node</var>, const char *<var>host</var>, int <var>port</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。`host' はプロクシサーバのホスト名を指定します。`port' はプロクシサーバのポート番号を指定します。</dd>
</dl>

<p>ノード接続オブジェクトにタイムアウトの情報を設定するには、関数 `est_node_set_timeout' を用います。</p>

<dl>
<dt><kbd>void est_node_set_timeout(ESTNODE *<var>node</var>, int <var>sec</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。`sec' は接続のタイムアウト時間を秒単位で指定します。</dd>
</dl>

<p>ノード接続オブジェクトに認証情報を設定するには、関数 `est_node_set_auth' を用います。</p>

<dl>
<dt><kbd>void est_node_set_auth(ESTNODE *<var>node</var>, const char *<var>name</var>, const char *<var>passwd</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。`name' は認証情報のユーザ名を指定します。`passwd' は認証情報のパスワードを指定します。</dd>
</dl>

<p>ノードに文書を追加するには、関数 `est_node_put_doc' を用いる。</p>

<dl>
<dt><kbd>int est_node_put_doc(ESTNODE *<var>node</var>, ESTDOC *<var>doc</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。`doc' は文書オブジェクトを指定します。文書オブジェクトはURI属性を持っていなければなりません。戻り値は成功なら真、エラーなら偽です。指定された文書オブジェクトのURI属性がノード内の既存の文書と一致する場合、既存の方は削除されます。</dd>
</dl>

<p>ノードから文書を削除するには、関数 `est_node_out_doc' を用います。</p>

<dl>
<dt><kbd>int est_node_out_doc(ESTNODE *<var>node</var>, int <var>id</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。`id' は登録文書のID番号を指定します。戻り値は成功なら真、エラーなら偽です。</dd>
</dl>

<p>ノードからURIで指定した文書を削除するには、関数 `est_node_out_doc_by_uri' を用います。</p>

<dl>
<dt><kbd>int est_node_out_doc_by_uri(ESTNODE *<var>node</var>, const char *<var>uri</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。`uri' は登録文書のURIを指定します。戻り値は成功なら真、エラーなら偽です。</dd>
</dl>

<p>ノードから文書を取得するには、関数 `est_node_get_doc' を用います。</p>

<dl>
<dt><kbd>ESTDOC *est_node_get_doc(ESTNODE *<var>node</var>, int <var>id</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。`id' は登録文書のID番号を指定します。戻り値は文書オブジェクトか、エラーなら `NULL' です。戻り値のオブジェクトは `est_doc_new' で生成されているので、不要になったら `est_doc_close' で破棄してください。</dd>
</dl>

<p>ノードからURIで指定した文書を取得するには、関数 `est_node_get_doc_by_uri' を用います。</p>

<dl>
<dt><kbd>ESTDOC *est_node_get_doc_by_uri(ESTNODE *<var>node</var>, const char *<var>uri</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。`uri' は登録文書のURIを指定します。戻り値は文書オブジェクトか、エラーなら `NULL' です。戻り値のオブジェクトは `est_doc_new' で生成されているので、不要になったら `est_doc_close' で破棄してください。</dd>
</dl>

<p>ノードから文書の属性値を取得するには、関数 `est_node_get_doc_attr' を用います。</p>

<dl>
<dt><kbd>char *est_node_get_doc_attr(ESTNODE *<var>node</var>, int <var>id</var>, const char *<var>name</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。`id' は登録文書のID番号を指定します。`name' は属性名を指定します。戻り値は該当の属性値か、無ければ `NULL' です。戻り値の領域は `malloc' で生成されているので、不要になったら `free' で破棄してください。</dd>
</dl>

<p>ノードからURIで指定した文書の属性値を取得するには、関数 `est_node_get_doc_attr_by_uri' を用います。</p>

<dl>
<dt><kbd>char *est_node_get_doc_attr_by_uri(ESTNODE *<var>node</var>, const char *<var>uri</var>, const char *<var>name</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。`uri' は登録文書のURIを指定します。`name' は属性名を指定します。戻り値は該当の属性値か、無ければ `NULL' です。戻り値の領域は `malloc' で生成されているので、不要になったら `free' で破棄してください。</dd>
</dl>

<p>URIに対応する文書のID番号を取得するには、関数 `est_node_uri_to_id' を用います。</p>

<dl>
<dt><kbd>int est_node_uri_to_id(ESTNODE *<var>node</var>, const char *<var>uri</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。`uri' は登録文書のURIを指定します。戻り値は文書のID番号であるか、エラーなら-1です。</dd>
</dl>

<p>ノードの名前を取得するには、関数 `est_node_name' を用います。</p>

<dl>
<dt><kbd>const char *est_node_name(ESTNODE *<var>node</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。戻り値はデータベースの名前か、エラーなら `NULL' です。戻り値の文字列の寿命はデータベースオブジェクトのそれと同期します。</dd>
</dl>

<p>ノードのラベルを取得するには、関数 `est_node_label' を用います。</p>

<dl>
<dt><kbd>const char *est_node_label(ESTNODE *<var>node</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。戻り値はデータベースのラベルか、エラーなら `NULL' です。戻り値の文字列の寿命はデータベースオブジェクトのそれと同期します。</dd>
</dl>

<p>ノードに登録された文書の数を取得するには、関数 `est_node_doc_num' を用います。</p>

<dl>
<dt><kbd>int est_node_doc_num(ESTNODE *<var>node</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。戻り値はデータベースに登録された文書の数か、エラーなら-1です。</dd>
</dl>

<p>ノードに登録された異なり語の数を取得するには、関数 `est_node_word_num' を用います。</p>

<dl>
<dt><kbd>int est_node_word_num(ESTNODE *<var>node</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。戻り値はデータベースに登録された異なり語の数か、エラーなら-1です。</dd>
</dl>

<p>ノードのデータベースのサイズを取得するには、関数 `est_node_size' を用います。</p>

<dl>
<dt><kbd>double est_node_size(ESTNODE *<var>node</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。戻り値はノードのデータベースのサイズか、エラーなら-1.0です。</dd>
</dl>

<p>検索条件に該当する文書の一覧を取得するには、関数 `est_node_search' を用います。</p>

<dl>
<dt><kbd>ESTNODERES *est_node_search(ESTNODE *<var>node</var>, ESTCOND *<var>cond</var>, int <var>depth</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。`cond' は検索条件オブジェクトを指定します。`depth' はメタ検索の深度を指定します。戻り値はノード結果オブジェクトか、エラーなら `NULL' です。戻り値のオブジェクトは不要になったら `est_noderes_delete' で破棄してください。</dd>
</dl>

<p>ノードのユーザアカウントを管理するには、関数 `est_node_set_user' を用います。</p>

<dl>
<dt><kbd>int est_node_set_user(ESTNODE *<var>node</var>, const char *<var>name</var>, int <var>mode</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。`name' はユーザ名を指定します。`mode' は操作モードを指定します。0ならアカウントを削除し、1ならアカウントを管理者にし、2なら通常ユーザにします。戻り値は成功なら真、エラーなら偽です。</dd>
</dl>

<p>ノードのリンクを管理するには、関数 `est_node_set_link' を用います。</p>

<dl>
<dt><kbd>int est_node_set_link(ESTNODE *<var>node</var>, const char *<var>url</var>, const char *<var>label</var>, int <var>credit</var>);</kbd></dt>
<dd>`node' はノード接続オブジェクトを指定します。`url' はリンク対象のノードのURLを指定します。`label' はリンクのラベルを指定します。`credit' はリンクの信頼度を指定します。負数の場合は該当のリンクを削除します。戻り値は成功なら真、エラーなら偽です。</dd>
</dl>

<h3>ノードからの検索結果を扱うAPI</h3>

<p>構造体型 `ESTNODERES' は、ノードからの検索結果を抽象化したものです。結果には、該当文書の情報のリストとヒント情報が含まれます。`ESTNODERES' の実体が直接参照されることはなく、必ずポインタを介して間接参照されます。このポインタおよびその参照先を総じてノード結果オブジェクトと呼びます。ノード結果オブジェクトは関数 `est_node_search' によって生成され、`est_noderes_delete' によって破棄されます。生成されたノード結果オブジェクトは必ず破棄してください。</p>

<p>構造体型 `ESTRESDOC' は、ノードからの検索結果の各文書の情報を抽象化したものです。文書情報には、複数の属性と一つのスニペットが含まれます。`ESTRESDOC' の実体が直接参照されることはなく、必ずポインタを介して間接参照されます。このポインタおよびその参照先を総じて結果文書オブジェクトと呼びます。結果文書オブジェクトは関数 `est_noderes_get_doc' によって参照できますが、実体はノード結果オブジェクトの内部で管理されるため、破棄する必要はありません。</p>

<p>ノード結果オブジェクトと結果文書オブジェクトの典型的なライフサイクルを以下に示します。</p>

<pre>ESTNODERES *nres;
CBMAP *hints;
ESTRESDOC *rdoc;
int i;

/* ノード結果オブジェクトを生成する */
nres = est_node_search(node, cond, 1);

/* ヒントを取り出す */
hints = est_noderes_hints(nres);

   /* ここでヒントを表示する */

/* 該当文書のリストを走査する */
for(i = 0; i &lt; est_noderes_doc_num(nres); i++){

  /* 結果文書オブジェクトを取り出す */
  rdoc = est_noderes_get_doc(nres, i);

  /* ここで文書情報を表示する */

}

/* ノード結果オブジェクトを破棄する */
est_noderes_delete(nres);
</pre>

<p>ノード結果オブジェクトを破棄するには、関数 `est_noderes_delete' を用います。</p>

<dl>
<dt><kbd>void est_noderes_delete(ESTNODERES *<var>nres</var>);</kbd></dt>
<dd>`nres' はノード結果オブジェクトを指定します。</dd>
</dl>

<p>ノード結果オブジェクトからヒントのマップオブジェクトを取得するには、関数 `est_noderes_hints' を用いる。</p>

<dl>
<dt><kbd>CBMAP *est_noderes_hints(ESTNODERES *<var>nres</var>);</kbd></dt>
<dd>`nres' はノード結果オブジェクトを指定します。戻り値はヒントのマップオブジェクトです。キーには "VERSION"、"NODE"、"HIT"、"HINT#n"、"DOCNUM"、"WORDNUM"、"TIME"、"LINK#n"、"VIEW" があります。戻り値のオブジェクトの寿命はノード結果オブジェクトのそれと同期します。</dd>
</dl>

<p>ノード結果オブジェクトに含まれる文書情報の数を取得するには、関数 `est_noderes_doc_num' を用います。</p>

<dl>
<dt><kbd>int est_noderes_doc_num(ESTNODERES *<var>nres</var>);</kbd></dt>
<dd>`nres' はノード結果オブジェクトを指定します。戻り値はノード結果オブジェクトに含まれる文書情報の数です。</dd>
</dl>

<p>ノード結果オブジェクトから個々の結果文書オブジェクトを取得するには、関数 `est_noderes_get_doc' を用います。</p>

<dl>
<dt><kbd>ESTRESDOC *est_noderes_get_doc(ESTNODERES *<var>nres</var>, int <var>index</var>);</kbd></dt>
<dd>`nres' はノード結果オブジェクトを指定します。`index' は取り出す要素のインデックスを指定します。戻り値は文書オブジェクトか、`index' が要素数と等しいか大きければ `NULL' です。戻り値のオブジェクトの寿命はノード結果オブジェクトのそれと同期します。</dd>
</dl>

<p>結果文書オブジェクトからURIを取得するには、関数 `est_resdoc_uri' を用います。</p>

<dl>
<dt><kbd>const char *est_resdoc_uri(ESTRESDOC *<var>rdoc</var>);</kbd></dt>
<dd>`rdoc' は結果文書オブジェクトを指定します。戻り値は結果文書オブジェクトのURIです。戻り値の文字列の寿命は結果文書オブジェクトのそれと同期します。</dd>
</dl>

<p>結果文書オブジェクトの属性名のリストを取得するには、関数 `est_resdoc_attr_names' を用います。</p>

<dl>
<dt><kbd>CBLIST *est_resdoc_attr_names(ESTRESDOC *<var>rdoc</var>);</kbd></dt>
<dd>`rdoc' は結果文書オブジェクトを指定します。戻り値は結果文書オブジェクトの属性名のリストです。戻り値のオブジェクトは `cblistopen' で生成されているので、不要になったら `cblistclose' で破棄してください。</dd>
</dl>

<p>結果文書オブジェクトの属性の値を取得するには、関数 `est_resdoc_attr' を用います。</p>

<dl>
<dt><kbd>const char *est_resdoc_attr(ESTRESDOC *<var>rdoc</var>, const char *<var>name</var>);</kbd></dt>
<dd>`rdoc' は結果文書オブジェクトを指定します。`name' は属性名を指定します。戻り値は属性値ですが、該当する属性がない場合は `NULL' が返されます。戻り値の文字列の寿命は文書オブジェクトのそれと同期します。</dd>
</dl>

<p>結果文書オブジェクトのスニペットを取得するには、関数 `est_resdoc_snippet' を用います。</p>

<dl>
<dt><kbd>const char *est_resdoc_snippet(ESTRESDOC *<var>rdoc</var>);</kbd></dt>
<dd>`rdoc' は結果文書オブジェクトを指定します。戻り値は結果文書オブジェクトのスニペットの文字列です。その形式はタブ区切り文字列（TSV）です。その各行は表示すべき文字列です。ほとんどの行は単一のフィールドしか持ちませんが、いくつかは二つのフィールドを持ちます。もし第2フィールドが存在したならば、第1フィールドはハイライトして表示すべき文字列で、第2フィールドはその正規化された文字列です。戻り値の文字列の寿命は結果文書オブジェクトのそれと同期します。</dd>
</dl>

<h3>並列性</h3>

<p>ノード接続オブジェクト、ノード結果オブジェクト、結果文書オブジェクトのいずれも、スレッド間で共有してはなりません。マルチスレッドを用いる場合は、各スレッドで別々のオブジェクトを使うようにしてください。その条件さえ守れば、ノードAPIの各関数はマルチスレッドセーフなものとして扱えます。</p>

<hr />

<h2 id="estcall">クライアント用コマンド</h2>

<p>ここでは、ノード管理用コマンドestcallの詳細な仕様を説明します。検索もできるので、estcallをスクリプト言語から呼び出せばそれなりのアプリケーションが簡単に作れます。</p>

<h3>書式</h3>

<p>estcallは多くのサブコマンドの集合体です。サブコマンドの名前は第1引数で指定されます。その他の引数はサブコマンドの種類に応じて解釈されます。<var>nurl</var>という引数は操作対象のノードのURLです。-proxyオプションはプロクシのホスト名とポート番号を指定します。-toutはタイムアウトの時間を秒単位で指定します。-authは認証のユーザ名とパスワードを指定します。</p>

<dl>
<dt><kbd>estcall put [-proxy <var>host</var>:<var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] <var>nurl</var> [<var>file</var>]</kbd></dt>
<dd>文書ドラフト形式のファイルを登録します。</dd>
<dd><var>file</var>は対象のファイルを指定しますが、省略した場合は標準入力が読み込まれます。</dd>
</dl>

<dl>
<dt><kbd>estcall out [-proxy <var>host</var>:<var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] <var>nurl</var> <var>expr</var></kbd></dt>
<dd>特定の文書の情報をインデックスから削除します。</dd>
<dd><var>expr</var>は対象のID番号かURIを指定します。</dd>
</dl>

<dl>
<dt><kbd>estcall get [-proxy <var>host</var>:<var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] <var>nurl</var> <var>expr</var> [<var>attr</var>]</kbd></dt>
<dd>特定の文書の情報を文書ドラフト形式で出力します。</dd>
<dd><var>expr</var>は対象のID番号かURIを指定します。</dd>
<dd><var>attr</var>を付けると、その属性の値のみを出力します。</dd>
</dl>

<dl>
<dt><kbd>estcall uriid [-proxy <var>host</var>:<var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] <var>nurl</var> <var>uri</var></kbd></dt>
<dd>指定したURIの文書のID番号を出力します。</dd>
<dd><var>uri</var>は対象のURIを指定します。</dd>
</dl>

<dl>
<dt><kbd>estcall inform [-proxy <var>host</var>:<var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] <var>nurl</var></kbd></dt>
<dd>ノードの名前とラベルと登録文書数と登録語数を出力します。</dd>
</dl>

<dl>
<dt><kbd>estcall search [-proxy <var>host</var>:<var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] [-vx] [-attr <var>expr</var>] [-ord <var>expr</var>] [-max <var>num</var>] [-dpt <var>num</var>] <var>nurl</var> [<var>phrase</var>]</kbd></dt>
<dd>ノードに登録された文書を検索します。</dd>
<dd><var>phrase</var>は全文検索の検索式を指定します。</dd>
<dd>-vxを付けると、XML形式にして結果を出力します。</dd>
<dd>-attrは絞り込みの属性条件を指定します。複数指定可能です。</dd>
<dd>-ordはソート条件を指定します。デフォルトはスコアの降順です。</dd>
<dd>-maxは最大表示件数を指定します。負数にすると無制限になります。デフォルトは10件です。</dd>
<dd>-dptはメタ検索の深度を指定します。デフォルトは0です。</dd>
</dl>

<dl>
<dt><kbd>estcall setuser [-proxy <var>host</var>:<var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] <var>nurl</var> <var>name</var> <var>mode</var></kbd></dt>
<dd>ユーザ権限を設定します。</dd>
<dd><var>name</var>はユーザ名を指定します。</dd>
<dd><var>mode</var>が1ならそのユーザを管理者にし、2ならそのユーザを通常ユーザにし、0ならユーザ権限を削除します。</dd>
</dl>

<dl>
<dt><kbd>estcall setlink [-proxy <var>host</var>:<var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] <var>nurl</var> <var>url</var> <var>label</var> <var>credit</var></kbd></dt>
<dd>リンクを設定します。</dd>
<dd><var>url</var>はリンク先のノードのURLを指定します。</dd>
<dd><var>label</var>はラベルを指定します。</dd>
<dd><var>credit</var>は信頼度を指定します。値が負数の場合はそのリンクを削除します。</dd>
</dl>

<dl>
<dt><kbd>estcall raw [-proxy <var>host</var>:<var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] [-np] [-eh <var>expr</var>] <var>url</var> [<var>file</var>]</kbd></dt>
<dd>HTTPリクエストを直接制御してレスポンスを出力します。</dd>
<dd><var>url</var>は操作対象のURLを指定します。</dd>
<dd><var>file</var>が指定された場合はその内容をPOSTメソッドで送信します。指定されなかった場合はGETメソッドを用います。"-" を指定すると標準入力を読み込みます。</dd>
<dd>-npを付けると、レスポンスヘッダも含めて出力します。</dd>
<dd>-ehは追加するHTTPヘッダを指定します。デフォルトではHostとConnectionとUser-AgentContent-Lengthが付加されます。</dd>
</dl>

<p>全てのサブコマンドは、処理が正常に終了した場合には0を、そうでない場合は1を終了ステータスにします。</p>

<h3>応用例：ノードマスタの操作</h3>

<p>ノードマスタ自体の操作はAPIにはありませんので、rawサブコマンドを用いてください。例えば、ノードマスタをシャットダウンするには、以下のようなコマンドを実行します。</p>

<pre>estcall raw -auth admin admin \
  'http://localhost:1978/master?action=shutdown'
</pre>

<p>ユーザを追加するには、以下のようなコマンドを実行します。</p>

<pre>estcall raw -auth admin admin \
  'http://localhost:1978/master?action=useradd&amp;name=mikio&amp;passwd=iloveyou'
</pre>

<p>POSTメソッドを使うには、以下のようにします。</p>

<pre>echo -n 'action=useradd&amp;name=mikio&amp;passwd=iloveyou' |
  estcall raw -auth admin admin \
    -eh 'Content-Type: application/x-www-form-urlencoded' \
    'http://localhost:1978/master' -
</pre>

<hr />

<h2 id="tips">助言</h2>

<p>ここでは、Hyper EstraierのP2P機構を活用するためのコツをいくつか紹介します。</p>

<h3>パラメータの詳細</h3>

<p>メタ検索の深度は0が起点です。深度が0なら自前のインデックスのみを対象とし、1ならリンク先のノードも対象とし、2ならその先も対象とし、3ならさらにその先も対象とします。それ以上の値も指定できます。クライアントが指定した深度がノードマスタの設定ファイルで指定した深度より大きい場合は、ノードマスタで指定した方に抑えられます。</p>

<p>リンクの信頼度は検索結果の各文書の順位を決定する際に利用されます。各ノードから収集した結果をマージする際には、各文書について、各ノードにおける順位を表示件数から引いた値に信頼度を掛けた値をスコアとして算出します。例えば、信頼度15000のノードに対して10件の文書を問い合わせた結果の4位の文書のスコアは「(10 - 4) * 15000」で90000になります。このスコアが高い順ものから提示されます。自前のインデックスの信頼度は10000で固定です。したがって、他のノードへのリンクの信頼度は、その結果を自前のインデックスの結果より上位にしたい場合は10000より大きくし、下位にしたい場合は10000より小さくするとよいでしょう。</p>

<h3>認証機構の詳細</h3>

<p>認証機構のモードは3種類あり、設定ファイルで指定されます。デフォルトは2です。以下の表では、各種の操作に対して匿名を許可する場合は「○」、認証を行う場合は「×」を示します。ノードサーバの管理操作とは、put_doc、out_doc、_set_user、_set_linkのことです。ノードサーバに対するそれ以外の操作は通常操作です。</p>

<table summary="authorization mode">
<tr>
<th abbr="mode"></th>
<th abbr="1">1（none）</th>
<th abbr="2">2（admin）</th>
<th abbr="3">3（all）</th>
</tr>
<tr>
<td>ノードマスタの操作</td>
<td>×</td>
<td>×</td>
<td>×</td>
</tr>
<tr>
<td>ノードサーバの管理操作</td>
<td>○</td>
<td>×</td>
<td>×</td>
</tr>
<tr>
<td>ノードサーバの通常操作</td>
<td>○</td>
<td>○</td>
<td>×</td>
</tr>
</table>

<p>認証機構があっても平文をネットワーク上に流すのではセキュリティとしては不十分です。特にHTTPの基本認証のセキュリティは低く、邪悪な人達には全く無力と言っても過言ではありません。したがって、重要なデータを扱う際には、通信を暗号化することをお薦めします。ただし、Hyper Estraier自体は暗号通信の機能を提供しませんので、Apache等をリバースプロクシとして利用してください。同時接続数が多い場合は市販のSSLアクセラレータを利用するとよいでしょう。</p>

<p>このような認証機構が気に入らない場合は、フロントエンドのクライアントを実装して、そこでアカウント管理と認証を行ってください。フロントエンドがバックエンドであるノードマスタやノードサーバにアクセスする際には常にスーパーユーザを用いるとよいでしょう。Apacheをフロントエンドにすれば、mod_auth_ldapを使ってLDAPによる認証を行ったり、mod_auth_radiusを使ってRADIUSによる認証を行ったりできます。Locationディレクティブなどを駆使すれば各メソッドのアクセス権限を詳細に設定することもできます。</p>

<h3>通常のWeb機能</h3>

<p>ノードマスタは通常のWebサーバとしての機能も備えています。この機能は検索対象文書の実体を公開する場合に便利でしょう。例えば、「/home/www/public_html」以下を公開したい場合は、設定ファイルに以下のように書きます。</p>

<pre>docroot: /home/www/public_html
indexfile: index.html
</pre>

<h3>負荷テスト用コマンド</h3>

<p>各種のWebアプリケーションに対する負荷テストのためのユーティリティとして、estloadコマンドが提供されます。以下の書式を持ちます。</p>

<dl>
<dt><kbd>estload [-t <var>num</var>] [-l <var>num</var>] [-i <var>num</var>] [-p] [-q] [<var>file</var>|<var>url</var>]</kbd></dt>
<dd><var>file</var>を指定した場合、そのファイルの各行に含まれるURLのリクエストを発行します。<var>url</var>を指定した場合、そのURLのリクエストを発行します。何も指定しなかった場合、標準入力の各行に含まれるURLのリクエストを発行します。</dd>
<dd>-tは並行して動かすスレッドの数を指定します。デフォルトは1です。</dd>
<dd>-lはリストを繰り返す回数を指定します。デフォルトは1です。</dd>
<dd>-iはリクエストを発行してからスリープする時間をミリ秒単位で回数を指定します。デフォルトは0です。</dd>
<dd>-pを指定すると、レスポンスを表示します。</dd>
<dd>-qを指定すると、進捗状態を表示しません。</dd>
</dl>

<h3>初期導入の効率化</h3>

<p>大規模なサイトの立ち上げを素早く行いたい場合、estcmdを利用するかアプリケーションを作成するかして、コアAPIのレベルでインデックスを作った方がよいでしょう。そうして作ったインデックスは、ノードディレクトリに置くことでノードサーバとして利用することができます。例えば、/home/mikio以下の文書を登録した、名前が「mikio」でラベルが「Mikio Hirabayashi」のノードサーバを設置するには、以下のようにします。</p>

<pre>estmaster init casket
estcmd gather -sd -il ja casket/_node/mikio /home/mikio
estcmd meta casket/_node/mikio label "Mikio Hirabayashi"
</pre>

<p>ユーザやリンクの設定は、ノードマスタを起動させた上で、ノードAPIやestcallコマンドを使って行ってください。なお、estcallにはestcmd gatherのようなギャザラ用のサブコマンドは用意されていません。findやestcmd draftなどを組み合わせれば同等のことは可能です。</p>

<hr />

</body>

</html>

<!-- END OF FILE -->