Revision: 4.3.2-9

1 Web API

1.1 概要

GridDBクラスタに対して、ロウの登録や取得、TQLやSQL文実行などの操作を行うことができるWeb APIを提供します。 Web APIはWebアプリケーションとして構成されます。

Web APIを用いて次のことができます。

• ロウ取得
  • コンテナからロウを取得
• ロウ登録
  • コンテナに対してロウを登録
• データベース接続確認
  • データベースに対して接続を確認
• コンテナ一覧取得
  • データベースに対してコンテナ一覧を取得
• コンテナ情報取得
  • コンテナに対してコンテナ情報（カラムなど）を取得
• TQL文実行
  • 複数のTQL文を実行し結果を取得
• ロウ削除
  • コンテナに対してロウを削除
• コンテナ作成
  • データベースに対して新規コンテナを作成
• コンテナ削除
  • データベースに対してコンテナを削除
• SQL SELECT文実行
  • 指定したデータベースでSQL SELECT文を実行

1.2 Web APIを利用するには

Web APIを利用するには、事前にJavaをインストールする必要があります。対応するバージョンは以下のとおりです。

• Oracle Java 8
• RedHat OpenJDK 8

Web APIのインストールと設定の手順は、以下のとおりです。

1. ライブラリパッケージをインストールする
2. Web APIパッケージをインストールする
3. 接続先のクラスタを設定する
4. Web APIの動作を設定する（任意）
5. ログ出力先を設定する（任意）

1.2.1 ライブラリパッケージをインストールする

以下の二つのパッケージをインストールします。

• Javaライブラリのパッケージ(griddb-xx-java_lib-X.X.X-linux.x86_64.rpm)
• NewSQLインタフェースのパッケージ(griddb-xx-newsql-X.X.X-linux.x86_64.rpm)　※GridDB AEの場合

Web APIアプリケーションを配置するマシンにrootユーザでログインし、以下のコマンドでパッケージをインストールします。

# rpm -Uvh griddb-xx-java_lib-X.X.X-linux.x86_64.rpm
# rpm -Uvh griddb-xx-newsql-X.X.X.linux.x86_64.rpm

※xxはGridDBのエディション(se, ae)

※X.X.XはGridDBのバージョン

1.2.2 Web APIパッケージをインストールする

Web APIのパッケージ(griddb-xx-webapi-X.X.X-linux.x86_64.rpm)をインストールします。

Web APIアプリケーションを配置するマシンにrootユーザでログインし、以下のコマンドでパッケージをインストールします。

# rpm -Uvh griddb-xx-webapi-X.X.X-linux.x86_64.rpm

※xxはGridDBのエディション(se, ae)

※X.X.XはGridDBのバージョン

インストール後、Web APIのjarファイルや設定ファイルは下記のように配置されます。

/usr/griddb-webapi/griddb-webapi.jar                     : Web API jarファイル

/var/lib/gridstore/webapi/conf/griddb_webapi.properties  : 設定ファイル
                              /repository.json           : クラスタ情報定義ファイル
                         /log                            : ログ出力ディレクトリ

1.2.3 接続先のクラスタを設定する

Web APIから接続するクラスタの情報を、クラスタ情報定義ファイル( /var/lib/gridstore/webapi/conf/repository.json )に設定します。

接続するクラスタのクラスタ定義ファイル(gs_cluster.json)の値を基に、modeにクラスタ構成の接続方式を指定し、方式に対応するアドレス情報の項目を記載してください。

例)マルチキャスト方式の場合

{
  "clusters" : [
    {
      "name" : "myCluster",
      "mode" : "MULTICAST",
      "address" : "239.0.0.111",
      "port" : 31999
    }
  ]
}

【メモ】

• repository.jsonの内容が不正である場合（書式誤り、必須パラメータ未定義など）、Web APIの起動がエラーになります。
• GridDB SEのWeb APIから、GridDB AEのクラスタに接続することができます。逆も同じです。ただし、GridDB AE限定のAPIであるSQL SELECT文実行については、GridDB AEのWeb APIからGridDB AEクラスタに接続して実行してください。

1.2.4 Web APIの動作を設定する（任意）

Web APIの動作設定を設定ファイル( /var/lib/gridstore/webapi/conf/griddb_webapi.properties )に設定します。

この設定の変更を行わずに、すべてデフォルト値のままでもWeb APIは動作します。システムの必要に応じて、値の変更を行ってください。

1.2.4.1 GridDBに関する設定

1.2.4.2 Web APIの動作設定

【メモ】

• 環境設定を反映させるにはWeb APIを再起動する必要があります。

1.2.5 ログ出力先を設定する（任意）

Web APIのログは、デフォルトでは下記のディレクトリに出力されます。

/var/lib/gridstore/webapi/log

出力先を変更する場合は、下記のファイルを変更してください。

/var/lib/gridstore/webapi/conf/logback.xml

1.2.6 起動と停止

Web APIアプリケーションはserviceコマンドで起動、停止を行うことができます。

# service griddb-webapi [start|stop|status|restart]

1.3 共通機能(HTTPリクエスト/レスポンス)

各機能において共通のHTTPリクエスト部分について説明します。

1.3.1 URI

Web APIを利用する場合にアクセスするURIです。

http://(Web APIサーバのIP):(port)/griddb/v2/(コマンドパス)

【メモ】

• (コマンドパス)は、各機能の節をご参照ください。
• 名前に記号('-' '.' '/' '=')を含むクラスタ・データベース・コンテナに対して、Web APIで操作を行うことはできません。

1.3.2 リクエストヘッダ

ヘッダには下記の値を指定してください。（全APIで共通）

1.3.3 リクエストボディ

リクエストボディで値を送信する場合、JSON形式で記述してください。JSON形式のフォーマットは、各機能の節をご参照ください。

【メモ】

• JSON形式のデータの文字コードはUTF-8で記述してください。
• 日時を記述する場合は、UTCで下記の形式で記述してください。
  • YYYY-MM-DDThh:mm:ss.SSSZ
• 日付型の値で上記以外の形式を指定した場合は、エラーになります。
  • 例)
    • 2016/01/17T14:32:33.888Z ・・・年月日の区切り文字誤りでエラー
    • 2016-01-18 ・・・時間の指定が無いのでエラー

1.3.4 レスポンスコード

レスポンスコードは各機能の節をご参照ください。

1.3.5 レスポンスボディ

処理が成功した場合のレスポンスボディは、各機能の節をご参照ください。

処理が失敗した場合は、下記の形式でエラーメッセージが返ります。

{
  "version":"v2",
  "errorCode":"エラーコード",
  "errorMessage":"エラーメッセージ"
}

1.4 ロウ取得

コンテナやテーブルのロウを取得します。条件を指定して、取得するロウを絞込むこともできます。

コマンドパス

/:cluster/dbs/:database/containers/:container/rows

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダを参照ください。

リクエストボディ

【メモ】

• limitで指定した値が設定ファイルのmaxLimitよりも大きい場合、maxLimitの値をlimit句に使用します。

例)カラムidの値が50以上のロウデータを、idの値で降順ソートし、11番目から100個取得する

{
  "offset" : 10,
  "limit"  : 100,
  "condition" : "id >= 50",
  "sort" : "id desc"
}

レスポンスコード

レスポンスボディ

取得したロウは、下記の形式のJSONデータで返ります。

例)

{
  "columns" : [
    {"name": "date", "type": "TIMESTAMP" },
    {"name": "value", "type": "DOUBLE" },
    {"name": "str", "type": "STRING" }
  ],
  "rows" : [
    ["2016-01-16T10:25:00.253Z", 100.5, "normal" ],
    ["2016-01-16T10:35:00.691Z", 173.9, "normal" ],
    ["2016-01-16T10:45:00.032Z", 173.9, null ]
  ],
  "total" : 100000,
  "offset" : 0,
  "limit" : 3
}

ロウのカラム値はカラムのデータ型に応じて、下記のJSONデータ型で出力されます。

【メモ】

• BLOB型は未サポートです。BLOB型のカラムを持つコンテナを指定した場合、BLOBのカラムは空文字が返ります。
• カラムのデータがNULL値の場合は、JSONデータ型のnullが返ります。

1.5 ロウ登録

コンテナにロウを登録します。

登録するロウは、JSON形式で指定します。ひとつのコンテナに複数のロウを登録することもできます。

【メモ】

• ひとつのコンテナに１ロウ/複数ロウのデータを指定して登録することができます。
• 登録先のコンテナは存在している必要があります。
• ロウキーが指定されているコンテナの場合、既にコンテナに存在するロウキーと同一のロウキーを指定するとロウが更新されます。ロウキーが異なる場合は、登録されます。
• ロウキーが指定されていないコンテナの場合、新しいロウとして登録されます。
• ロウ登録処理の途中で例外が発生した場合、一部のロウに対する登録のみが反映されたままとなる場合があります。そのため、例外発生時にHTTPクライアントでリトライする場合、ロウキーが指定されていないコンテナの場合は同じデータが重複して登録される場合があります。

コマンドパス

/:cluster/dbs/:database/containers/:container/rows

HTTPメソッド

PUT

リクエストヘッダ

リクエストヘッダを参照ください。

リクエストボディ

ロウを下記のJSON形式で指定してください。

例)

[
  ["2016-01-16T10:25:00.253Z", 100.5, "normal"],
  ["2016-01-16T10:35:00.691Z", 173.9, "normal"],
  ["2016-01-16T10:45:00.032Z", 173.9, null]
]

ロウのカラム値はカラムのデータ型に応じて、下記のJSONデータ型で記述してください。

【メモ】

• BLOB型はサポートしていません。BLOB型のカラムを持つコンテナを指定するとエラーになります。
• カラムのデータにNULL値（JSONデータ型のnull）を指定した場合、以下のように動作します。
  • 対応するカラムにNOT NULL制約が設定されている場合：登録エラー
  • 対応するカラムにNOT NULL制約が設定されていない場合：NULL値が登録される

レスポンスコード

レスポンスボディ

処理に成功した場合は、何も返りません。

失敗した場合のレスポンスボディは、レスポンスボディを参照ください。

1.6 データベース接続確認

指定したデータベースへの接続を確認します。

コマンドパス

/:cluster/dbs/:database/checkConnection

HTTPメソッド

GET

リクエストヘッダ

リクエストヘッダを参照ください。

リクエストパラメータ

レスポンスコード

レスポンスボディ

処理に成功した場合は、何も返りません。

失敗した場合のレスポンスボディは、レスポンスボディを参照ください。

1.7 コンテナ一覧取得

コンテナやテーブルの一覧を取得します。条件を指定して、取得するコンテナを絞込むこともできます。

コマンドパス

/:cluster/dbs/:database/containers

HTTPメソッド

GET

リクエストヘッダ

リクエストヘッダを参照ください。

リクエストパラメータ

【メモ】

• limitで0を指定した場合は、条件に合致するすべてのロウが返ります。
• offsetは、必ずlimitと同時に使用する必要があります。

レスポンスコード

レスポンスボディ

取得したロウは、下記の形式のJSONデータで返ります。

例)

{
  "names" : [
    "container1",
    "container2",
    "timeseries1"
  ],
  "total" : 100000,
  "offset" : 0,
  "limit" : 3
}

1.8 コンテナ情報取得

コンテナやテーブルの情報を取得します。

コマンドパス

/:cluster/dbs/:database/containers/:container/info

HTTPメソッド

GET

リクエストヘッダ

リクエストヘッダを参照ください。

リクエストボディ

なし

レスポンスコード

レスポンスボディ

例)

{
  "container_name" : "container1",
  "container_type" : "collection",
  "rowkey" : true,
  "columns" : [
    {"name": "date", "type": "TIMESTAMP", "index": ["tree"]},
    {"name": "value", "type": "DOUBLE", "index": []},
    {"name": "str", "type": "STRING", "index": []}
  ]
}

【メモ】

• 複合ロウキー、複合索引が設定されているコンテナは非対応です。実行するとIllegalStateExceptionが発生します。

1.9 TQL実行

TQL文を実行します。複数のTQL文を一度に送信することができます。また、実行結果で特定のカラムの値だけを取得することができます。

コマンドパス

/:cluster/dbs/:database/tql

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダを参照ください。

リクエストボディ

【メモ】

• TQL文中のlimitで指定した値が設定ファイルのmaxLimitよりも大きい場合、maxLimitの値をlimit句に使用します。

例)

[
  {"name" : "container1", "stmt" : "select * limit 100", "columns" : null},
  {"name" : "container2", "stmt" : "select * where column1>=0", "columns" : ["column1"]},
  {"name" : "container3", "stmt" : "select SUM(*) order by column1 desc", "columns" : null}
]

レスポンスコード

レスポンスボディ

【メモ】

• TQL文が集約演算の場合、total, offset, limitは含まれません。

例)

[
  {
    "columns" : [
      {"name": "date", "type": "TIMESTAMP"},
      {"name": "value", "type": "DOUBLE"},
      {"name": "str", "type": "STRING"}
    ],
    "results" : [
      ["2016-01-16T10:25:00.253Z", 100.5, "normal" ],
      ["2016-01-16T10:35:00.691Z", 173.9, "normal" ],
      ["2016-01-16T10:45:00.032Z", 173.9, null]
    ],
    "total" : 1000125,
    "offset" : 0,
    "limit" : 3
  },
  {
    "columns" : [
      {"name": "aggregationResult", "type": "LONG"}
    ],
    "results" : [
      [55]
    ]
  }
]

1.10 ロウ削除

コンテナやテーブルのロウを削除します。

コマンドパス

/:cluster/dbs/:database/containers/:container/rows

HTTPメソッド

DELETE

リクエストヘッダ

リクエストヘッダを参照ください。

リクエストボディ

例)

[
  "key1",
  "key2",
  "key3"
]

レスポンスコード

レスポンスボディ

処理に成功した場合は、何も返りません。

失敗した場合のレスポンスボディは、レスポンスボディを参照ください。

【メモ】

• 複合ロウキーが設定されているコンテナは非対応です。実行するとIllegalStateExceptionが発生します。

1.11 コンテナ作成

コンテナを作成します。

コマンドパス

/:cluster/dbs/:database/containers

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダを参照ください。

リクエストボディ

例)

{
  "container_name" : "container1",
  "container_type" : "collection",
  "rowkey" : true,
  "columns" : [
    {"name": "date", "type": "TIMESTAMP", "index": ["tree"]},
    {"name": "value", "type": "DOUBLE", "index": []},
    {"name": "str", "type": "STRING", "index": []}
  ]
}

レスポンスコード

レスポンスボディ

処理に成功した場合は、何も返りません。

失敗した場合のレスポンスボディは、レスポンスボディを参照ください。

【メモ】

• 複合ロウキー、複合索引は非対応です。

1.12 コンテナ削除

コンテナを削除します。

コマンドパス

/:cluster/dbs/:database/containers

HTTPメソッド

DELETE

リクエストヘッダ

リクエストヘッダを参照ください。

リクエストボディ

例)

[
  "container1",
  "container2",
  "timeseries1"
]

レスポンスコード

レスポンスボディ

処理に成功した場合は、何も返りません。

失敗した場合のレスポンスボディは、レスポンスボディを参照ください。

1.13 SQL SELECT文実行

指定したデータベースでSQL SELECT文を実行します。 本機能は、GridDB Advanced Editionでのみ使用できます。

コマンドパス

/:cluster/dbs/:database/sql

HTTPメソッド

POST

リクエストヘッダ

リクエストヘッダを参照ください。

リクエストボディ

SQL SELECT文を下記のJSON形式で指定してください。

例)

[
  {"type" : "sql-select", "stmt" : "select * from container1"},
  {"type" : "sql-select", "stmt" : "select column1 from container 2 where column1>=0"},
  {"type" : "sql-select", "stmt" : "select column2, column3 from container3 order by column1 desc"}
]

レスポンスコード

レスポンスボディ

例)

[
  {
    "columns" : [
      {"name": "date", "type": "TIMESTAMP"},
      {"name": "value", "type": "DOUBLE"},
      {"name": "str", "type": "STRING"}
    ],
    "rows" : [
      ["2016-01-16T10:25:00.253Z", 100.5, "normal" ],
      ["2016-01-16T10:35:00.691Z", 173.9, "normal" ],
      ["2016-01-16T10:45:00.032Z", 173.9, null]
    ]
  },
  {
    "columns" : [
      {"name": "date", "type": "TIMESTAMP"},
      {"name": "value", "type": "DOUBLE"},
      {"name": "str", "type": "STRING"}
    ],
    "results" : [
      ["2016-01-16T10:25:00.253Z", 100.5, "normal" ],
      ["2016-01-16T10:35:00.691Z", 173.9, "normal" ],
      ["2016-01-16T10:45:00.032Z", 173.9, null]
    ]
  }
]

ロウのカラム値はカラムのデータ型に応じて、下記のJSONデータ型で出力されます。

【メモ】

• カラムのデータがNULL値の場合は、JSONデータ型のnullが返ります。
• BLOB型、GEOMETRY型、配列型は未サポートです。
• BLOB型のカラムを持つコンテナを指定した場合、データ型は”BLOB”となりますが、カラムのデータとしては空文字が返ります。
• GEOMETRY型と配列型カラムのデータ型は”UNKNOWN”となり、カラムのデータとしてはnullが返ります。

1.14 動作確認

Web APIの動作確認は、Linuxのcurlコマンド等で行ってください。

• 例)ロウ取得

  curl -X POST -u "user:password" \\
  -H "Content-type:application/json; charset=UTF-8" -d '{"limit":5,"sort":"id asc"}' \\
  http://host:port/griddb/v2/cluster/dbs/public/containers/test/rows
  

• 例)ロウ登録

  curl -X PUT -u "user:password" \\
  -H "Content-type:application/json; charset=UTF-8" -d '[[1,"value"],[2,"value"]]' \\
  http://host:port/griddb/v2/cluster/dbs/public/containers/test/rows
  

• 例)SQL SELECT文実行

  curl -X POST -u "user:password" \\
  -H "Content-type:application/json; charset=UTF-8" -d '{"type":"sql-select","stmt":"select * from test"}' \\
  http://host:port/griddb/v2/cluster/dbs/public/sql
  

1.15 アンインストール

Web APIを停止したあと、以下の手順でディレクトリおよび配置したファイルを削除してください。

# rpm -e griddb-xx-webapi

※xxはGridDBのエディション(se, ae)