GridDB Web APIリファレンス
Revision: 5.7.0-932
1 Web API
1.1 概要
GridDBクラスタに対して、ロウの登録や取得、TQLやSQL文実行などの操作を行うことができるWeb APIを提供します。 Web APIはWebアプリケーションとして構成されます。
Web APIを用いて次のことができます。
- ロウ取得
- コンテナからロウを取得
- コンテナから複数のロウを取得
- ロウ登録
- コンテナに対してロウを登録
- 複数のコンテナに対してロウを登録
- データベース接続確認
- データベースに対して接続を確認
- コンテナ一覧取得
- データベースに対してコンテナ一覧を取得
- コンテナ情報取得
- コンテナに対してコンテナ情報(カラムに関してなど)を取得
- TQL文実行
- 複数のTQL文を実行し結果を取得
- ロウ削除
- コンテナに対してロウを削除
- コンテナ作成
- データベースに対して新規コンテナを作成
- コンテナ削除
- データベースに対してコンテナを削除
- SQL DDL文実行
- 指定したデータベースでSQL DDL文を実行
- SQL DML SELECT文実行
- 指定したデータベースでSQL SELECT文を実行
- SQL DML UPDATE文実行
- 指定したデータベースでSQL UPDATE文を実行
- SQL DCL文実行
- 指定したデータベースでSQL DCL文を実行
- SQL SELECT文実行
- 指定したデータベースでSQL SELECT文を実行
- SQL UPDATE文実行
- 指定したデータベースでSQL UPDATE文を実行
1.2 Web APIを利用するには
Web APIを利用するには、事前にJavaをインストールする必要があります。対応するバージョンは以下のとおりです。
- Oracle Java 8
- Oracle Java 11
- OpenJDK 8
- OpenJDK 11
Web APIのインストールと設定の手順は、以下のとおりです。
- ライブラリパッケージをインストールする
- Web APIパッケージをインストールする
- 接続先のクラスタを設定する
- Web APIの動作を設定する(任意)
- ログ出力先を設定する(任意)
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-ee-webapi-X.X.X/ : Web APIインストールディレクトリ
conf/
etc/
griddb-webapi-ee-X.X.X.jar : Web API jarファイル
/usr/girddb-webapi/griddb-webapi.jar -> /usr/griddb-ee-webapi-X.X.X/griddb-webapi-ee-X.X.X.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にクラスタ構成の接続方式を指定し、方式に対応するアドレス情報の項目を記載してください。
パラメータ | JSONデータ型 | 説明 |
---|---|---|
clusters | 配列 | クラスタ情報の配列 |
name | 文字列 | クラスタ名 |
mode | 文字列 | 接続方式(MULTICAST/FIXED_LIST/PROVIDER ) |
(mode=MULTICAST) | ||
address | 文字列 | ロウ登録/取得用マルチキャストアドレス |
port | 整数 | ロウ登録/取得用ポート |
jdbcAddress | 文字列 | SQL実行用マルチキャストアドレス |
jdbcPort | 整数 | SQL実行用ポート番号 |
(mode=FIXED_LIST) | ||
transactionMember | 文字列 | ロウ登録/取得用アドレスとポート |
sqlMember | 文字列 | SQL実行用アドレスとポート |
(mode=PROVIDER) | ||
providerUrl | 文字列 | 全機能共通のプロバイダURL |
例)マルチキャスト方式の場合
{
"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に関する設定
項目 | 説明 | デフォルト値 |
---|---|---|
failoverTimeout | WebAPIからGridDBへのアクセスでノード障害を検知してからリトライを繰り返すフェイルオーバー時間(秒) | 5 |
transactionTimeout | トランザクション開始から終了までの最大時間(秒) | 30 |
containerCacheSize | コンテナ情報をキャッシュする最大数 | 100 |
1.2.4.2 Web APIの動作設定
項目 | 説明 | デフォルト値 |
---|---|---|
maxResponseSize | ロウ取得、SQL実行結果、TQL実行結果の上限のサイズ(MB) (1~2048までの整数) | 20 |
maxRequestSize | ロウ登録の上限のサイズ(MB) (1~2048までの整数) | 20 |
loginTimeout | SQL実行時の接続タイムアウト(秒) (値は整数を指定します。0以下のときはSQL実行はできません。) |
5 |
maxQueryNum | 一回のリクエストに含められる最大のSELECT文のクエリ数(0~100までの整数) | 10 |
maxLimit | SQL, TQL実行時に一度に取得する上限のロウ数(1以上の整数) | 10000 |
timeZone | SQL、TQLで時刻情報を取得する際のオフセット計算に利用するタイムゾーンとして、時刻(±hh:mm または ±hhmm), タイムゾーンID(「Z」のみサポート), AUTO(JavaVMの環境引継ぎ)のいずれかを指定 | Z |
authenticationMethod | 認証方式として、INTERNAL(内部認証) / LDAP(LDAP認証)のいずれかを指定 | GridDBクラスタ設定に依存 |
notificationInterfaceAddress | 複数のネットワークインターフェースがあるときにクラスタのネットワーク構成をマルチキャスト方式にする場合、マルチキャストパケットを受信するインターフェースのIPアドレスを指定 | OSに依存 |
sslMode | SSL接続設定として、DISABLED(SSL無効)、PREFERRED(SSL有効、ただし非SSL接続も許容),VERIFY(SSL有効かつサーバ証明書検証実施)のいずれかを指定 | PREFERRED |
blobPath | BLOBデータをzipファイルとして処理する際、一時データを保管するために用いられるディレクトリ | - |
【メモ】
- 環境設定を反映させるには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
- Web APIの使用するポート番号を変更する場合は、以下の/usr/griddb-webapi/application.propertiesの設定を変更してください。設定可能な値は1~65535までの整数です。
#HTTP/HTTPS port
server.port=8081
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で共通)
項目 | 説明 | 必須 |
---|---|---|
Content-Type | "application/json; charset=UTF-8" | ○ |
Authorization | GridDBへアクセスするユーザとパスワードをuser:password形式で指定します(Basic認証) | ○ |
1.3.3 リクエストボディ
リクエストボディで値を送信する場合、JSON形式で記述してください。JSON形式のフォーマットは、各機能の節をご参照ください。
【メモ】
JSON形式のデータの文字コードはUTF-8で記述してください。
日時を記述する場合は、UTCで下記の形式で記述してください。
- YYYY-MM-DDThh:mm:ss.SSSZ
日付型の値で上記以外の形式を指定した場合は、エラーになります。
- 例)
- 2016/01/17T14:32:33.888Z ・・・年月日の区切り文字誤りでエラー
- 2016-01-18 ・・・時間の指定がないのでエラー
- 例)
リクエストボディのJSONデータの最大値(単位:MB)は、下のように
griddb_webapi.properties
で設定できます。maxRequestSize=20
1.3.4 レスポンスコード
レスポンスコードは各機能の節をご参照ください。
1.3.5 レスポンスボディ
処理が成功した場合のレスポンスボディは、各機能の節をご参照ください。
処理が失敗した場合は、下記の形式でエラーメッセージが返ります。
{
"version":"v2",
"errorCode":"エラーコード",
"errorMessage":"エラーメッセージ"
}
【メモ】
リクエストボディのJSONデータの最大値(単位:MB)は、下のように
griddb_webapi.properties
で設定できます。maxResponseSize=20
1.4 ロウ取得
1.4.1 単一のコンテナからのロウ取得
コンテナやテーブルのロウを取得します。条件を指定して、取得するロウを絞込むこともできます。
コマンドパス
/:cluster/dbs/:database/containers/:container/rows
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースの場合は "public"を指定してください) |
:container | コンテナ(テーブル)名 |
HTTPメソッド
POST
リクエストヘッダ
リクエストヘッダを参照してください。
リクエストボディ
項目 | 説明 | JSONデータ型 | 必須 |
---|---|---|---|
/offset | 取得開始位置 | 数値(0からの整数) | - |
/limit | 取得数 | 数値(1からの整数) | ○ |
/condition | 条件式(詳細は『GridDB TQLリファレンス』(GridDB_TQL_Reference.html)参照) | 文字列 | - |
/sort | ソート条件(指定したカラムの値の昇順(asc)・降順(desc)。「カラム名 asc」または「カラム名 desc」と記述する。) | 文字列 | - |
【メモ】
- limitで指定した値が設定ファイルのmaxLimitの値よりも大きい場合、maxLimitの値をlimit句に使用します。
例)カラム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 または 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))" | |
BLOB型 | BLOB | 文字列 | "UEsDBAoAAAgAADS4PFIAAAAAAAAAAAA..." | |
配列型 | ブール型 | 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"] |
【メモ】
- BLOBデータはbase64形式で返ります。そのため、BLOBデータの取得後にbase64のデータをデコードする必要があります。
- カラム値がNULLの場合、JSONデータのカラムにはnullが返ります。
1.4.2 単一のコンテナからのロウ取得(zipファイル形式のBLOBデータ)
本機能はコンテナ (テーブル)からロウを取得します。コンテナにBLOBカラムがある場合、BLOBデータはzipファイルとして返ります。条件を指定して、取得するロウを絞り込むこともできます。
コマンドパス
/:cluster/dbs/:database/containers/:container/rows/blob
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースには"public"を指定してください) |
:container | コンテナ (テーブル) 名 |
HTTPメソッド
POST
リクエストヘッダ
リクエストヘッダを参照してください。
リクエストボディ
項目名 | 説明 | JSONデータ型 | 必須 |
---|---|---|---|
/offset | 取得開始位置 | 0からの整数 | - |
/limit | 取得するロウ数 | 1からの整数 | ○ |
/condition | 条件式(詳細は『GridDB TQLリファレンス』(GridDB_TQL_Reference.html)参照) | 文字列 | - |
/sort | ソート条件 (指定したカラムの値の昇順(asc)・降順(desc)。「カラム名 asc」または「カラム名 desc」と記述する。) | string | - |
/fileNameCol | 値をBLOBデータファイル名に用いるコンテナ内のカラム名 | 文字列 | - |
【メモ】
- limitで指定される値が設定ファイルのmaxLimitの値よりも大きい場合、limit句ではmaxLimitの値が用いられます。
- デフォルトでは各ロウのBLOBデータはランダムな名前でファイル拡張子なしで保存されます。 Web APIにはBLOBデータファイル名を別のカラムの値に設定するオプションがあります。例えば、BLOBデータのファイル名を保管する文字列型カラム
file_name
を有するテーブルの場合、オプションによりこのカラムの値を使って各ロウのBLOBデータファイル名を設定することができます。:{"fileNameCol": "<column_name>"}
次の例ではカラム"id" の値が50以上のロウデータを取得し、取得したデータを"id"の値の降順にソートし、10番目のロウから100の値を取得し、カラムfile_name
の値をBLOBデータファイル名に用います。
{
"offset" : 10,
"limit" : 100,
"condition" : "id >= 50",
"sort" : "id desc",
"fileNameCol": "file_name"
}
レスポンスコード
コード | 説明 |
---|---|
200 | 成功 |
400 | リクエストデータの誤り |
401 | 認証エラー、接続エラー |
404 | 指定したリソースが存在しない |
500 | Web API/GridDBでエラーが発生 |
レスポンスボディ
レスポンスボディは次のフォームデータとして返ります。
キー | 説明 | コンテンツタイプ |
---|---|---|
file | zipファイルは全BLOBデータファイルを含みます。 このzipファイルの名前としてランダムな名前が生成され、レスポンスに付加されます。 |
application/zip |
rows | 非BLOBのカラムデータ | application/json |
rows
の値は次のJSONデータとして返ります。
項目 | 説明 | JSONデータ型 |
---|---|---|
/columns | カラム情報の配列 | 配列 |
/columns/name | カラム名 | 文字列 |
/columns/type | カラムデータ型 | 文字列 |
/rows | ロウの配列 | 配列 |
/total | offsetとlimitを無視した場合に取得するロウ数 | 数値 |
/offset | 取得開始位置 | 数値 |
/limit | 適用する取得数 | 数値 |
【メモ】
- コンテナにBLOBカラムがない場合またはクエリ結果にBLOBデータがない場合、Web APIは中にファイルを含まないzipファイルを返します。
- コンテナに2つ以上のBLOBカラムがある場合、BLOBデータファイル名は同じ名前の前に番号を付けたものになります。 例:1_picture.jpg、2_picture.jpg.
fileNameCol
のロウ値が無効なファイル名を有する場合、APIサーバはランダムな名前を生成します。- zipファイル中のBLOBファイル名はJSONデータ中のBLOBカラムの値と同一であり、双方とも
(BLOB)
という接頭辞で始まります。 - レスポンスデータには、JSONデータとフォームデータの2つのデータ型があります。この両者の間は
--
で始まる文字列で区切られます。最初のデータがJSONデータで次に来るのがフォームデータです。全BLOBデータファイルを含むzipファイルを取得するには、バイナリの中身をコピーして(PK
という接頭辞を最初につけます)、.zip
拡張子のファイルに保存します。
例:
- 次はレスポンスボディの一例です。
--zO7yOzRXhcrXUbD7heAB9rGzewWDfUt
Content-Disposition: form-data; name="rows"
Content-Type: application/json;charset=UTF-8
{"columns":[{"name":"key","type":"INTEGER"},{"name":"data","type":"BLOB"},{"name":"des","type":"STRING"}],"rows":[[1000,"(BLOB)d0f925b9-884a-420a-a7a8-91c53ed7b126","lombok"],[200,"(BLOB)dee59ebc-2bf9-4f36-9b86-0bf72ff16e29","anh2.png"]],"offset":0,"limit":2,"total":3}
--zO7yOzRXhcrXUbD7heAB9rGzewWDfUt
Content-Disposition: form-data; name="file"; filename="e17bba76-4315-4c32-9384-81fff84abc84.zip"
Content-Type: application/zip
Content-Length: 1780817
PKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
カラム値はカラムのデータ型に応じて、下記のJSONデータ型を戻します。
分類 | データ型 | JSONデータ型 | 例 | |
---|---|---|---|---|
基本型 | ブール型 | BOOL | 真偽値 (true または 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"] |
【メモ】
- カラム値がNULLの場合、JSONデータのカラムにはnullが返ります。
1.4.3 複数のコンテナからのロウ取得
本機能は複数のコンテナ(テーブル)からロウを取得します。条件を指定して取得するロウを絞り込むこともできます。本機能はロウキーを有するコンテナにのみサポートされています。
コマンドパス
/:cluster/dbs/:database/containers/rows
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースの場合は "public"を指定してください) |
HTTPメソッド
POST
リクエストヘッダ
リクエストヘッダを参照してください。
リクエストボディ
項目 | 説明 | JSONデータ型 | 必須 | デフォルト値 |
---|---|---|---|---|
/name | コンテナ名 | 文字列 | ○ | - |
/startKeyValue | - ロウデータを取得する開始位置を指定するためのロウキー値。 - startKeyValue はデータ型がLONG、INTEGER、TIMESTAMPのいずれかであるひとつのロウキーを有するコンテナに対してのみ適用されます。- ロウキーがTIMESTAMP型の場合、開始のキー値は次の形式になっている必要があります。 yyyy-MM-ddTHH:mm:ss.SSSZ |
文字列または数値 | - | - |
/finishKeyValue | - ロウデータを取得する終了位置を指定するためのロウキー値。 - finishKeyValue はデータ型がLONG、INTEGER、TIMESTAMPのいずれかであるひとつのロウキーを有するコンテナに対してのみ適用されます。- ロウキーがTIMESTAMP型の場合、終了のキー値は次の形式になっている必要があります。 yyyy-MM-ddTHH:mm:ss.SSSZ |
文字列または数値 | - | - |
/keyValues | - ロウデータ取得の検索条件として使われるロウキー値の一覧。この一覧中の値と一致するロウキーを有するロウデータが返ります。 - keyValues はデータ型がSTRING、LONG、 INTEGER、TIMESTAMPのいずれかであるひとつのロウキーを有するコンテナに対してのみ適用されます。- startKeyValue 、 finishKeyValue 、keyValues を同時に指定した場合、Web APIはkeyValues の条件を使ってロウを取得し、startKeyValue とfinishKeyValue は無視します。- ロウキーがTIMESTAMP型の場合、キー値は次の形式になっている必要があります。 yyyy-MM-ddTHH:mm:ss.SSSZ |
文字列/数値の配列 | - | - |
/offset | 取得開始位置。offsetは各コンテナに対し設定されます。 | 0からの整数 | - | 0 |
/limit | 取得するロウ数。limitは各コンテナに対し設定されます。 | 1からの整数 | - | 10000 |
【メモ】
- limitに指定された値が設定ファイルのmaxLimitの値よりも大きい場合、maxLimitの値をlimit句に使用します。
- BLOBデータはbase64形式で返ります。そのため、BLOBデータの取得後にbase64のデータをデコードする必要があります。
startKeyValue
、finishKeyValue
、keyValues
の条件はひとつのロウキーを有するコンテナにのみサポートされています。
次の例は2つのコンテナからロウデータを取得します。最初のコンテナはキー値が0から100であるロウデータを取得し、その中の2番目のロウから10個の値を取得します。2番目のコンテナはキー値が1、3、5のいずれかであるロウデータを取得します。
[
{
"name":"container1",
"startKeyValue":0,
"finishKeyValue":100,
"limit":10,
"offset":2
},
{
"name":"container2",
"keyValues":[1, 3, 5]
}
]
レスポンスコード
コード | 説明 |
---|---|
200 | 成功 |
400 | リクエストデータの誤り |
401 | 認証エラー、接続エラー |
404 | 指定したリソースが存在しない |
500 | Web API/GridDBでエラーが発生 |
レスポンスボディ
取得したロウは次のJSONデータとして返ります。
項目 | 説明 | JSONデータ型 |
---|---|---|
/container | コンテナ名 | 文字列 |
/columns | カラム情報の配列 | 配列 |
/columns/name | カラム名 | 文字列 |
/columns/type | JSONデータ型 | 文字列 |
/results | ロウの配列 | Array |
/total | offset, limitを無視した場合のロウの取得数 | 数値 |
/offset | 取得開始位置 | 数値 |
/limit | 適用された取得数 | 数値 |
例)
[
{
"container":"container1",
"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":100,
"offset":0,
"limit":3
},
{
"container":"container2",
"columns": [
{ "name":"date", "type":"STRING" },
{ "name":"value", "type":"LONG" }
],
"results": [
["string1", 100],
["string2", 173],
["string3", 200]
],
"total":10000,
"offset":0,
"limit":10000
}
]
カラムのデータ型に応じて、次のJSONタイプのカラム値が戻ります。本セクションを参照してください。
【メモ】
- カラム値がNULLの場合、JSONデータのカラムにはnullが返ります。
1.5 ロウ登録
1.5.1 単一のコンテナへのロウ登録
ひとつのコンテナにロウを登録します。
登録するロウは、JSON形式で指定します。ひとつのコンテナに複数のロウを登録することもできます。
【メモ】
- ひとつのコンテナに1ロウ/複数ロウのデータを指定して登録することができます。
- 登録先のコンテナは存在している必要があります。
- ロウキーが指定されているコンテナの場合、既にコンテナに存在するロウキーと同一のロウキーを指定するとロウが更新されます。ロウキーが異なる場合は、ロウが新規に登録されます。
- ロウキーが指定されていないコンテナの場合、すべてのロウが新規に登録されます。
- Web APIはbase64形式のBLOBデータをサポートしています。そのため、このデータをリクエストボディに指定する前にbase64のBLOBデータはエンコードする必要があります。
- ロウ登録処理の途中で例外が発生した場合、一部のロウに対する登録のみが反映されたままとなる場合があります。そのため、例外発生時にHTTPクライアントでリトライする場合、ロウキーが指定されていないコンテナの場合は同じデータが重複して登録される場合があります。
コマンドパス
/: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 または false) または 文字列 ("true" または "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))" | |
BLOB型 | BLOB | 文字列 | "UEsDBAoAAAgAADS4PFIAAAAAAAAAAAA..." | |
配列型 | ブール型 | 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"] |
【メモ】
- カラムのデータにNULL値(JSONデータ型のnull)を指定した場合、Web APIは以下のように動作します。
- 対応するカラムにNOT NULL制約が設定されている場合:登録エラー
- 対応するカラムにNOT NULL制約が設定されていない場合:NULL値が登録される
レスポンスコード
コード | 説明 |
---|---|
200 | 成功 |
400 | リクエストデータの誤り |
401 | 認証エラー、接続エラー |
404 | 指定したリソースが存在しない |
500 | Web API/GridDBでエラーが発生 |
レスポンスボディ
レスポンスボディはJSONデータとして返ります。
項目 | 説明 | JSONデータ型 |
---|---|---|
/count | 更新/挿入されたロウ数 | 数値 |
例)
{
"count" : 2
}
1.5.2 単一のコンテナへのロウ登録(zipファイル形式のBLOBデータ)
本機能は指定したBLOBデータを有するコンテナにロウを登録します。
登録するロウをフォームデータの形式で指定します。ひとつのコンテナに複数のロウを登録することができます。
【メモ】
- ひとつのコンテナに1ロウ/複数ロウのデータを指定して登録することができます。
- 登録先のコンテナは存在している必要があります。
- ロウキーが指定されているコンテナの場合、既にコンテナに存在するロウキーと同一のロウキーを指定するとロウが更新されます。ロウキーが異なる場合は、ロウが新規に登録されます。
- ロウキーが指定されていないコンテナの場合、ロウが新規に登録されます。
- ロウ登録処理の途中で例外が発生した場合、一部のロウに対する登録のみが反映されたままとなる場合があります。そのため、例外発生時にHTTPクライアントでリトライする場合、ロウキーが指定されていないコンテナの場合は同じデータが重複して登録される場合があります。
コマンドパス
/:cluster/dbs/:database/containers/:container/rows/blob
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースの場合は "public"を指定してください) |
:container | コンテナ(テーブル)名 |
HTTPメソッド
PUT
リクエストヘッダ
リクエストヘッダを参照してください。
リクエストボディ
リクエストボディを次のフォームデータとして指定します。
キー | 説明 | コンテンツタイプ |
---|---|---|
file | zipファイルはすべてのBLOBデータファイルを含みます。 | application/zip |
rows | JSON形式でコンテナに追加する必要のあるロウの一覧(各ロウはオブジェクトの一覧) | application/json |
rows
を下記のJSON形式で指定してください。
項目 | 説明 | JSONデータ型 | 必須 |
---|---|---|---|
/(row) | ロウ(カラム値の配列) | 配列 | ○ |
【メモ】
BLOBカラムの値は文字列型である必要があります。これはzipファイル中のファイル名(大文字/小文字を区別) についても同じです。
BLOBカラムの値がzipファイル中にない場合、エラーが返ります。
zipファイルにサブディレクトリがある場合、BLOBカラム値にそのサブディレクトリを指定してください。
アップロードファイルの最大サイズは次のようにapplication.propertiesファイルで設定できます。
例)
zipファイルが以下のファイル構造である場合、
file.zip |----image1.png |----picture |----image2.png
リクエストボディの
rows
のデータ型は以下のようになっている必要があります。[ ["5","image1.png"], ["6","picture/image2.png"] ]
カラム値はカラムのデータ型に応じて、下記のJSONデータ型で記述してください。
分類 | データ型 | JSONデータ型 | 例 | |
---|---|---|---|---|
基本型 | ブール型 | BOOL | 真偽値(true または false) または文字列("true"または"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"] |
【メモ】
- カラムのデータにNULL値(JSONデータ型のnull)を指定した場合、Web APIは以下のように動作します。
- 対応するカラムにNOT NULL制約が設定されている場合:登録エラーが発生
- 対応するカラムにNOT NULL制約が設定されていない場合:NULL値が登録される
レスポンスコード
コード | 説明 |
---|---|
200 | 成功 |
400 | リクエストデータの誤り |
401 | 認証エラー、接続エラー |
404 | 指定したリソースが存在しない |
500 | Web API/GridDBでエラーが発生 |
レスポンスボディ
処理に成功した場合は、何も返りません。
失敗した場合のレスポンスボディは、レスポンスボディ を参照してください。
1.5.3 複数のコンテナへのロウ登録
本機能は複数のコンテナにロウを登録します。
登録するロウは、JSON形式で指定します。ひとつのコンテナに複数のロウを登録することもできます。
【メモ】
- ひとつのコンテナにひとつまたは複数ロウのデータを指定して登録することができます。
- 登録先のコンテナは存在している必要があります。
- ロウキーが指定されているコンテナの場合、既にコンテナに存在するロウキーと同一のロウキーを指定するとロウが更新されます。ロウキーが異なる場合は、ロウが新規に登録されます。
- ロウキーが指定されていないコンテナの場合、すべてのロウが新規に登録されます。
- ひとつのロウの中の値の数は、ひとつのコンテナの中のカラム数と等しい必要があります。カラムがnullableの場合、そのカラムの値は省略できません。
null
または空の値として指定する必要があります。 - Web APIはbase64形式のBLOBデータをサポートしています。そのため、このデータをリクエストボディに指定する前にbase64のBLOBデータはエンコードする必要があります。
- ロウ登録処理の途中で例外が発生した場合、一部のロウに対する登録のみが反映されたままとなる場合があります。そのため、例外発生時にHTTPクライアントでリトライする場合、ロウキーが指定されていないコンテナの場合は同じデータが重複して登録される場合があります。
コマンドパス
/:cluster/dbs/:database/containers/rows
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースの場合は "public"を指定してください) |
HTTPメソッド
PUT
リクエストヘッダ
リクエストヘッダ を参照してください。
リクエストボディ
ロウを下記のJSON形式で指定してください。
項目 | 説明 | JSONデータ型 | 必須 |
---|---|---|---|
/containerName | コンテナ名 | 文字列 | ○ |
/rows | ロウ(カラム値の配列) | 配列 | ○ |
【メモ】
- ロウキーがTIMESTAMP型の場合、ロウの値は次の形式である必要があります。
yyyy-MM-ddTHH:mm:ss.SSSZ
例)
[
{
"containerName":"container2",
"rows":[
["a3", "a4"],
["b3", "b4"]
]
},
{
"containerName":"container4",
"rows":[
[3000, 4000],
[5000, 6000]
]
}
]
カラム値はカラムのデータ型に応じて、下記のJSONデータ型で記述してください。
本セクション を参照してください。
【メモ】
- カラム値にNULL値(JSONデータ型のnull)を指定した場合、Web APIは以下のように動作します。
- 対応するカラムにNOT NULL制約が設定されている場合:登録エラーが発生
- 対応するカラムにNOT NULL制約が設定されていない場合:NULL値が登録される
レスポンスコード
コード | 説明 |
---|---|
200 | 成功 |
400 | リクエストデータの誤り |
401 | 認証エラー、接続エラー |
404 | 指定したリソースが存在しない |
500 | Web API/GridDBでエラーが発生 |
レスポンスボディ
レスポンスボディは下記のJSONデータで返ります。
項目 | 説明 | JSONデータ型 |
---|---|---|
/containerName | コンテナ名 | 文字列 |
/updatedRows | 更新/挿入されたロウ数 | 数値 |
例)
[
{
"containerName":"container2",
"updatedRows" : 2
},
{
"containerName":"container4",
"updatedRows" : 2
}
]
1.6 データベース接続確認
指定したデータベースへの接続を確認します。
コマンドパス
/:cluster/dbs/:database/checkConnection
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースの場合は "public"を指定してください) |
HTTPメソッド
GET
リクエストヘッダ
リクエストヘッダを参照してください。
リクエストパラメータ
項目 | 説明 | データ型 | 必須 |
---|---|---|---|
/timeout | Web API専用のタイムアウト値(秒) | 数値(0からの整数) | - |
レスポンスコード
コード | 説明 |
---|---|
200 | 成功 |
400 | リクエストデータの誤り |
401 | 認証エラー、接続エラー |
500 | Web API/GridDBでエラーが発生 |
レスポンスボディ
処理に成功した場合は、何も返りません。
失敗した場合のレスポンスボディは、レスポンスボディを参照してください。
1.7 コンテナ一覧取得
コンテナやテーブルの一覧を取得します。条件を指定して、取得するコンテナを絞込むこともできます。
コマンドパス
/:cluster/dbs/:database/containers
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースの場合は "public"を指定してください) |
HTTPメソッド
GET
リクエストヘッダ
リクエストヘッダを参照してください。
リクエストパラメータ
項目 | 説明 | JSONデータ型 | 必須 |
---|---|---|---|
/type | 取得コンテナ種別 | 文字列(COLLECTION または TIME_SERIES) | - |
/limit | 取得数 | 数値(0からの整数) | ○ |
/offset | 取得開始位置 | 数値(0からの整数) | - |
/sort | ソート | 文字列 | - |
【メモ】
- offsetは、必ずlimitと同時に使用する必要があります。
レスポンスコード
コード | 説明 |
---|---|
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 | コンテナ種別 | 文字列(COLLECTION または TIME_SERIES) |
/rowkey | ロウキー有無 | 真偽値(true または false) |
/columns | カラム情報の配列 | 配列 |
/columns/name | カラム名 | 文字列 |
/columns/type | カラムのデータ型 | 文字列 |
/columns/index | インデックス | 文字列の配列(TREE または SPATIAL) |
例)
{
"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
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースの場合は "public"を指定してください) |
HTTPメソッド
POST
リクエストヘッダ
リクエストヘッダを参照してください。
リクエストボディ
項目 | 説明 | JSONデータ型 | 必須 |
---|---|---|---|
/name | 対象コンテナ名 | 文字列 | ○ |
/stmt | TQL文 | 文字列 | ○ |
/columns | 取得カラム名の配列 | 配列 | - |
/hasPartialExecution | 部分実行モードの設定有無。デフォルト値は設定無し | 真偽値(true または false) | - |
【メモ】
- TQL文中のlimitで指定した値が設定ファイルのmaxLimitの値よりも大きい場合、maxLimitの値をlimit句に使用します。
例)
[
{"name" : "container1", "stmt" : "select * limit 100", "columns" : null, "hasPartialExecution" : true},
{"name" : "myTable", "stmt" : "select * limit 100", "columns" : ["value1"]}
]
レスポンスコード
コード | 説明 |
---|---|
200 | 成功 |
400 | リクエストデータの誤り |
401 | 認証エラー、接続エラー |
404 | 指定したリソースが存在しない |
500 | Web API/GridDBでエラーが発生 |
レスポンスボディ
項目 | 説明 | JSONデータ型 |
---|---|---|
/columns | カラム情報の配列 | 配列 |
/columns/name | カラム名 | 文字列 |
/columns/type | データ型 | 文字列 |
/results | TQL実行結果 | 配列 |
/total | offset, limitを無視した場合の取得数 | 数値 |
/offset | 取得開始位置 | 数値 |
/limit | 適用された取得数 | 数値 |
/responseSizeByte | レスポンスサイズ | 数値 |
【メモ】
- TQL文が集約演算の場合、total, offset, limitは含まれません。
例)
[
{
"columns":[
{"name":"date","type":"TIMESTAMP","timePrecision":"MILLISECOND"},
{"name":"value","type":"DOUBLE"},{"name":"str","type":"STRING"}
],
"results":[
["2016-01-16T10:25:00.253Z",20.02,"row_example_1"],
["2016-01-16T10:25:00.254Z",20.03,"row_example_2"],
["2016-01-16T10:25:00.255Z",20.04,"row_example_3"],
["2016-01-16T10:25:00.256Z",20.05,"row_example_4"]
],
"offset":0,
"limit":100,
"total":4,
"responseSizeByte":116
},
{
"columns":[
{"name":"value1","type":"DOUBLE"}
],
"results":[
[1.0]
],
"offset":0,
"limit":100,
"total":1,
"responseSizeByte":8
}
]
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でエラーが発生 |
レスポンスボディ
処理に成功した場合は、何も返りません。
失敗した場合のレスポンスボディは、レスポンスボディを参照してください。
【メモ】
- 複合ロウキーが設定されているコンテナは非対応です。実行するとIllegalStateExceptionが発生します。
1.11 コンテナ作成
コンテナを作成します。
コマンドパス
/:cluster/dbs/:database/containers
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースの場合は "public"を指定してください) |
HTTPメソッド
POST
リクエストヘッダ
リクエストヘッダを参照してください。
リクエストボディ
項目 | 説明 | JSONデータ型 | 必須 |
---|---|---|---|
/container_name | コンテナ名 | 文字列 | ○ |
/container_type | コンテナ種別 | 文字列(COLLECTION または TIME_SERIES) | ○ |
/rowkey | ロウキー有無 | 真偽値(true または false) | ○ |
/columns | カラム情報の配列 | 配列 | ○ |
/columns/name | カラム名 | 文字列 | ○ |
/columns/type | カラムのデータ型 | 文字列 | ○ |
/columns/index | インデックス | 文字列の配列(TREE または SPATIAL) | - |
例)
{
"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 DDL文実行
本機能はGridDBのデータベースでひとつまたは複数のSQL DDL文(CREATE TABLE, DROP TABLE, ALTER TABLE)を実行します。
コマンドパス
/:cluster/dbs/:database/sql/ddl
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースの場合は "public"を指定してください) |
HTTPメソッド
POST
リクエストヘッダ
リクエストヘッダ参照してください。
リクエストボディ
ひとつまたは複数のSQL DDL文を下記のJSON形式で指定してください。
項目 | 説明 | JSONデータ型 | 必須 |
---|---|---|---|
/stmt | SQL DDL文 | string | ○ |
例)
[
{"stmt" : "CREATE TABLE myTable (key INTEGER PRIMARY KEY, value1 DOUBLE NOT NULL, value2 DOUBLE NOT NULL)"}
]
レスポンスコード
コード | 説明 |
---|---|
200 | 成功 |
400 | リクエストデータの誤り |
401 | 認証エラー、接続エラー |
500 | Web API/GridDBでエラーが発生 |
レスポンスボディ
項目 | 説明 | JSONデータ型 |
---|---|---|
/status | SQL DDL文のステータス。 1 と 0 はそれぞれ成功と失敗を指します。0 が含まれる場合も、HTTPのステータスコードは200(OK)が返ります。 |
数値 |
/stmt | SQL DDL文 | 文字列 |
/message | クエリ実行時に表示されるエラーメッセージ | 文字列 |
例)
[
{
"status" : 1,
"stmt" : "CREATE TABLE myTable (key INTEGER PRIMARY KEY, value1 DOUBLE NOT NULL, value2 DOUBLE NOT NULL)",
"message": null
}
]
1.14 SQL DML SELECT文実行
指定したデータベースでひとつまたは複数のSQL SELECT文を実行します。
コマンドパス
/:cluster/dbs/:database/sql/dml/query
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースの場合は "public"を指定してください) |
HTTPメソッド
POST
リクエストヘッダ
リクエストヘッダを参照してください。
リクエストボディ
ひとつまたは複数のSQL SELECT文を下記のJSON形式で指定してください。
項目 | 説明 | JSONデータ型 | 必須 |
---|---|---|---|
/stmt | SQL SELECT文 | 文字列 | ○ |
例)
[
{"stmt" : "select * from container1"},
{"stmt" : "select * from myTable"}
]
レスポンスコード
コード | 説明 |
---|---|
200 | 成功 |
400 | リクエストデータの誤り |
401 | 認証エラー、接続エラー |
404 | 指定したリソースが存在しない |
500 | Web API/GridDBでエラーが発生 |
レスポンスボディ
項目 | 説明 | JSONデータ型 |
---|---|---|
/columns | カラム情報の配列 | 配列 |
/columns/name | カラム名 | 文字列 |
/columns/type | データ型 | 文字列 |
/results | SQL SELECT実行結果 | 配列 |
/responseSizeByte | レスポンスサイズ | 数値 |
例)
[
{
"columns":[
{"name":"date","type":"TIMESTAMP","timePrecision":"MILLISECOND"},
{"name":"value","type":"DOUBLE"},
{"name":"str","type":"STRING"}
],
"results":[
["2016-01-16T10:25:00.253Z",20.02,"row_example_1"],
["2016-01-16T10:25:00.254Z",20.03,"row_example_2"],
["2016-01-16T10:25:00.255Z",20.04,"row_example_3"],
["2016-01-16T10:25:00.256Z",20.05,"row_example_4"]
],
"responseSizeByte":180
},
{
"columns":[
{"name":"key","type":"INTEGER"},
{"name":"value1","type":"DOUBLE"},
{"name":"value2","type":"DOUBLE"}
],
"results":[
[1,1.0,2.0]
],
"responseSizeByte":20
}
]
ロウのカラム値はカラムのデータ型に応じて、下記のJSONデータ型で出力されます。
分類 | データ型 | JSONデータ型 | 例 | |
---|---|---|---|---|
基本型 | ブール型 | BOOL | 真偽値 (true または 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" |
【メモ】
- カラムのデータがNULL値の場合は、JSONデータ型のnullが返ります。
- GEOMETRY型、配列型は未サポートです。
- GEOMETRY型と配列型カラムのデータ型は”UNKNOWN”となり、カラムのデータとしてはnullが返ります。
- 複数のSQLを指定する際、どれかひとつでも実行に失敗した場合、HTTPレスポンスのステータスコードとして400が返ります。この際、失敗したSQL以降のSQLは実行されません。
1.15 SQL DML UPDATE文実行
本機能はGridDBのデータベースでひとつまたは複数のSQL UPDATE文(UPDATE, INSERT, DELETE, REPLACE)を実行します。
コマンドパス
/:cluster/dbs/:database/sql/dml/update
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースの場合は "public"を指定してください) |
HTTPメソッド
POST
リクエストヘッダ
リクエストヘッダ参照してください。
リクエストボディ
ひとつまたは複数のSQL UPDATE文を下記のJSON形式で指定してください。
項目 | 説明 | JSONデータ型 | 必須 |
---|---|---|---|
/stmt | SQL UPDATE文 | string | ○ |
例)
[
{"stmt" : "update container1 set col2 = 333 where col1 = 't3'"}
]
レスポンスコード
コード | 説明 |
---|---|
200 | 成功 |
400 | リクエストデータの誤り |
401 | 認証エラー、接続エラー |
500 | Web API/GridDBでエラーが発生 |
レスポンスボディ
項目 | 説明 | JSONデータ型 |
---|---|---|
/status | SQL UPDATE文のステータス。 1 と 0 はそれぞれ成功と失敗を指します。0 が含まれる場合も、HTTPのステータスコードは200(OK)が返ります。 |
数値 |
/message | クエリ実行時に表示されるエラーメッセージ | 文字列 |
/updatedRows | 更新または挿入されたロウ数 | 数値 |
/stmt | SQL UPDATE文 | 文字列 |
例)
[
{
"status" : 1,
"updatedRows" : 2,
"stmt" : "update container1 set col2 = 333 where col1 = 't3'",
"message": null
}
]
1.16 SQL DCL文実行
本機能はGridDBのデータベースでひとつまたは複数のSQL DCL文(GRANT, REVOKE, SET PASSWORD)を実行します。
コマンドパス
/:cluster/dbs/:database/sql/dcl
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースの場合は "public"を指定してください) |
HTTPメソッド
POST
リクエストヘッダ
リクエストヘッダ参照してください。
リクエストボディ
ひとつまたは複数のSQL DCL文を下記のJSON形式で指定してください。
項目 | 説明 | JSONデータ型 | 必須 |
---|---|---|---|
/stmt | SQL DCL文 | string | ○ |
例)
[
{"stmt" : "grant all on database1 to user1"}
]
レスポンスコード
コード | 説明 |
---|---|
200 | 成功 |
400 | リクエストデータの誤り |
401 | 認証エラー、接続エラー |
500 | Web API/GridDBでエラーが発生 |
レスポンスボディ
項目 | 説明 | JSONデータ型 |
---|---|---|
/status | SQL DLC文のステータス。 1 と 0 はそれぞれ成功と失敗を指します。0 が含まれる場合も、HTTPのステータスコードは200(OK)が返ります。 |
数値 |
/message | クエリ実行時に表示されるエラーメッセージ | 文字列 |
/stmt | SQL DCL文 | 文字列 |
Example:
[
{
"status" : 1,
"stmt" : "grant all on database1 to user1",
"message": null
}
]
1.17 【非推奨】SQL SELECT文実行
指定したデータベースでひとつまたは複数のSQL SELECT文を実行します。
コマンドパス
/:cluster/dbs/:database/sql/select
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースの場合は "public"を指定してください) |
HTTPメソッド
POST
リクエストヘッダ
リクエストヘッダを参照してください。
リクエストボディ
ひとつまたは複数のSQL SELECT文を下記のJSON形式で指定してください。
項目 | 説明 | JSONデータ型 | 必須 |
---|---|---|---|
/stmt | SQL SELECT文 | 文字列 | ○ |
例)
[
{"stmt" : "select * from container1"},
{"stmt" : "select * from myTable"}
]
レスポンスコード
コード | 説明 |
---|---|
200 | 成功 |
400 | リクエストデータの誤り |
401 | 認証エラー、接続エラー |
404 | 指定したリソースが存在しない |
500 | Web API/GridDBでエラーが発生 |
レスポンスボディ
項目 | 説明 | JSONデータ型 |
---|---|---|
/columns | カラム情報の配列 | 配列 |
/columns/name | カラム名 | 文字列 |
/columns/type | データ型 | 文字列 |
/results | SQL SELECT実行結果 | 配列 |
/responseSizeByte | レスポンスサイズ | 数値 |
例)
[
{
"columns":[
{"name":"date","type":"TIMESTAMP","timePrecision":"MILLISECOND"},
{"name":"value","type":"DOUBLE"},
{"name":"str","type":"STRING"}
],
"results":[
["2016-01-16T10:25:00.253Z",20.02,"row_example_1"],
["2016-01-16T10:25:00.254Z",20.03,"row_example_2"],
["2016-01-16T10:25:00.255Z",20.04,"row_example_3"],
["2016-01-16T10:25:00.256Z",20.05,"row_example_4"]
],
"responseSizeByte":180
},
{
"columns":[
{"name":"key","type":"INTEGER"},
{"name":"value1","type":"DOUBLE"},
{"name":"value2","type":"DOUBLE"}
],
"results":[
[1,1.0,2.0]
],
"responseSizeByte":20
}
]
ロウのカラム値はカラムのデータ型に応じて、下記のJSONデータ型で出力されます。
分類 | データ型 | JSONデータ型 | 例 | |
---|---|---|---|---|
基本型 | ブール型 | BOOL | 真偽値 (true または 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" |
【メモ】
- カラムのデータがNULL値の場合は、JSONデータ型のnullが返ります。
- GEOMETRY型、配列型は未サポートです。
- GEOMETRY型と配列型カラムのデータ型は”UNKNOWN”となり、カラムのデータとしてはnullが返ります。
- 複数のSQLを指定する際、どれかひとつでも実行に失敗した場合、HTTPレスポンスのステータスコードとして400が返ります。この際、失敗したSQL以降のSQLは実行されません。
1.18 【非推奨】SQL UPDATE文実行
本機能はGridDBのデータベースでひとつまたは複数のSQL UPDATE文を実行します。
コマンドパス
/:cluster/dbs/:database/sql/update
項目 | 説明 |
---|---|
:cluster | クラスタ名 |
:database | データベース名 (publicデータベースの場合は "public"を指定してください) |
HTTPメソッド
POST
リクエストヘッダ
リクエストヘッダ参照してください。
リクエストボディ
ひとつまたは複数のSQL UPDATE文を下記のJSON形式で指定してください。
項目 | 説明 | JSONデータ型 | 必須 |
---|---|---|---|
/stmt | SQL UPDATE文 | string | ○ |
【メモ】
- Web APIではSQL文中のSELECT、EXPLAIN、ANALYZEはサポートされていません。
例)
[
{"stmt" : "update container1 set col2 = 333 where col1 = 't3'"}
]
レスポンスコード
コード | 説明 |
---|---|
200 | 成功 |
400 | リクエストデータの誤り |
401 | 認証エラー、接続エラー |
500 | Web API/GridDBでエラーが発生 |
レスポンスボディ
項目 | 説明 | JSONデータ型 |
---|---|---|
/status | SQL UPDATE文のステータス。 1 と 0 はそれぞれ成功と失敗を指します。0 が含まれる場合も、HTTPのステータスコードは200(OK)が返ります。 |
数値 |
/message | クエリ実行時に表示されるエラーメッセージ | 文字列 |
/updatedRows | 更新または挿入されたロウ数 | 数値 |
/stmt | SQL UPDATE文 | 文字列 |
Example:
[
{
"status" : 1,
"updatedRows" : 2,
"stmt" : "update container1 set col2 = 333 where col1 = 't3'",
"message": null
}
]
1.19 動作確認
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 '[{"stmt":"select * from test"}]' \ http://host:port/griddb/v2/cluster/dbs/public/sql/select
1.20 アンインストール
Web APIを停止したあと、以下の手順でディレクトリおよび配置したファイルを削除してください。
# rpm -e griddb-ee-webapi