簡単導入! OSS全文検索サーバFess入門

【第14回】管理用APIの使い方

管理用APIとは

管理用APIはFessが提供する管理操作用のRESTful APIのことで、Fessの設定をHTTPリクエスト経由で行うことができます。

クローラ設定や辞書設定など、Fessの管理画面で設定できるものはほとんどが管理用APIからも設定することができます。外部のアプリケーションからFessの設定を変更したい場合などに便利です。

今回はクロールとスケジューラの設定を作成しながら管理用APIについて紹介します。

Fessの管理機能自体の説明は管理者ガイドを参照してください。HTTPリクエストで送るパラメータの説明や、今回紹介していない設定項目についてはI/Fガイドの/api/admin/などを参照してください。

以降の説明では、Fessの環境が構築済みであるものとして説明します。

管理用APIを使うための準備

管理用APIを使うためには、まずFessの管理画面でアクセストークンを作成します。

Fessの管理画面の「システム」>「アクセストークン」から右上の「新規作成」をクリックして、 以下のように設定してアクセストークンを発行します。

項目名	設定値
名前	Test
パーミッション	{role}admin-api

名前は任意の値で問題ありませんが、管理用APIにアクセスするためには admin-api ロールが必要になります。

生成されたアクセストークンを確認するためには、アクセストークンの一覧ページから作成した設定をクリックして「トークン」の欄に表示されている値を保存しておきます。

ここで取得したアクセストークンを使用すれば、管理者としてログインしなくても設定を変更できてしまうため、アクセストークンの管理には注意してください。

今回は取得したアクセストークンの値が access_token であると仮定します。

クローラ設定

クローラ設定ではクロールを実行するための設定を登録できます。

ここでは例としてFessの公式サイトをクロールする設定を登録します。

まずはウェブクロール設定をJSON形式で以下のように記述します。I/Fガイドのannotations欄でRequiredとあるものは必ずHTTPリクエストのボディ部分に含める必要があります。

json
{
   "name":"Fess : https://fess.codelibs.org/",
   "description":"Enterprise Search Server: Fess",
   "urls":"https://fess.codelibs.org/",
   "included_urls":"https://fess.codelibs.org/.*",
   "user_agent":"Mozilla/5.0",
   "num_of_thread":1,
   "interval_time":10000,
   "boost":1.0,
   "available":true,
   "sort_order":0
}

次にPUTメソッドで上記のJSONを管理用APIでFessに送信します。

アクセストークンはAutorizationリクエストヘッダーで指定します。curlコマンド内の access_token は管理画面で取得したアクセストークンに置き換えて実行してください。

$ curl -H "Authorization: access_token" -XPUT "http://localhost:8080/api/admin/webconfig/setting" -d '{"name":"Fess : https://fess.codelibs.org/","description":"Enterprise Search Server: Fess","urls":"https://fess.codelibs.org/","included_urls":"https://fess.codelibs.org/.*","user_agent":"Mozilla/5.0","num_of_thread":1,"interval_time":10000,"boost":1,"available":true,"sort_order":0}'

以下のようなJSONレスポンスが返却されます。

{"response":{"id":"webconfig_id","created":true,"version":"13.1","status":0}}

created フィールドがtrue、status フィールドが0(0は正常終了)となっていれば、登録に成功しています。id フィールドの文字列がこのクローラ設定のIDとなります。ここでは webconfig_id に置き換えています。

ウェブクロール設定のAPI以外にファイルクロール設定のAPIやデータストアクロール設定のAPIなども用意されています。

各種設定情報の登録は上記と同様な方法で操作できます。

スケジューラ

スケジューラではクローラなどの各種ジョブの実行スケジュールを管理できます。

以下のコマンドでスケジューラに登録されているジョブの一覧を取得します。

$ curl -H "Authorization: access_token" -XGET "http://localhost:8080/api/admin/scheduler/settings"

以下のようなJSONレスポンスが返却されます。

json
{
   "response":{
      "settings":[
         {
            "running":false,
            "id":"default_crawler",
            "version_no":-1,
            "name":"Default Crawler",
            "target":"all",
            "cron_expression":"0 0 * * *",
            "script_type":"groovy",
            "script_data":"return container.getComponent(\"crawlJob\").logLevel(\"info\").execute(executor);",
            "crawler":"true",
            "job_logging":"true",
            "available":"true",
            "sort_order":0
         },
         ...(省略)...
      ],
      "total":10,
      "version":"13.1",
      "status":0
   }
}

settings には現在、登録されているジョブの情報が含まれます。標準で登録されているジョブを確認することができます。

次にスケジューラAPIを利用して、さきほど登録したウェブクロール設定のジョブを登録します。

登録するジョブの設定はJSON形式で以下のように記述します。ここではクロールジョブを実行する時刻を毎日12時とし、ジョブに登録するウェブクロール設定のIDは webconfig_id であるものとします。

json
{  
   "name":"Fess : https://fess.codelibs.org/",
   "target":"all",
   "cron_expression":"0 12 * * *",
   "script_type":"groovy",
   "script_data":"return container.getComponent(\"crawlJob\").logLevel(\"info\").sessionId(\"webconfig_id\").webConfigIds([\"webconfig_id\"] as String[]).fileConfigIds([] as String[]).dataConfigIds([] as String[]).jobExecutor(executor).execute();",
   "sort_order":0,
   "crawler":true,
   "job_logging":true,
   "available":true
}

作成したJSONテキストをPUTメソッドで送信して、スケジューラにジョブを作成します。

$ curl -H "Authorization: access_token" -XPUT "http://localhost:8080/api/admin/scheduler/setting" -d '{"name":"Fess : https://fess.codelibs.org/","target":"all","cron_expression":"0 12 * * *","script_type":"groovy","script_data":"return container.getComponent(\"crawlJob\").logLevel(\"info\").sessionId(\"webconfig_id\").webConfigIds([\"webconfig_id\"] as String[]).fileConfigIds([] as String[]).dataConfigIds([] as String[]).jobExecutor(executor).execute();","sort_order":0,"crawler":true,"job_logging":true,"available":true}'

以下のようなJSONレスポンスが返ってくれば成功です。

json
{"response":{"id":"(作成したジョブのID)","created":true,"version":"13.1","status":0}}

ここでは作成(PUT)する例を示しましたが、取得(GET)や編集(POST)、削除(DELETE)も同様に操作できます。

また、特定のジョブをすぐに実行したい場合には、

$ curl -H "Authorization: access_token" -XPOST "http://localhost:8080/api/admin/scheduler/(ジョブのID)/start"

とします。

*　　*　　*

今回はFessが提供する管理用APIについての具体的な使用例を紹介しました。今回紹介していない管理用APIを利用する際にも参考になると思います。

Fessを組み込みたい場合などに、管理APIを利用することで、Fessの機能を組み込んだシステムを構築することも可能です。