GridDB Web APIリファレンス

Revision: 4.6.0-400

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
• Oracle Java 11
• RedHat OpenJDK 8
• RedHat OpenJDK 11

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

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

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

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

• Javaライブラリのパッケージ(griddb-ee-java_lib-X.X.X-linux.x86_64.rpm)

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

# rpm -Uvh griddb-ee-java_lib-X.X.X-linux.x86_64.rpm

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

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

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

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

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

※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の起動がエラーになります。

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を再起動する必要があります。
• LDAP認証、SSL接続の詳細は『GridDB 機能リファレンス』(GridDB_FeaturesReference.html)を参照してください。
• GridDBクラスタでSSL接続設定が無効の場合、本ツールの設定に依らず、SSL通信は行うことができません。
• SSL通信設定(sslMode)をVERIFYに設定する場合、信頼する認証局の証明書が必要です。keytoolコマンドを使ってインポートしてください。また、java起動時の引数でトラストストア(-Djavax.net.ssl.trustStore)やパスワード((-Djavax.net.ssl.trustStorePassword)を指定したい場合は、環境変数GS_COMMON_JVM_ARGSに指定してください。信頼する認証局の証明書の有効期限切れ確認は未サポートです。
• 環境変数GS_COMMON_JVM_ARGSは、以下を参考に/etc/environmentへ設定してください。設定を反映させるにはWeb APIを再起動する必要があります。

例）

GS_COMMON_JVM_ARGS="-Djavax.net.ssl.trustStore=/var/lib/gridstore/admin/keystore.jks -Djavax.net.ssl.trustStorePassword=changeit"

• クライアントとWEB API間でSSL通信を行う場合、以下を参考に/usr/griddb-webapi/application.propertiesへ設定してください。

例）

server.ssl.enabled=true
server.port=8443
server.ssl.key-store-type=JKS
server.ssl.key-store=/var/lib/gridstore/admin/keystore.jks
server.ssl.key-store-password=changeit
server.ssl.key-alias=tomcat

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文を実行します。

コマンドパス

/: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 -f -X GET -u "user:password" \
  http://host:port/griddb/v2/cluster/dbs/public/checkConnection
  

• 例)コンテナ一覧取得

  curl -f -X GET -u "user:password" \
  http://host:port/griddb/v2/cluster/dbs/public/containers?limit=100
  

• 例)ロウ取得

  curl -f -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 -f -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 -f -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-ee-webapi