【入門】GridDB Cloud にPostmanを使ってWeb APIで触れてみよう！

記事「【入門】GridDB Cloudにcurlを使ってWeb APIで触れてみよう！)」では、ビッグデータ・IoT向けデータベース GridDB をDB as a Serviceとして提供されるマネージドサービスである GridDB Cloud の無料トライアル を入手し、Web APIでデータ登録・確認をおこなうまでの一連の手順について紹介しました。そこでは、Web APIの実行と確認 (疎通確認)には、URLシンタックスを用いてファイルを送信または受信するcurlコマンドを用いました。しかし、curlコマンドは、手軽にさまざまなプロトコルに対応したデータを転送することができたりして便利ですが、コマンドラインツールなので生産性はあまりよくないと言えます。 Postmanは、GUIでどのようなリクエストをおこなうか簡単に設定できリクエスト可能な便利なツールです。 今回、curlコマンドではなく、Postmanを用いた GridDB CloudのWeb APIの実行と確認（疎通確認）の一連の手順について、はじめからていねいにまとめてご紹介します。また、Postmanのインストールから使い方までPostmanの詳細についても詳しく説明していくので、Postmanを初めて使う方にも参考になると思います。 本記事の流れは次の通りです。 　 - 事前準備 - 運用管理GUIへのログイン - Postmanインストールの入手とインストール - WebAPIの実行と確認 なお、本記事は、記事「【入門】GridDB Cloudにcurlを使ってWeb APIで触れてみよう！)」で、curlコマンドを用いて説明している「Web APIの実行と確認（疎通確認）」の内容をcurlコマンドを用いる代わりにPostmanを用いて説明したものとなります。 よって、GridDB Cloudの「【入門】GridDB Cloudにcurlを使ってWeb APIで触れてみよう！)」の「事前準備」、「運用管理GUIへのログイン」を参照願います。 今回、Postmanをインストールしたデバイスの仕様とWindowsの仕様は次の通りです。 プロセッサ Intel(R) COre(TM) i5-6300U CPU @ 2.40GHz 2.50DHz 実装RAM 8.00 GB システムの種類 64 ビット オペレーティング システム、x64 ベース　プロセッサ- エディション Windows 10 Pro 事前準備 事前準備は、GridDB Cloudのトライアルの入手です。 記事「【入門】GridDB Cloudにcurlを使ってWeb APIで触れてみよう！)」の「事前準備」を参照してください。 運用管理GUIへのログイン ブラウザで電子メールでが送付されてきたGridDB CloudサービスのURLを開き、運用管理GUIへのログインします。 記事「【入門】GridDB Cloudにcurlを使ってWeb APIで触れてみよう！)」の「運用管理GUIへのログイン」を参照参照してください。 Postmanの入手とインストール 次に、Postmanを入手し、インストールします。 まずは、公式ページのダウンロードページ Download Postman からダウンロードします。 「Download the App」を左マウスボタンでクリックすると「Windows 32-bit」と「Windows 64-bit」の選択ができるようになるので,選択します。今回のデバイスの仕様は、「64 ビット オペレーティング システム」なので、「Windows 64-bit」を選択します。 Postman-win64-8.11.1-Setup.exe のダウンロートが開始されます。 ダウンロードされたインストーラ Postman-win64-8.11.1-Setup.exe をダブルクリックすると、次のような画面が表示されインストールの実行が開始されます。 すると、次のようなアカウント作成画面が表示されます。今回は、「Create Free Accout」を選択しました。「×」で閉じてスキップしての問題なく使用できるようです。 メールアドレスの登録もしくはGoogleアカウントで、アカウントを作成できます。今回はメールアドレス、ユーザ名とパスワードの登録でアカウントを作成しました。 「Continue」をクリックします。 これでインストールは完了です。 WebAPIの実行と確認 接続情報の確認 Web API のベースURLとクラスタ名を確認します。 詳細は、記事「【入門】GridDB Cloudにcurlを使ってWeb APIで触れてみよう！)」の「接続情報の確認」を参照してください。 Web API のベースURLの確認 今回のWeb API のベースURLはhttps://cloud1.griddb.com/trial001/griddb/v2/ とします。 クラスタ名の確認 今回のクラスタ名はgs_clustertrial001とします。 データベースユーザの作成 次にデータベースユーザを作成します。運用管理GUIで、「セキュリティ」画面に遷移し、「データベースユーザの作成」ボタンをクリックして、任意のユーザ名とパスワードを設定し、「作成」ボタンをクリックします。 ここでは、ユーザ名：「test_user1」、パスワード：「test_user1」とします。 詳細は、記事「【入門】GridDB Cloudにcurlを使ってWeb APIで触れてみよう！)」の「データベースユーザの作成」を参照してください。 Web APIの実行 では、本題のPostmanを用いたWeb APIの実行（疎通確認）に入ります。今回のWeb APIの実行は次のような流れでおこないます。 データベース(デフォルトデータベースpublic)への接続の確認 コンテナ (コンテナ名:point01) を作成TIMESTAMP, BOOL, DOUBLEの3カラムで構成 コンテナ一覧を取得 作成したコンテナの情報を取得 ロウにデータを登録　"2021-06-27T10:30:00.000Z", false, "100" "2021-06-28T10:30:00.000Z", false, "100" 最大100件で、2021年6月28日 4時30分以降のデータを取得するという条件でロウの取得 TQL実行 "2021-06-28T10:30:00.000Z"のロウを削除 SQL SELECTを文実行 コンテナ (コンテナ名:point01) を削除 GridDB Cloud が提供するWeb APIの仕様の詳細については「GridDB Web APIリファレンス」を参照してください。 Postmanの起動 PostmanでWeb APIの実行（疎通確認）するために、まずは、Postmanを起動します。Postmanを起動すると次のような画面が表示されます。 もし、表示されない場合は、「Home」をクリックしてください。 「Get started with Postman」の「Started with something new」の「Create New > 」をクリックします。 「Create New」ウィンドウで「HTTP Request」をクリックしてください。 次のようなウィンドウが表示されます。 上部のバーにはリクエストメソッド（デフォルトでは GET）、その右横にはリクエストURLを入力します。 次のセクション(Params/Authorization/Headers/Body/Pre-request Script/Tests/Setting)には7つのタブがあります。 Params：リクエストに引数がある場合、引数を指定する Authorization：Basic AuthやOAuth2など、リクエストの認証方法を指定する Headers：Authorizationやcontent-typeなど、リクエストヘッダーを指定する Body：PostやPUTなどの場合に指定するリクエストボディーを指定する Pre-request Script：リクエスト前に実行するJavaScriptコードを指定する Tests：Postman API リクエストのテストスクリプトをJavaScriptコードで指定する Setting：リクエストに関する設定を指定する 準備ができたら、Sendボタンをクリックしてリクエストを開始します。 下のボタンのセクション(Response)には、レスポンスの情報（status、time、size）が表示されます。 リクエストヘッダ GridDBのWeb APIへの接続には次のAuthorizationとContent-Typeのヘッダが必須です。これらは、すべてのリクエストに付与します。 ヘッダ 説明 Authorization ベーシック認証(基本認証)でGridDBへアクセスするユーザとパスワードを指定します。今回はユーザ名：test_user1とパスワード：test_user1となります Content-Type 「application/json; charset=UTF-8」を指定します Authorization (認証) Postmanは多くの認証方式をサポートしています。今回は、ヘッダーで設定するベーシック認証(基本認証)を使います。 セクション「Params/Authorization/Headers/Body/Pre-request Script/Tests/Setting)」からタブ「Authorization」をクリックします。 「Inherit」を左クリックし、プルダウンメニューを表示し「Basic Auth」を選択します。 「データベースユーザの作成」で作成したユーザ名とパスワードを入力します。ここでは、「Username」に「test_user1」、「Password」に「test_user1」を入力します。 Content-Type (コンテンツタイプ) 「Headers」を左クリックします。 「Key」に「Content-Type」、「Value」に「application/json; charset=UTF-8」を入力します。 データベース接続確認 まずは、手始めにデータベースへの接続確認をしてみましょう。データベース接続確認のHTTPトメソッドとリクエストURLは次の通りです。 GET ベースURL + クラスタ名/dbs/データベース名/containers/checkConnection 今回の場合は、クラスタ名：「gs_clustertrial001」、データベース名：「public」となります。 よって、「Enter request」に次のように入力します。 https://cloud1.griddb.com/trial001/griddb/v2/gs_clustertrial001/dbs/public/checkConnection 「Send」をクリックします。 次のようにHTTPレスポンスのステータスが200になっていれば成功です。 コンテナの作成 次は、TIMESTAMP型, BOOL型, DOUBLE型の3カラムで構成される時系列コンテナpoint01を作成します。 コンテナの作成のHTTPトメソッドとリクエストURLは次の通りです。 POST ベースURL + クラスタ名/dbs/データベース名/containers よって、POSTをチョイスし、「Enter request」に次のように入力します。 https://cloud1.griddb.com/trial001/griddb/v2/gs_clustertrial001/dbs/public/containers ここでは、TIMESTAMP型, BOOL型, DOUBLE型の3カラムで構成される時系列コンテナpoint01を作成しますので、送信するリクエストボディは次の通りです。 { "container_name" : "point01", "container_type" : "TIME_SERIES", "rowkey" : true, "columns" : [ {"name": "timestamp", "type": "TIMESTAMP"}, {"name": "active", "type": "BOOL"}, {"name": "voltage", "type": "DOUBLE"} ] } 画面で、 「Body」 を選択します。 そうするとデフォルトが「none」となっているので、「raw」を選択してください。 入力エリアが表れ、デフォルトの「JSON」となります。 今回の送信するリクエストボディはJSON形式なので、そのまま送信するリクエストボディを入力します。 そして、「Send」をクリックします。 「GridDB Cloud クイックスタートガイド　5.2 コンテナの作成」では、「HTTPレスポンスのステータスが200(OK)になっていれば成功です。」と記述されていますが、実際は、HTTPレスポンスのステータスが201になっていれば成功です。 コンテナ一覧取得 コンテナ一覧取得のHTTPトメソッドとリクエストURLは次の通りです。 GET ベースURL + クラスタ名/dbs/データベース名/containers/ よって、GETをチョイスし、「Enter request」に次のように入力します。 https://cloud1.griddb.com/trial001/griddb/v2/gs_clustertrial001/dbs/public/containers?limit=10&offset=0 「Body」は「none」を指定します。 「Send」をクリックします。 「GridDB Web APIリファレンス 1.7 コンテナ一覧取得」 では、「limitで0を指定した場合は、条件に合致するすべてのロウが返ります。」と記載されていますが、limit 0を指定した場合、取得数が0になるため、コンテナ名は取得されないようです。 コンテナ一覧取得が実行されました。 コンテナ情報取得 コンテナやテーブルの情報を取得してみましょう。 コンテナ情報取得のHTTPトメソッドとリクエストURLは次の通りです。 GET ベースURL + クラスタ名/dbs/データベース名/containers/コンテナ名/info よって、GETをチョイスし、「Enter request」に次のように入力します。 https://cloud1.griddb.com/trial001/griddb/v2/gs_clustertrial001/dbs/public/containers/point01/info 「Send」をクリックします。 レスポンスボディに次のようなコンテナ情報が取得でき、HTTPレスポンスのステータスが200になっていれば成功です。 { "container_name":"point01", "container_type":"TIME_SERIES", "rowkey":true, "columns":[ { "name":"timestamp", "type":"TIMESTAMP", "index":[] }, { "name":"active", "type":"BOOL", "index":[] }, { "name":"voltage", "type":"DOUBLE", "index":[] } ] } ロウの登録 次に、作成したコンテナpoint01にロウを登録します。 登録するロウは、JSON形式で指定します。ひとつのコンテナに複数のロウを登録することもできます。 ロウの登録ののHTTPトメソッドとリクエストURLは次の通りです。 PUT ベースURL + クラスタ名/dbs//データベース名/containers/コンテナ名/rows 今回、例として次のリクエストボディを送信します。 [ ["2021-06-27T10:30:00.000Z", false, "100"], ["2021-06-28T10:30:00.000Z", false, "100"] ] よって、PUTをチョイスし、「Enter request」に次のように入力します。 https://cloud1.griddb.com/trial001/griddb/v2/gs_clustertrial001/dbs/public/containers/point01/rows 今回はHTTPレスポンスのステータスが200になっていて、レスポンスボディが {"count":2} のようになっていれば成功です。 ロウの取得 次に、コンテナpoint01に登録したロウを取得します。 ロウの取得のHTTPトメソッドとリクエストURLは次の通りです。 POST ベースURL + クラスタ名/dbs//データベース名/containers/コンテナ名/rows よって、PUTをチョイスし、「Enter request」に次のように入力します。 https://cloud1.griddb.com/trial001/griddb/v2/gs_clustertrial001/dbs/public/containers/point01/rows 今回、取得対象は最大100件で、2021年6月28日 4時30分以降のデータを取得するという条件でロウの取得をします。 timestampは時刻型なので、TQLの時刻型演算関数 TIMESTAMP(str)で時刻の文字列表現を時刻型に変換して指定します。 リクエストボディは次の通りです。 { "limit" : 100, "condition" : "timestamp >= TIMESTAMP('2021-06-28T04:30:00.000Z')" } 実行すると次のような画面になります。 TQL実行 次にTQL文を実行します。 TQL実行のHTTPトメソッドとリクエストURLは次の通りです。 POST ベースURL + クラスタ名/dbs/データベース名/tql よって、POSTをチョイスし、「Enter request」に次のように入力します。 https://cloud1.griddb.com/trial001/griddb/v2/gs_clustertrial001/dbs/public/tql 今回、コンテナpoint01に対して TQL文 select * を実行します。 [ {"name" : "point01", "stmt" : "select * "} ] ロウ削除 ロウ削除のHTTPトメソッドとリクエストURLは次の通りです。 DELETE ベースURL + クラスタ名/dbs//データベース名/containers//コンテナ名/rows ロウキー "2021-06-28T10:30:00.000Z"を指定してロウを削除してみます。 ["2021-06-28T10:30:00.000Z] よって、DELETEをチョイスし、「Enter request」に次のように入力します。 https://cloud1.griddb.com/trial001/griddb/v2/gs_clustertrial001/dbs/public/containers/point01/rows HTTPレスポンスのステータスが204になっていれば成功です。 SQL SELECT文実行 実際、ロウキー "2021-06-28T10:30:00.000Z"のロウが削除されたか確認するために、SQL SELECT文 "select * from point01"を実行してみます。 SQL SELECT文実行のHTTPトメソッドとリクエストURLは次の通りです。 POST ベースURL + クラスタ名/dbs/データベース名/sql/select よって、POSTをチョイスし、「Enter request」に次のように入力します。 https://cloud1.griddb.com/trial001/griddb/v2/gs_clustertrial001/dbs/public/sql SQL SELECT文を次のようなJSON形式で指定します。 [ {"type" : "sql-select", "stmt" : "select * from point01"} ] HTTPレスポンスのステータスが200になっていれば成功です。 コンテナ削除 では、最後に今回Web APIの疎通確認するために作成したコンテナ (コンテナ名:point01)を削除します。 コンテナ削除のHTTPトメソッドとリクエストURLは次の通りです。 DELETE ベースURL + クラスタ名/dbs/データベース名/containers よって、DELETEをチョイスし、Enter requestに次のように入力します。 https://cloud1.griddb.com/trial001/griddb/v2/gs_clustertrial001/dbs/public/containers 削除するコンテナ名として次のリクエストボディを 送信します。 ["point01"] HTTPレスポンスのステータスが204になっていれば成功です。しかし、GridDB Cloud v1.1では、削除するコンテナ名の指定がタイプミスで誤っていたりして存在しないコンテナを指定しても、現状HTTPレスポンスのステータスが204になってしまうようです。注意が必要です。 さいごに ビッグデータ・IoT向けデータベース GridDB をDB as a Serviceとして提供されるマネージドサービスである GridDB Cloud の無料トライアルを入手し、Postmanを用いて、Web APIでデータ登録・確認をおこなう一連の動作を確かめました。 今回の動作確認に用いたPostman の基本機能はほんの一部です。 Postmanには今回用いた機能以外、便利な機能がまだたくさんあります。 なお、記述について誤りがあったり、気になることがあれば、編集リクエストやコメントでフィードバックしていただけると助かります。