2020年9月22日火曜日

REST API で取得した値を Volt の表へセットする

先日のノーツコンソーシアムのアプリ開発研究会で取り組んだ、Web API で取得したjson 配列の値を Volt のフォームに追加した表へセットする方法についてご紹介します。

使用する Web API は Google のジオコーディング API です。この API を使うには API キーが必要なのですが、キーを入手する方法についてはこのあたりのページが参考になるかと思います。

APIキーを入手できたら、次のURLへGET要求します。

https://maps.googleapis.com/maps/api/geocode/json?language=ja&latlng=<緯度>,<経度>&key=<APIキー>

※出力フォーマットとして json を指定します
※表示する住所を日本語にしたいので language=ja を追加しています

仮に、取得した位置情報が自由が丘駅ホーム、入手したAPIキーが "abcd1234" とすると、URLは次のようになります。

https://maps.googleapis.com/maps/api/geocode/json?latlng=35.60869829275,139.66870970056&key=abcd1234

まっとうなAPIキーをセットしたURLの場合、ブラウザのアドレス欄へ指定すると、REST API のレスポンスが表示されます(下図)。

この json から住所を取得したいのですが、位置情報から取得できる住所が複数の場合があります。上の図では縦スクロールバーのサイズから察するとおり複数の住所が取得できました。

このような複数の値が戻ってくることが分かっている値を Volt のフォーム上に表示したい場合、表を使用すると便利です。戻り値の数に応じて行数が自動で変化しますので、戻り値の数が10あれば、表に10行の住所を表示してくれます。

さて今回 json から取得する値は、results という配列にある formatted_address の値とします。

formatted_address をVolt の表の列に割り当てていきます。

今回も HCL社が用意している Application Sandbox を利用してアプリケーションを作成していきます。こちらはライセンスを持っていない方でもアカウント登録さえ行えば利用できますので、Domino Volt での開発を試してみたい方にお勧めします。

開発の流れは次のとおりです。
  1. 新規アプリケーションの作成
  2. 表を追加
  3. 列を追加
  4. イベントとサービス構成を追加
では始めます。

Sandbox にログイン後 Volt の初期画面から「新規アプリケーションの作成」をクリックします。「白紙から」を選択して[次へ]ボタンをクリックします。アプリケーション名を「住所リスト」として[作成]ボタンをクリックします。

ページに表を追加します。画面左側のパレットから「特殊」にある「表」をクリックします(ダブルクリックすると複数の表が追加されますのでシングルクリックしましょう)。するとページ内に表が追加されると思います。表をページ内の任意の場所へ追加したい場合は、「特殊」にある「表」をドラッグして、ページ内の任意の場所へドロップするほうが便利かもしれません。

この表へ列を追加します。今回は住所だけを表示したいので1列だけ追加します。画面右側の「アウトライン」から「ページ1」の左にある > をクリックすると下に表示される「表」をクリックします。画面左側のパレットから「フィールド」にある「単一行エントリー」をクリックします。すると表に単一行エントリーが追加されると思います。表内に追加された単一行エントリーで太字で「単一行エントリー」と表示されている文字をクリックすると文字を編集できますので、これを「住所」と書き換えます。この「住所」が列のタイトルとして表示されます。

列を追加したら、ここで列幅を(デフォルトは「10文字」と狭いので)調整します。列幅は表のプロパティーから編集できます。画面右側の「アウトライン」から「ページ1」をクリックします。そして画面中央の表の右上に表示される歯車アイコン(カーソルを持っていくと「表プロパティーの編集」と表示されます)をクリックします。

「「表」プロパティの編集」ダイアログが表示されたら、その上部にあるメニューから「拡張」をクリックして、「オプション:」にある住所列の「幅(概略値)」の値を 500 までの適当な数値に書き換えます。書き換えたら[OK]ボタンをクリックしてダイアログを閉じます。

次にフォームへイベントを追加します。画面上部のメニューから「イベント」をクリックして、画面左側の「フォーム・イベント」欄の下にある[追加]というリンクをクリックします。

するとイベントのリストが表示されます。ここから onShow をクリックします。

すると onShow イベントの編集画面が表示されます。「事前定義アクション」にある「サービスの呼び出し」にチェックを付けます。すると「サービス構成の追加/編集」というリンクが現れるので、これをクリックします。

「サービス構成」というダイアログが表示されますので、ここから「API のレスポンス」と「フォーム上のフィールド」の割り当てを設定します。まずは「URLを入力」を選択します。自由が丘の位置情報とAPIキーを含むURLをURL欄へ入力します。ここでURL欄の右側にある歯車アイコンをクリックします。

「サービスの詳細」ダイアログが表示されます。ここではフォーム上のフィールドから取得可能な値をURLの各パラメータへセットしたい場合に、フィールドと紐づけさせたいURLパラメータを指定することができます。今回はURLにある3つのパラメータ「言語(language)、緯度経度(latlng)、,APIキー(key)」はどのフィールドとも紐づけしません。そのため、この画面にある「割り当て可能」についた3つの青いチェックボックスをクリックしてチェックを外した状態にして、[OK]ボタンをクリックします。※下図はチェックを外す前の状態です

「サービス構成」画面に戻ったら、その画面上部にある「3.出力」をクリックします。ここで「2.入力」をスルーするのは、フォーム上のフィールドとURLパラメータを紐づけしないからです。「3.出力」では戻ってきた json の項目("ソース"と呼びます)を、フォーム上のフィールド("ターゲット"と呼びます)へ割り当てます。画面左側の「ソースの選択」から "results" の左にある > をクリックして展開し、"formatted_address" をクリックします。するとクリックした文字が太字に変化します。続いて画面右側の「ターゲットの選択」から”表”の左にある > をクリックして展開し、"住所"をクリックします。こちらもクリックした文字が太字に変わります。"formatted_address" と "住所" の両方が太字になっている状態で、その中間にある[出力の割り当て]ボタンをクリックします。

すると画面下部の「割り当てられている出力」欄へ追加されます(下図)。[OK]ボタンをクリックして「サービス構成」ダイアログを閉じます。




以上で(見た目はさておき...)機能としては完成です。

画面右上にある[保存]ボタンをクリックして、その左にある[プレビュー]をクリックします。すると下図のような感じで表示されると思います。

この表には5行しか表示されておらず、縦のスクロールバーも表示されていませんが、実は戻り値は12個存在しました。表の上でスクロールの操作を行うことで、表示されていない残りの行も見ることができました。

今回は API の実行タイミングを「フォームを表示したとき」としたかったので「フォームのイベント」にサービスを構成しましたが、例えば、フォーム上にボタンを設置して、ボタンをクリックしたタイミングで API を実行したい場合は、今回と同様のサービス構成をボタンの onClick イベントへ追加することになります。

また今回構成したサービスでは「2.入力」をスルーしましたが、フォーム上に緯度経度のフィールドを用意することで、それらの値をURLパラメータに代入するといったサービスにしたい場合は「2.入力」の画面で設定することになります。

【配列の入れ子に注意しましょう】
REST API の戻り値にある配列の値を表へセットする場合、配列の構造に注意が必要です。今回の REST API では対象となりませんでしたが、「配列の中に配列がある」といった構造の場合は「フォームの中に追加した表の内側にさらに表を追加する」といったように、ソースの入れ子構造にあわせてターゲット側も入れ子構造にしなければサービスを構成することができません。しかしながら現状の Volt は入れ子の表を作ることはできるものの表をそれっぽく表示することができません。そのため取得した値を表示することができないのです。この問題をサポートへ報告したところ回避する手段を教えてもらうことができましたので、機会があれば紹介したいと思います。

0 件のコメント:

コメントを投稿