メッセージ形式

リクエスト

リクエストのメッセージの基本的な形式は以下の通りです。

{
  "id"      : "<メッセージの識別子>",
  "type"    : "<メッセージの種類>",
  "replyTo" : "<レスポンスの受信者へのパス>",
  "dataset" : "<対象データセット名>",
  "timeout" : <結果を待つ秒数>,
  "targetRole" : "<対象となるロール>",
  "body"    : <メッセージ本文>
}

id

概要
そのメッセージの一意な識別子。
値
識別子となる文字列。一意でさえあれば、どんな形式のどんな文字列でも指定できます。値は対応するレスポンスの‘inReplyTo`に使われます。
省略時の既定値
なし。この情報は省略できません。

type

概要
そのメッセージの種類。
値
コマンドの名前の文字列
省略時の既定値
なし。この情報は省略できません。

replyTo

概要
レスポンスの受信者へのパス。
値
<ホスト>:<ポート番号>/<タグ名> で示されたパス文字列。例：localhost:24224/output.
省略時の既定値
なし。この情報は省略可能で、省略した場合はレスポンスのメッセージは単に捨てられます。

dataset

概要
対象となるデータセット。
値
データセット名の文字列。
省略時の既定値
なし。この情報は省略できません。

timeout

概要
リクエストメッセージが有効な期間を示す秒数。 もし指定された時間までにリクエストに対応する結果が返されなかった場合、システムはそのリクエストに起因するすべてのメッセージの追跡を打ち切ります。 その際、クライアントはこれを「操作がタイムアウトした」と報告することがあります。
値
浮動小数点小数。例：0.5.
省略時の既定値
60（＝1分）

targetRole

概要
メッセージを処理する対象とするEngineノードのロール。 メッセージを受け取ったノード自身のロールがこのフィールドの値と異なっていた場合、メッセージはそのロールを持つ他のEngineノードにそのまま転送されます。 targetRoleが無い、または特別な値"any"が指定された場合、そのノードのロールが何であるかに関わらず、メッセージを受信したノードがメッセージを処理します。
値
null、"any"、または以下のいずれか：
  • "service-provider"
  • "absorb-source"
  • "absorb-destination"
省略時の初期値
null

body

概要
メッセージの本文。
値
オブジェクト、文字列、数値、真偽値、または null。
省略時の既定値
なし。この情報は省略可能です。

レスポンス

レスポンスのメッセージの基本的な形式は以下の通りです。

{
  "type"       : "<メッセージの種類>",
  "inReplyTo"  : "<対応するリクエストメッセージの識別子>",
  "statusCode" : <ステータスコード>,
  "body"       : <メッセージの本文>,
  "errors"     : <ノードから返されたエラー>
}

type

概要
そのメッセージの種類。
値
メッセージの種類を示す文字列。多くの場合は、元のリクエストメッセージの type の値に .result という接尾辞を伴った文字列です。

inReplyTo

概要
対応するリクエストメッセージの識別子。
値
対応するリクエストメッセージの識別子の文字列 related request message.

statusCode

概要
そのメッセージの種類。
値
ステータスコードを示す整数。

レスポンスのステータスコードはHTTPのステータスコードに似ています。

200 およびその他の 2xx のステータス
コマンドが正常に処理されたことを示します。

body

概要
そのリクエストメッセージの処理結果の情報。
値
オブジェクト、文字列、数値、真偽値、または null。

errors

概要
各ノードから返されたすべてのエラー。
値
オブジェクト。

この情報は、コマンドが複数のボリュームに分散して処理された時にのみ現れます。それ以外の場合、レスポンスメッセージは errors フィールドを含みません。詳細はエラーレスポンスの説明を参照して下さい。

エラーレスポンス

コマンドの中にはエラーを返す物があります。

エラーレスポンスは通常のレスポンスと同じ type を伴って返されますが、通常のレスポンスとは異なる statusCode と body を持ちます。大まかなエラーの種類は statusCode で示され、詳細な情報は body の内容として返されます。

コマンドが複数のボリュームに分散して処理されて、各ボリュームがエラーを返した場合、レスポンスメッセージは errors フィールドを持ちます。各ボリュームから返されたエラーは以下のように保持されます：

{
  "type"       : "add.result",
  "inReplyTo"  : "...",
  "statusCode" : 400,
  "body"       : {
    "name":    "UnknownTable",
    "message": ...
  },
  "errors"     : {
    "/path/to/the/node1" : {
      "statusCode" : 400,
      "body"       : {
        "name":    "UnknownTable",
        "message": ...
      }
    },
    "/path/to/the/node2" : {
      "statusCode" : 400,
      "body"       : {
        "name":    "UnknownTable",
        "message": ...
      }
    }
  }
}

このような場合、すべてのエラーの中で代表的な1つがメッセージの body に出力されます。

エラーレスポンスのステータスコード

エラーレスポンスのステータスコードはHTTPのステータスコードに似ています。

400 およびその他の 4xx のステータス
リクエストのメッセージが原因でのエラーであることを示します。
500 およびその他の 5xx のステータス
Droonga Engine内部のエラーであることを示します。

エラーレスポンスの body

エラーレスポンスの body の基本的な形式は以下の通りです。

{
  "name"    : "<エラーの種類>",
  "message" : "<人間が読みやすい形式で示されたエラーの詳細>",
  "detail"  : <任意の形式の、追加のエラー情報>
}

追加の情報がない場合、 detail は出力されないことがあります。

エラーの種類

すべてのコマンドに共通するエラーとして、以下の物があります。

MissingDatasetParameter
dataset の指定がないことを示します。ステータスコードは 400 です。
UnknownDataset
指定されたデータセットが存在しないことを示します。ステータスコードは 404 です。
UnknownType
type に指定されたコマンドを処理するハンドラが存在しない、未知のコマンドであることを示します。ステータスコードは 400 です。