Db2 Warehouse on Cloud の REST API を試す #初心者

「マニュアルに載ってるよ～」
https://developer.ibm.com/static/site-id/85/api/db2whc-v3/
はいはい…確かにマニュアルにのっております。しかし経験のない人にはマニュアルを見てもさっぱりなのです。（自分のこと）
ということで、なかなかシンプルなやり方についてサンプルがなかったのでやってみました。

準備するもの。

Db2 Warehouse on Cloud
cURLコマンドが打てる環境。またはRESTクライアント(ChromeならPOSTMANかなぁ https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop , FirefoxはRESTClient https://addons.mozilla.org/ja/firefox/addon/restclient )といったところでしょうか

全体の流れ

以前はベーシック認証が利用でき、URLにユーザー名とパスワードを埋め込めば簡単にアクセス出来ていましたが、REST APIのバージョンが上がり、アクセストークンによる認証に変更になっています。
1. アクセストークンを取得する
2. 取得したアクセストークンを利用してREST APIを実行

これだけです。これだけなのにサンプルがない！日本語の…

1. アクセストークンの取得

Every request must include the Authorization HTTP header with the value
Bearer [access_token].
An access token can be obtained with the /auth/tokens endpoint,

はい。さっぱりなのでとりあえずやってみる

$ curl -X POST 'https://dashdb-xxxxxxxxxx.bluemix.net:8443/dbapi/v3/auth/tokens' -d '{"userid":"mikan", "password":"mikanpassword"}'

結果

{"userid":"mikan","token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzczNTc5OTIsInVzZXJOYW1lIjoibm9tYSIsImNvb2tpZSI6IiIsImlzc3VlIjoiaHR0cHM6Ly8xMC4xNDMuMTMzLjExMDo4ODgwLyJ9.RGV97DWU7aRlfxDw_QdtyRuEJoQiib_w0n7u4NFBNRc"}

このランダムな文字列がアクセストークンです。
"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzczNTc5OTIsInVzZXJOYW1lIjoibm9tYSIsImNvb2tpZSI6IiIsImlzc3VlIjoiaHR0cHM6Ly8xMC4xNDMuMTMzLjExMDo4ODgwLyJ9.RGV97DWU7aRlfxDw_QdtyRuEJoQiib_w0n7u4NFBNRc"

ちなみに。このアクセストークンには期限があります。恐らく1時間です。

2. 取得したアクセストークンを利用してREST API を実行

さっそくやってみましょう。

まずはデータベースのモニターから

GET /monitor

$ curl -X GET 'https://dashdb-xxxxxxxxxx.bluemix.net:8443/dbapi/v3/monitor' -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzczNTc5OTIsInVzZXJOYW1lIjoibm9tYSIsImNvb2tpZSI6IiIsImlzc3VlIjoiaHR0cHM6Ly8xMC4xNDMuMTMzLjExMDo4ODgwLyJ9.RGV97DWU7aRlfxDw_QdtyRuEJoQiib_w0n7u4NFBNRc' -d '{"userid":"mikan", "password":"mikanpassword"}'

結果

{"authentication_service":"online","messages":"","database_service":"online"}

ストレージの利用状況の確認

GET /monitor/storage

$ curl -X GET 'https://dashdb-xxxxxxxxxx.bluemix.net:8443/dbapi/v3/monitor/storage' -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzczNTc5OTIsInVzZXJOYW1lIjoibm9tYSIsImNvb2tpZSI6IiIsImlzc3VlIjoiaHR0cHM6Ly8xMC4xNDMuMTMzLjExMDo4ODgwLyJ9.RGV97DWU7aRlfxDw_QdtyRuEJoQiib_w0n7u4NFBNRc'

※一度トークンが認証されると次回から"userid"と"password"は省略可能で、トークンだけで認証OKです。
ただし期限があるので注意。

結果

{"capacity_kb":4128243712,"usage":59,"name":"Database storage","available_kb":1680867328,"used_kb":2446327808,"collected_at":1537357602048}

という感じでURLを目的に応じて変更するだけです。
ちょっと結果のJSONが見にくいとか日本語が化けるという方は最初に紹介したRESTクライアントを利用するとラクチンです。

3.SQLを実行してみよう！

SQLの実行は少し変わっていて、実行して結果が出るではなく、実行すると結果セットが一旦引き出しに入って、
引き出しを指定してデータをダウンロードするという2段階の操作が必要です。

まずはSQLの実行です。

POST /sql_jobs

SQLは以下の例のJSONにしてPOSTします。

{
"commands":"select * from tokyo;",    --- 実行したいSQLクエリ
"limit":10,                           --- 結果セットの取得行数の指定（デフォルト1000）
"separator":";",                      --- SQLの終端文字
"stop_on_error":"no"                  --- エラー発生時にジョブを止めるかどうか
}

以下のように実行します。

$ curl -X POST 'https://dashdb-xxxxxxxxxx.bluemix.net:8443/dbapi/v3/sql_jobs' -H 'Content-type: application/json' -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzczNTc5OTIsInVzZXJOYW1lIjoibm9tYSIsImNvb2tpZSI6IiIsImlzc3VlIjoiaHR0cHM6Ly8xMC4xNDMuMTMzLjExMDo4ODgwLyJ9.RGV97DWU7aRlfxDw_QdtyRuEJoQiib_w0n7u4NFBNRc' -d '{"commands":"SELECT * FROM TOKYO;","limit":10,"separator":";","stop_on_error":"no"}'

JSONをPOSTするためにヘッダにContent-type: application/jsonを付けないとうまく動きませんでした。
結果

{"commands_count":1,"limit":10,"id":"1537436952027_1854825181_-1644888840"}

この結果にある1537436952027_1854825181_-1644888840 が結果セットの入っている引き出しの番号になります。

引き出しの番号を指定して結果の取り出しを行います。

GET /sql_jobs/{id}

$ curl -X GET 'https://dashdb-enterprise4-yp-dal09-25.services.dal.bluemix.net:8443/dbapi/v3/sql_jobs/1537436952027_1854825181_-1644888840' -H 'Content-type: application/json' -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzczNTc5OTIsInVzZXJOYW1lIjoibm9tYSIsImNvb2tpZSI6IiIsImlzc3VlIjoiaHR0cHM6Ly8xMC4xNDMuMTMzLjExMDo4ODgwLyJ9.RGV97DWU7aRlfxDw_QdtyRuEJoQiib_w0n7u4NFBNRc'

結果

{"id":"1537436952027_1854825181_-1644888840","results":[{"rows_affected":0,"rows_count":10,"runtime_seconds":19,"columns":["\u5e74\u6708\u65e5\u6642","\u6c17\u6e29","\u6c17\u6e29\u54c1\u8cea\u60c5\u5831","\u6c17\u6e29\u5747\u8cea\u756a\u53f7","\u964d\u6c34\u91cf","\u964d\u6c34\u91cf\u73fe\u8c61\u306a\u3057\u60c5\u5831","\u964d\u6c34\u91cf\u54c1\u8cea\u60c5\u5831","\u964d\u6c34\u91cf\u5747\u8cea\u756a\u53f7"],"limit":10,"last_inserted":0,"rows":[["2013-2-8 7:00:00","4.1","8","1","0.0","1","8","1"],["2013-2-8 8:00:00","3.8","8","1","0.0","1","8","1"],["2013-2-8 9:00:00","3.9","8","1","0.0","1","8","1"],["2013-2-8 10:00:00","4.0","8","1","0.0","1","8","1"],["2013-2-8 11:00:00","4.9","8","1","0.0","1","8","1"],["2013-2-8 12:00:00","4.8","8","1","0.0","1","8","1"],["2013-2-8 13:00:00","5.0","8","1","0.0","1","8","1"],["2013-2-8 14:00:00","6.2","8","1","0.0","1","8","1"],["2013-2-8 15:00:00","6.0","8","1","0.0","1","8","1"],["2013-2-8 16:00:00","5.9","8","1","0.0","1","8","1"]],"error":"","command":"SELECT * FROM TOKYO"}],"status":"completed"}

日本語列名がコードポイントになってしまっていますが…
RESTのツールで見るとこんな感じです。

他にもデータのロードなど様々なRSET APIが用意されているのでボチボチ遊んでみようと思います。

参考URL
IBM Db2 Warehouse on Cloud REST API Version 3
https://developer.ibm.com/static/site-id/85/api/db2whc-v3
Query Cloud Db2 Using REST APIs
http://www.db2dean.com/Previous/Db2RESTCloud.html