GridDB Web APIリファレンス

Revision: 4.3.2-9

1 Web API

1.1 概要

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

Web API
Web API

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

1.2 Web APIを利用するには

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

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

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

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

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

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 array クラスタ情報の配列
name string クラスタ名
mode string 接続方式(MULTICAST/FIXED_LIST/PROVIDER )
(mode=MULTICAST)
address string ロウ登録/取得用マルチキャストアドレス
port int ロウ登録/取得用ポート
jdbcAddress string SQL SELECT文用マルチキャストアドレス
jdbcPort int SQL SELECT文用ポート番号
(mode=FIXED_LIST)
transactionMember string ロウ登録/取得用アドレスとポート
sqlMember string SQL SELECT文用アドレスとポート
(mode=PROVIDER)
providerUrl string 全機能共通のプロバイダURL

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

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

【メモ】

1.2.4 Web APIの動作を設定する(任意)

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

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

1.2.4.1 GridDBに関する設定

名前 説明 デフォルト値
failoverTimeout WebAPIからGridDBへのアクセスで、ノード障害を検知してからリトライを繰り返すフェイルオーバー時間(秒)を指定します。 5
transactionTimeout トランザクション開始から終了までの最大時間(秒)を指定します。 30
containerCacheSize コンテナ情報をキャッシュする数を指定します。 100

1.2.4.2 Web APIの動作設定

名前 説明 デフォルト値
port Web APIサービスポート (1~65535までの整数) 8081
maxGetRowSize ロウ取得、TQL実行結果、SQL SELECT文実行結果の上限のサイズ(MB) (1~2048までの整数) 20
maxPutRowSize ロウ登録の上限のサイズ(MB) (1~2048までの整数) 20
loginTimeout SQL SELECT文実行時の接続タイムアウト(秒)
(値は整数を指定します。0以下のときはSQL SELECT文実行を禁止します。)
5
maxQueryNum 一度のリクエストに含められる最大のクエリ数(0~100までの整数) 10
maxLimit TQL, SQL実行時に一度に取得する上限のロウ数(1以上の整数) 10000

【メモ】

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/(コマンドパス)

【メモ】

1.3.2 リクエストヘッダ

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

名前 説明 必須
Content-Type "application/json; charset=UTF-8"
Authorization GridDBへアクセスするユーザとパスワードをuser:password形式で指定します(Basic認証)

1.3.3 リクエストボディ

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

【メモ】

1.3.4 レスポンスコード

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

1.3.5 レスポンスボディ

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

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

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

1.4 ロウ取得

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

コマンドパス

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

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)
:container コンテナ(テーブル)名

HTTPメソッド

POST

リクエストヘッダ

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

リクエストボディ

項目 説明 JSONデータ型 必須
/offset 取得開始位置 数値(0からの整数) -
/limit 取得数 数値(1からの整数)
/condition 条件 文字列 -
/sort ソート条件(カラム名 asc or desc) 文字列 -

【メモ】

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

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

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

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

項目 説明 JSONデータ型
/columns カラム情報の配列 配列
/columns/name カラム名 文字列
/columns/type データ型 文字列
/rows ロウの配列 配列
/total offset, limitを無視した場合の取得ロウ数 数値
/offset 取得開始位置 数値
/limit 適用された取得数 数値

例)

{
  "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データ型で出力されます。

分類 データ型 JSONデータ型
基本型 ブール型 BOOL 真偽値 ( true or false ) true
文字列型 STRING 文字列 "GridDB"
整数型 BYTE/SHORT/INTEGER/LONG 数値 512
浮動小数点数型 FLOAT/DOUBLE 数値 593.5
時刻型 TIMESTAMP 文字列
・UTC
・フォーマット
YYYY-MM-DDThh:mm:ss.SSSZ
"2016-01-16T10:25:00.253Z"
空間型 GEOMETRY 文字列 (WKT表現) "POLYGON((0 0,10 0,10 10,0 10,0 0))"
配列型 ブール型 BOOL 真偽値の配列 [true, false, true]
文字列型 STRING 文字列の配列 ["A","B","C"]
整数型 BYTE/SHORT/INTEGER/LONG 数値の配列 [100, 39, 535]
浮動小数点数型 FLOAT/DOUBLE 数値の配列 [3.52, 6.94, 1.83]
時刻型 TIMESTAMP 文字列の配列
(書式は基本型の時刻型と同じ)
["2016-01-16T10:25:00.253Z", "2016-01-17T01:42:53.038Z"]

【メモ】

1.5 ロウ登録

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

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

【メモ】

コマンドパス

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

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)
:container コンテナ(テーブル)名

HTTPメソッド

PUT

リクエストヘッダ

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

リクエストボディ

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

項目 説明 JSONデータ型 必須
/(row) ロウ(カラム値の配列) 配列

例)

[
  ["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データ型で記述してください。

分類 データ型 JSONデータ型
基本型 ブール型 BOOL 真偽値 ( true or false )
または 文字列 ( "true" or "false")
true
文字列型 STRING 文字列 "GridDB"
整数型 BYTE/SHORT/INTEGER/LONG 数値 または 文字列 512
浮動小数点数型 FLOAT/DOUBLE 数値 または 文字列 593.5
時刻型 TIMESTAMP 文字列
・UTC
・フォーマット
YYYY-MM-DDThh:mm:ss.SSSZ
"2016-01-16T10:25:00.253Z"
空間型 GEOMETRY 文字列 (WKT表現) "POLYGON((0 0,10 0,10 10,0 10,0 0))"
配列型 ブール型 BOOL 真偽値の配列 または 文字列の配列 [true, false, true]
文字列型 STRING 文字列の配列 ["A","B","C"]
整数型 BYTE/SHORT/INTEGER/LONG 数値の配列 または 文字列の配列 [100, 39, 535]
浮動小数点数型 FLOAT/DOUBLE 数値の配列 または 文字列の配列 [3.52, 6.94, 1.83]
時刻型 TIMESTAMP 文字列の配列
(書式は基本型の時刻型と同じ)
["2016-01-16T10:25:00.253Z", "2016-01-17T01:42:53.038Z"]

【メモ】

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

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

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

1.6 データベース接続確認

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

コマンドパス

/:cluster/dbs/:database/checkConnection

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

GET

リクエストヘッダ

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

リクエストパラメータ

項目 説明 データ型 必須
/timeout 本API専用のタイムアウト値(秒) 数値(0からの整数) -

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
500 Web API/GridDBでエラーが発生

レスポンスボディ

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

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

1.7 コンテナ一覧取得

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

コマンドパス

/:cluster/dbs/:database/containers

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

GET

リクエストヘッダ

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

リクエストパラメータ

項目 説明 JSONデータ型 必須
/type 取得コンテナ種別 文字列(collection or timeseries) -
/limit 取得数 数値(0からの整数)
/offset 取得開始位置 数値(0からの整数) -
/sort ソート 文字列 -

【メモ】

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
500 Web API/GridDBでエラーが発生

レスポンスボディ

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

項目 説明 JSONデータ型
/names コンテナ名の配列 配列
/total offset, limitを無視した場合の取得数 数値
/offset 取得開始位置 数値
/limit 適用された取得数 数値

例)

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

1.8 コンテナ情報取得

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

コマンドパス

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

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)
:container コンテナ(テーブル)名

HTTPメソッド

GET

リクエストヘッダ

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

リクエストボディ

なし

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

項目 説明 JSONデータ型
/container_name カラム情報の配列 配列
/container_type カラム名 文字列
/rowkey カラム名 文字列
/columns カラム情報 配列
/columns/name カラム名 文字列
/columns/type カラムのデータ型 文字列
/columns/index インデックス 配列

例)

{
  "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.9 TQL実行

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

コマンドパス

/:cluster/dbs/:database/tql

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

POST

リクエストヘッダ

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

リクエストボディ

項目 説明 JSONデータ型 必須
/name 対象コンテナ名 文字列
/stmt TQL文 文字列
/columns 取得カラム名の配列 配列 -

【メモ】

例)

[
  {"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}
]

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

項目 説明 JSONデータ型
/columns カラム情報の配列 配列
/columns/name カラム名 文字列
/columns/type データ型 文字列
/results TQL実行結果 配列
/total offset, limitを無視した場合の取得数 数値
/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

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)
:container コンテナ(テーブル)名

HTTPメソッド

DELETE

リクエストヘッダ

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

リクエストボディ

項目 説明 JSONデータ型 必須
/(key) ロウキー 配列 -

例)

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

レスポンスコード

コード 説明
204 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

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

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

【メモ】

1.11 コンテナ作成

コンテナを作成します。

コマンドパス

/:cluster/dbs/:database/containers

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

POST

リクエストヘッダ

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

リクエストボディ

項目 説明 JSONデータ型
/container_name カラム情報の配列 配列
/container_type カラム名 文字列
/rowkey カラム名 文字列
/columns カラム情報 配列
/columns/name カラム名 文字列
/columns/type カラムのデータ型 文字列
/columns/index インデックス 配列

例)

{
  "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": []}
  ]
}

レスポンスコード

コード 説明
201 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
409 指定したコンテナがすでに存在する
500 Web API/GridDBでエラーが発生

レスポンスボディ

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

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

【メモ】

1.12 コンテナ削除

コンテナを削除します。

コマンドパス

/:cluster/dbs/:database/containers

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

DELETE

リクエストヘッダ

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

リクエストボディ

項目 説明 JSONデータ型 必須
/(name) コンテナ名 配列 -

例)

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

レスポンスコード

コード 説明
204 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
500 Web API/GridDBでエラーが発生

レスポンスボディ

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

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

1.13 SQL SELECT文実行

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

コマンドパス

/:cluster/dbs/:database/sql

項目 説明
:cluster クラスタ名
:database データベース名 (publicデータベースの場合は "public"を指定してください)

HTTPメソッド

POST

リクエストヘッダ

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

リクエストボディ

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

項目 説明 JSONデータ型 必須
/type クエリ文の種別 ("sql-select"だけを指定できます) 文字列
/stmt SQL SELECT文 文字列

例)

[
  {"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"}
]

レスポンスコード

コード 説明
200 成功
400 リクエストデータの誤り
401 認証エラー、接続エラー
404 指定したリソースが存在しない
500 Web API/GridDBでエラーが発生

レスポンスボディ

項目 説明 JSONデータ型
/columns カラム情報の配列 配列
/columns/name カラム名 文字列
/columns/type データ型 文字列
/rows SQL SELECT実行結果 配列

例)

[
  {
    "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データ型で出力されます。

分類 データ型 JSONデータ型
基本型 ブール型 BOOL 真偽値 ( true or false ) true
文字列型 STRING 文字列 "GridDB"
整数型 BYTE/SHORT/INTEGER/LONG 数値 512
浮動小数点数型 FLOAT/DOUBLE 数値 593.5
時刻型 TIMESTAMP 文字列
・UTC
・フォーマット
YYYY-MM-DDThh:mm:ss.SSSZ
"2016-01-16T10:25:00.253Z"

【メモ】

1.14 動作確認

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

1.15 アンインストール

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

# rpm -e griddb-xx-webapi

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