droonga-request

概要
使い方
パラメータ
インストール方法

概要

droonga-requestは、任意のメッセージをDroongaクラスタに送り、レスポンスとして得られた結果を出力します。

このコマンドはDroongaネイティブプロトコルとHTTPの両方に対応しています。 Droonga Engineノードに対しては、Droongaネイティブのメッセージを直接送れます。

大量のメッセージを一気に送信したい場合は、droonga-sendコマンドの説明も併せて参照して下さい。

使い方

基本的な使い方

例えば、192.168.100.50というDroonga Engineノードがあり、同一ネットワークセグメント内のコンピュータ192.168.100.10にログインしている場合、system.statusコマンドのメッセージを送信するコマンド列は以下のようになります：

(on 192.168.100.10)
$ echo '{"type":"system.status"}' |
    droonga-request --host 192.168.100.50 --receiver-host 192.168.100.10
Elapsed time: 0.00900742
{
  "inReplyTo": "1430963525.9829412",
  "statusCode": 200,
  "type": "system.status.result",
  "body": {
    "nodes": {
      "node0:10031/droonga": {
        "status": "active"
      },
      "node1:10031/droonga": {
        "status": "active"
      }
    },
    "reporter": "node0:55329/droonga @ node0:10031/droonga"
  }
}

1行目はレスポンスを得るまでにかかった時間です。後の行はレスポンスメッセージとして得られた内容です。

メッセージの形式のリファレンスの説明にある通り、id、date、datasetの各フィールドはリクエストメッセージの必須フィールドです。与えられたメッセージがそれらを持っていなかった場合、このコマンドは初期状態で、適切な値を推測または生成して補います。実際に送信された補完後のメッセージを見るには、--report-requestオプションを指定して下さい：

(on 192.168.100.10)
$ echo '{"type":"system.status"}' |
    droonga-request --report-request --host 192.168.100.50 --receiver-host 192.168.100.10
Request: {
  "type": "system.status",
  "id": "1430963525.9829412",
  "date": "2015-05-07T02:39:50.334377Z",
  "dataset": "Default"
}
Elapsed time: 0.00900742
...

利用可能な全てのコマンドの一覧については、コマンドリファレンスを併せて参照して下さい。

他のコマンドとの連携

このメッセージは標準入力を通じて送信するメッセージを受け取れます。上記の例のように、echo、cat、およびその他のコマンドをこのコマンドのための入力ソースとして利用できます。例えば、drndumpの出力もそのまま入力ソースとして利用できます：

(on 192.168.100.10)
$ drndump --host 192.168.100.50 --receiver-host 192.168.100.10 | \
    droonga-request --host 192.168.100.60 --receiver-host 192.168.100.10 \
    > /dev/null

ファイルからの入力

テキストファイルを入力ソースとして使うこともできます。このコマンドは以下のように、コマンドライン引数として指定されたファイルの内容を読み込んで利用します：

(on 192.168.100.10)
$ cat /tmp/message.json
{"type":"system.status"}
$ droonga-request --host 192.168.100.60 --receiver-host 192.168.100.10 /tmp/message.json
Elapsed time: 0.00900742
{
  "inReplyTo": "1430963525.9829412",
  "statusCode": 200,
  "type": "system.status.result",
  "body": {
    "nodes": {
      "node0:10031/droonga": {
        "status": "active"
      },
      "node1:10031/droonga": {
        "status": "active"
      }
    },
    "reporter": "node0:55329/droonga @ node0:10031/droonga"
  }
}

複数のメッセージを一度に送る

このコマンドは複数のメッセージを順番に送る事もできます。複数メッセージの一括送信は、単に、複数のメッセージを入力として与えるだけで行えます：

(on 192.168.100.10)
$ echo '{"type":"system.status"} {"type":"system.statistics.object.count","body":{"output":["total"]}}' |
    droonga-request --host 192.168.100.50 --receiver-host 192.168.100.10
Elapsed time: 0.007365724
{
  "inReplyTo": "1430964599.844579",
  "statusCode": 200,
  "type": "system.status.result",
  "body": {
    "nodes": {
      "node0:10031/droonga": {
        "status": "active"
      },
      "node1:10031/droonga": {
        "status": "active"
      }
    },
    "reporter": "node0:55329/droonga @ node0:10031/droonga"
  }
}
Elapsed time: 0.014172429
{
  "inReplyTo": "1430964599.8521488",
  "statusCode": 200,
  "type": "system.statistics.object.count.result",
  "body": {
    "total": 549
  }
}

全てのレスポンスに伴う処理結果は、順番に標準出力に出力されます。

もちろん、以下のようにしてソースファイル内に複数のメッセージを含めることもできます：

(on 192.168.100.10)
$ cat /tmp/messages.jsons
{"type":"system.status"}
{"type":"system.statistics.object.count",
 "body":{"output":["total"]}}
$ droonga-request --host 192.168.100.60 --receiver-host 192.168.100.10 /tmp/messages.jsons
Elapsed time: 0.007365724
{
  "inReplyTo": "1430964599.844579",
  "statusCode": 200,
  "type": "system.status.result",
  "body": {
    "nodes": {
      "node0:10031/droonga": {
        "status": "active"
      },
      "node1:10031/droonga": {
        "status": "active"
      }
    },
    "reporter": "node0:55329/droonga @ node0:10031/droonga"
  }
}
Elapsed time: 0.014172429
{
  "inReplyTo": "1430964599.8521488",
  "statusCode": 200,
  "type": "system.statistics.object.count.result",
  "body": {
    "total": 549
  }
}

個々のリクエストは1つ前のリクエストに対するレスポンスが得られてから送られるため、大量のメッセージがある場合には非常に時間がかかります。そのような場合のための代わりの選択肢としてはdroonga-sendコマンドがあります。

DroongaクラスタとHTTPで通信する

このコマンドはDroonga Engineとの接続だけでなく、以下のようにしてHTTPプロトコルアダプターとも通信できます：

(on 192.168.100.10)
$ echo '{"type":"system.statistics.object.count","body":{"output":["total"]}}' |
    droonga-request --report-request --protocol http --host 192.168.100.50 --port 10041
Request: {
  "method": "GET",
  "path": "/droonga/system/statistics/object/count?output[]=total",
  "headers": {
    "Accept": "*/*",
    "User-Agent": "Ruby"
  },
  "body": null
}
Elapsed time: 0.026170325
{
  "total": 549
}

HTTPプロトコルアダプタに接続する場合は、使い方が若干変わります：

--protocol http (--protocol=http)オプションを指定する必要があります。
--portオプションを使って、HTTPプロトコルアダプター用に正しいポート番号を指定する必要があります。 (このオプションの値は既定の状態ではDroonga Engineノード用に10031になっていますが、通常、HTTPプロトコルアダプターは10041番ポートを使います。)
--receiver-hostオプションは使用しません。

この利用形態においては、HTTP用のリクエストメッセージを入力として与えることができます。通常のDroongaネイティブプロトコルのメッセージは、上記の例のように自動的にHTTP用のリクエストメッセージに変換されます。

同様の体裁で、独自のHTTPリクエストメッセージを入力として与えることもできます。以下は、POSTメソッドで、独自のユーザーエージェント文字列を伴ったPOSTメソッドのHTTPリクエストを送信する例です：

(on 192.168.100.10)
$ echo '{"method":"POST","path": "/droonga/system/statistics/object/count","headers":{"User-Agent":"Droonga Client"},"body":{"output":["total"]}}' |
    droonga-request --report-request --protocol http --host 192.168.100.50 --port 10041
Request: {
  "method": "POST",
  "path": "/droonga/system/statistics/object/count",
  "headers": {
    "User-Agent": "Droonga Client",
    "Accept": "*/*"
  },
  "body": "{\"output\":[\"total\"]}"
}
Elapsed time: 0.026170325
{
  "total": 549
}

パラメータ

--host=NAME

メッセージの送信先となるDroongaクラスタの接続先ホスト名。既定値は、コマンドを実行しているコンピュータ自身の推測されたホスト名です。

--port=PORT

Droongaクラスタの接続先との通信に使うポート番号。既定値は10031です。

--tag=TAG

Droongaクラスタの接続先との通信に使うタグ名。既定値はdroongaです。

--protocol=PROTOCOL

Droongaクラスタの接続先との通信に使うプロトコル。取り得る値は以下の通りです：

droonga (既定値): Droonga Engineノードのネイティブプロトコル。
http: HTTP。

--timeout=SECONDS

応答がない接続を打ち切るまでの待ち時間（単位：秒）です。既定値は1です。

--receiver-host=NAME

このコマンドを実行しているコンピュータのホスト名。既定値は、そのコンピュータのホスト名として推測される名前です。

--[no-]report-request

実際に送信されたリクエストのメッセージを報告するかどうか。既定の状態は、--no-report-requestが指定されている場合に等しいです。実際に送られたメッセージを見るためには、--report-requestオプションを手動で指定する必要があります。

--[no-]report-elapsed-time

リクエストに対してレスポンスが得られるまでにかかった時間を報告するかどうか。既定の状態は、--report-elapsed-timeが指定されている場合に等しいです。出力からElapsed time:の行を消したい場合は、--no-report-elapsed-timeオプションを手動で指定する必要があります。

--default-dataset=NAME

メッセージの既定の送信先データセット名。既定値はDefaultです。

--default-target-role=ROLE

メッセージを処理できるEngineノードの既定のロール。以下のいずれかを指定します:

service-provider: メッセージは、クラスタ内でサービスを提供中のノードで処理されます。データ抽出操作に関わるノードには、後から遅れてメッセージが伝搬します。
absorb-source: メッセージは、クラスタへのノード追加操作におけるデータコピー元となっているノードで処理されます。サービスを提供中のノード、並びにデータコピー先となっているノードへは、メッセージは伝搬しません。
absorb-destination: メッセージは、クラスタへのノード追加操作におけるデータコピー先となっているノードで処理されます。サービスを提供中のノード、並びにデータコピー元となっているノードへは、メッセージは伝搬しません。
any: メッセージは、--hostで指定されたノードで処理されます。

既定値はanyです。

--[no-]completion

入力メッセージの必須フィールドを補完するかどうか。既定の状態は、--completionが指定されている場合に等しいです。（既定のフィールドが欠落した）壊れたメッセージを意図的に送りたい場合は、--no-completionオプションを手動で指定する必要があります。

--[no-]validation

入力メッセージの妥当性を検証するかどうか。既定の状態は、--validationが指定されている場合に等しいです。妥当でない内容のメッセージを意図的に送りたい場合は、--no-validationオプションを手動で指定する必要があります。

--help

コマンドの使い方の説明を表示します。

インストール方法

このコマンドは、Rubygemsのパッケージdroonga-clientの一部としてインストールされます。

# gem install droonga-client