Web アプリ素人が Domino 12.0.2 の新機能である Domino REST API（Project KEEP）を怖いもの見たさで触ってみた体験レポートの #5 です。
前回は郵便番号マスタ DB を Domino REST API に設定しました。今回はその設定のテストを行います。
テストは、Swagger UI を使って実施します。まずは、WEB ブラウザから Domino REST API のトップページにアクセスし、[OpenAPI v3] をクリックして、Swagger UI を起動します。
認証トークンの取得
Swagger UI を起動したら、[authentication] セクションの『/auth』API を開きます。この API は、サーバにログインして認証トークン（JWT）を取得します。具体的には、ユーザ名とパスワードを Request body 内の JSON にセットして POST すると、JWT を含む JSON が取得できます。
Resuest body の Examples の枠内にサンプルの JSON が表示されているのでパスワードとユーザ名を入力します。
入力が完了したら、[Excecute] ボタンをクリックします。結果は、Responses の Server Response、Response body に JSON が返されます。
bearer の値が認証トークンとなりますので、これをクリップボードにコピーします。Swagger UI 上部の [Authorize] ボタンをクリックし、Value 欄に認証トークンをペーストして、認証します。
これで、テスト準備完了です。
郵便番号検索のテスト
いよいよ、前回設定した API をテストします。
Swagger UI の [data] セクションの /query を開きます。説明に「Send a DQL query and get JSON documents back」とあるので、DQL を送信して検索し、文書を JSON で取得する API のようです。
まずはパラメータを確認しましょう。
必須のパラメータは２つです。dataScope には、事前に定義したスコープ名 "zipscope" を入力します。action は、"execute" のままでよさそうです。
続いて、Request body の設定です。検索するのですから、query に条件を設定するのは当たり前といえます。サンプルを以下の通り、修正します。
| "query": "form = 'zip' and zipcode = '6810002'", |
実行すると次のような結果が返ってきました。ヒットした件数は表示されているのですが、肝心の文書の内容がありません。
ここで行き詰ったので、HCL テクニカルサポートに問い合わせして、原因を教えていただきました。問題は下記の２点でした。
1. デザインカタログが有効になっていない
/query API は、Swagger UI にも記述がある通り、DQL で検索します。DQL を使用するには、デザインカタログを有効にする必要があるそうです。
以下のサーバコマンドで、デザインカタログを有効にしました。
- load updall Home\zipcode.nsf -e
DQL に関してはこれまで経験がなかったのですが、利用するのにこんな条件があるとは知りませんでした。DQL に関しては、追って調査したいと思います...
2. mode は "default" で
Examples では、mode が "dql" となっています。これを "default" と変更すると動くとのことです。個人的には、"dql" の方が正しいような気がするのですが...
いずれ、Examples か仕様が修正されるのでしょう...
ちなみに、Request Body に設定する JSON の仕様については、Swagger UI 内にドキュメントはないそうです。設定内容に不明な点があれば、HCL テクニカルサポートに問い合わせるしかないようです。
改めてテスト
テクニカルサポートから指摘いただいた点を修正のうえ、改めてテストしたところ、ヒットした文書の情報が正常に返されました。結果の JSON は以下の通りです。
住所などの返される項目は、スキーマで設定した項目になっていて、文書内の全フィールドが返されるわけではないようです。
これで当初計画した『リクエスト時に郵便番号を渡し、その郵便番号の住所を含む JSON を返す』ができました。
最後に、Request body の Examples なのですが、無用な項目や無用な項目が含まれていそうです。そこで、順に項目を削除しながら、必須の項目を探ってみました。結果、次の項目があれば検索が実行されることを確認しました。
|
{ "mode": "default", "query": "form = 'zip' and zipcode = '6810002'" } |
このあたりも API の仕様にあたると思いますので、Swagger UI 内にドキュメントがあればありがたいですね。
| 前回 | Project KEEP 体験 | 次回 |
0 件のコメント:
コメントを投稿