gss3プロトコル の変更点

Top > gss3プロトコル


gss3プロトコルは、GETAssocの検索系の操作をWebアプリケーションから簡単に利用するために定義された規約です。WebアプリケーションとGETAssocの通信路にはHTTPを利用し、データのフォーマット形式にはXMLを利用します。このためHTTPで通信できる機能を持った任意のプログラム言語でクライアントを作成することができますし、Javascriptを用いて直接ブラウザ上からGETAssocへアクセスすることもできます。

#contents

* 基本
- 送受信(Request, Response)ともにXML形式です。
- Rootタグは<gss></gss>です。
- 名前空間は  http://gss3.cs.nii.ac.jp/ です。

** Gss3 Protocol Analyzer
gss3プロトコルを用いた実装例として、Javascriptで作成されブラウザ上で動作するサンプルアプリケーションGSS3 Protocol Analyzerを用意しました。gss3プロトコルを用いた実際のRequest、Response形式を簡単に確認することができます。配布パッケージに同梱してありますので、GETAssocのインストール後、お手元のコンピュータで動作させることができます。
gss3プロトコルを用いた実装例として、Javascriptで作成されブラウザ上で動作するサンプルアプリケーションGSS3 Protocol Analyzerがあります。gss3プロトコルを用いた実際のRequest、Response形式を簡単に確認することができます。使用するためには、Webページから次のファイルを直接ダウンロードし、同じディレクトリに置いてください。
- http://getassoc.cs.nii.ac.jp/gpa/gss3.html
- http://getassoc.cs.nii.ac.jp/gpa/gss3.js
- http://getassoc.cs.nii.ac.jp/gpa/load.gif
次にgss3.jsの866行目を環境に合わせて書き換えます。同一マシンで動作させるときは、次のようにします。
 gss3.url = 'http://localhost/getassoc/gss3';


* assoc (連想検索)
GETAssocの検索系の動作を指定します。連想検索のデータの流れについては[[詳細/GETAssocにおける連想計算]]もご覧ください。
** Request

 <?xml version="1.0" encoding="UTF-8"?>
 <gss version="3.0" xmlns="http://gss3.cs.nii.ac.jp/">
   <assoc target="ja_document" niwords="70" cutoff-df="10000"
          narticles="10" nkeywords="10" yykn="10" nacls="1" nkcls="1" a-offset="0" a-props="title,link" 
          cross-ref="aw,wa" stage1-sim="WT_SMARTAW" stage2-sim="WT_SMARTWA">
     <freetext cutoff-df="30000" stemmer="MECAB">getassocを使って連想検索を効率的にしたい。</freetext>
     <article name="12345"/>
     <article vec="[[&quot;晴れ&quot;,1],[&quot;曇り&quot;,1],[&quot;雨&quot;,1]]"/>
     <filter expression="(&quot;雨&quot; &amp; !&quot;雪&quot;)"/>
     <filter>
       <search>
         <join>
           <p>効率的にしたい</p>
           <n>したくない</n>
         </join>
       </search>
     </filter>
   </assoc>
 </gss>

連想検索のRequestは主に次の3つのパートから成り立っています
:<assoc>タグの属性 | 連想検索の計算法、検索結果の出力の指定
:<freetext>、<article>タグ | クエリーの表現
:<filter>タグ | 検索結果の絞り込み条件の指定

*** <assoc>タグの属性
stage1に関連する属性
|属性名|省略時|説明|
|target | 不可 | 検索したいコーパスのハンドル名を指定します。|
|niwords | "70" | stage1で出力する重要語リストの単語数を指定します。|
|cutoff-df | → | この値以上の文書数に出現する単語は重要語の計算には使用されず捨てられます。あまりにも多くの文書に出現する単語は、検索結果にはあまり影響しないということと、そのような単語を使用した場合検索時間がかかることがあるためです。この属性の省略時には、min(1, pow(0.125, log10(N) - 4)) * N (Nはコーパスの文書数、N=10,000のとき10,000、N=1,000,000のとき15,625)という値が指定されます。またcutoff-df="0"とした時には、クエリーに出現したすべての単語について重要度の計算をします。|
|stage1-sim | "WT_SMARTAW" | 重要単語リストを計算するときに使用する類似度を指定します。|

stage2に関連する属性
|属性名 | 省略時 | 説明 |
|narticles | 不可 | 出力する文書の数を指定します。|
|nkeywords | 不可 | 出力する関連語の数を指定します。|
|a-offset | "0" | 出力する文書のスタート位置を指定します。|
|nacls | "1" | 出力文書をクラスタリングする時の分割数を指定します。|
|nkcls | "1" | 出力関連語をクラスタリングする時の分割数を指定します。|
|yykn | "10" | 関連語の候補を得るために必要な文書数を指定します。|
|a-props | 不可 | 出力するプロパティを指定します。|
| cross-ref | "*" | 文書単語間の相関値を出力します。aw(文書→単語)、wa(単語→文書)、aa(文書→文書)、ww(単語→単語) |
|stage2-sim | "WT_SMARTWA" | 重要単語リストと文書の類似度を計算するときに使用する類似度を指定します。|

*** <freetext>、<article>タグによるクエリーの表現
&lt;freetext>タグ
 <freetext stemmer="MECAB" cutoff-df="0">getassocを使って連想検索を効率的にしたい。</freetext>
|属性名 | 説明 |
|stemmer | クエリー文字列をstemmingするstemmerを指定します。"auto"または省略時はdefaultstemmerが使用されます。|
|cutoff-df| &lt;assoc>のcutoff-dfと同じです。|

&lt;article>タグ
 <article name="12345"/>
 <article vec="[[&quot;晴れ&quot;,1],[&quot;曇り&quot;,1],[&quot;雨&quot;,1]]"/>
 <article name="12345" source="wikipedia_en">

|属性名 | 説明 |
|name | 文書idを指定できます。 |
|vec | 単語のベクトルです。"単語:頻度"をJSON形式の文字列として表現します。|
|source | 文書idについての単語ベクトルを取得するコーパスを指定します。省略時は<assoc>タグの属性で指定されたtargetが使用されます。|
|cutoff-df| &lt;assoc>のcutoff-dfと同じです。|

*** <filter>タグによる検索結果の絞り込み
&lt;filter expression="〜">
 <filter expression="(&quot;雨&quot; &amp; !&quot;雪&quot;) | &quot;雷&quot;"/>
expression属性内ではstemmerによりstemmingされた単語を使います。ブール式を組み合わせることで絞り込み条件が指定できます。

&lt;filter><search><join>〜</join><join>〜</join></search></filter>

     <filter>
       <search>
         <join>
           <p>効率的にしたい</p>
           <n>したくない</n>
         </join>
         <join>
           <p>お世話になっています</p>
         </join>
       </search>
     </filter>

この形式では特定のフレーズにより検索結果の絞り込み条件が指定できます。ただし全文一致インデックスを作成している場合のみ有効です。書式の詳細は全文検索の項をご覧ください。

** Response

** stage1,2で分割

* assoc (全文検索)
GETAssocで全文一致検索を実行します。stpでのインデックス作成時に全文検索オプション(@fss)を指定したときにのみ使用できます。
** Request
 <?xml version="1.0" encoding="UTF-8"?>
 <gss version="3.0">
   <assoc target="wikipedia_ja" narticles="10" nkeywords="10" yykn="10" nacls="1" 
      nkcls="1" a-offset="0" a-props="title,link">
     <search segments="0-31">
       <join segments="0" options="match-tail">
         <p>サイン</p>
         <n>コサイン</n>
       </join>
       <join>
         <p segments="0,2-5">署名</p>
       </join>
     </search>
   </assoc>
 </gss>

:<assoc>タグの属性 | 連想検索の<assoc>タグのstage2と同じです。ただしstage2-simは使用しません。
:<search>タグ | 全文一致検索の一致条件を書きます。

&lt;search>タグ内では<join>タグを1つ以上含み、それぞれはOR関係となります。<join>タグ内では、<p>タグに必ず含むフレーズを、<n>タグに含まないフレーズを指定します。<join>内では複数の<p>、<n>タグが記述でき、それぞれはAND関係となりますが、<n>タグのみの指定はできません。

&lt;search>、<join>、<p>、<n>タグには、それぞれ独自に次の属性を付加することができます。
:segments | 全文一致部分を指定します。segmentsは、itbファイル内の全文検索用文字列の行に対応します。例えば「!123\n!456」のとき、segments=0は「123」に、segments=1は「456」に対応します。現在、segmentsは0から31までしか対応していません。
:options | 全文一致条件を指定します。詳しくは次の表をご覧ください。

*** options について
optionsは、全文検索インデックスがあれば適用できるものと、インデックス作成時に予め指定しておかないと適用できないものがあります。
-全文検索インデックスがあれば適用できるオプション

|match-head|segmentsの先頭にマッチします。|
|match-tail|segmentsの末尾にマッチします。|

-インデックス作成時に指定しておかないと適用できないオプション

|collapse-ay|(イ,キ,ギ,シ,ジ,チ,ヂ,ニ,ヒ,ビ,ピ,ミ,リ,ヰ)ア/ヤを区別しない|
|collapse-bv|バ/ヴァ ビ/ヴィ ベ/ヴェ ボ/ヴォを区別しない|
|collapse-dash|マイナス/長音/ダッシュを区別しない|
|collapse-eshk|漢字の異体字を同一視する。[[詳細/全文一致検索のカスタマイズ]]を参照してください|
|collapse-hf|ヒュ/フュ、ビュ/ヴュを区別しない|
|collapse-hirakata|ひらがな/カタカナを区別しない|
|collapse-ka|箇个ヶヵを区別しない|
|collapse-kx|キ/ク(サ,シ,ス,セ,ソ)を区別しない|
|collapse-qy|拗音、促音を区別しない|
|collapse-ssh|セ/シェ、ゼ/ジェを区別しない|
|collapse-tts|ツィ/ティ/チ、ディ/ジを区別しない|
|collapse-zdz|ヂ/ジ、ヅ/ズを区別しない|
|ignore-case|大文字/小文字を区別しない|
|ignore-punct|区切り記号を無視する|
|ignore-space|空白を無視する|

インデックス作成時にオプションを指定するためには、itbファイルの先頭で次のように指定します。
 @title=データベース1
 $ignore-case,collapse-hirakata,collapse-zdz

ただし、これらのオプションを指定して作成された全文一致検索用インデックスは、検索速度が大きく低下する場合があります。

** Response

* getprop
各ドキュメントのpropertyを取得します。

** Request

 <?xml version="1.0" encoding="UTF-8"?>
 <gss version="3.0" xmlns="http://gss3.cs.nii.ac.jp/" >
   <getprop target="handle" a-props="title,link,vec" >
     <article name="A1" />
     <article name="A2" />
   </getprop>
 </gss>

- ''target''には、情報を取得したいコーパスのnameを指定ください。
- ''a-props''には、取得するドキュメントの情報を指定します。
-- ''title''や''link''は、stpによるコーパスのインデックス時に指定したプロパティに対応するものです。
-- ''vec''を指定すると、ドキュメントを構成する用語と頻度のリストを取得することができます。
- 一度に複数のドキュメントを指定することができます。

** Response

 <?xml version="1.0" encoding="UTF-8"?>
 <gss version="3.0" xmlns="http://gss3.cs.nii.ac.jp/" user-time="0.019">
   <result status="OK" >
     <article name="A1" title="A1 title" link="http://..." vec='[["T1",3],["T2",5], ... ,["T100",1]]'/>
     <article name="A2" title="A2 title" link="http://..." vec='[["T2",1],["T3",8], ... ,["T200",1]]'/>
   </result>
 </gss>

- 各ドキュメントごとにタグがあり、その属性値に情報が付与されます。
- ''vec''には、用語とその頻度のリストがJSON形式の文字列として格納されています。

* inquire
GETAssocで現在検索できるデータの情報('''catalogue'''といいます)を取得します。

** Request

 <?xml version="1.0" encoding="UTF-8"?>
 <gss version="3.0" xmlns="http://gss3.cs.nii.ac.jp/">
   <inquire type="catalogue" />
 </gss>

- このRequestには、ユーザが指定できる属性はありません。

** Response

 <?xml version="1.0" encoding="UTF-8"?>
 <gss version="3.0" xmlns="http://gss3.cs.nii.ac.jp/" user-time="0.005">
   <result status="OK" >
     <corpus name="hdhcx" title="Encyclopedia Galactica" properties="title,link" created="1141782415" ... />
     <corpus name="senya" title="..." properties=... created="..." />
     ...
   </result>
 </gss>

- 各コーパスの情報が返ってきます。

* エラーについて
Requestに不備がある場合、もしくはGETAssoc内部で何らかのエラーが発生した場合、Responseからはエラー情報が返ってきます。以下に代表的なエラー情報を示します。
: loading XML document error | RequestのXMLが間違っています。
: unknown attribute | 定義されていない属性が使われています。
: unknown weight type | 定義されていない類似度名が使われています。

TOP