当ブログに掲載しているサンプルは、すべて利用者の自己責任という形でお願いします。
ただし、明らかな不具合がある場合、ご連絡いただければ、訂正記事を出します。
また、こちらのサンプルは、別のサイト等への公開、転載は一切禁止しています。
どうしてもと言う場合は、筆者にあらかじめご連絡ください。
記事そのもののリンクについてはご自由に行っていただいてよいです。

テクてく Lotus 技術者 Slack に参加しよう!

2013年6月23日日曜日

Notes/Domino でREST APIを使ってみよう-後半-

今日は、REST APIの後半の話です。
前半では、Domino データサービスの設定方法や、ブラウザからREST APIを利用した場合の結果についてみてみました。
後半は、Notesアプリケーションにそれを応用してみます。


では、記事に入る前にこちらをクリックしましょう。
にほんブログ村 IT技術ブログへ


Dominoデータサービスを設定したことにより、Notesアプリケーションは、JavaやJavaScriptを使ったアプリケーションから利用することができます。
また、Notes/DominoはJavaやJavaScriptを利用することができます。
ということは、NotesアプリケーションでREST APIを使うことができるということになります。

利用するデータは前半でも紹介した「郵便番号辞書アプリ」です。
これは、すでにDominoデータサービスが利用できるようにしてあります。

このアプリからデータを検索するというサンプルアプリケーションを作成してみましょう。
サンプルアプリケーションの内容は、
「7桁の郵便番号を入力して、[検索]ボタンをクリックすると、郵便番号辞書アプリから該当する住所データを取得して、都道府県名、市区町村名、町域名を画面上のフィールドにセットする」
というものです。
サンプルアプリケーションはXPagesで作成します。

1.フォームを作成する
 下図のようなフォームを作成します。
 フォーム名は「AddressForm」としておきます。
 フィールド名は下図を参照してください。
検索画面用のフォーム

2.XPageを作成する
 XPagesアプリケーションにしたので、画面を作成します。
 「home」(任意です)という名前で作成します。
 データソースを作成して、1.で作成したフォームを割り当てます。
データソースを作成
データソースをXPage画面にバインドします。
データソースをXPage画面に追加

 ちなみに、このような設定でバインドしてあります。
データバインドコントロールの設定


3.検索用のコードを記述する(SSJS)
 さて、画面が出来上がったので、次に検索用のコードを記述します。
 比較のために、REST APIを使わない場合のものを載せます。
 サーバサイドJavaScript(SSJS)のNotesクラスを使った場合ですね。
郵便番号を検索するためのSSJS
var zip7 = getComponent( "zip71" ).getValue();
 で画面上に入力された郵便番号を取得しています。
 あとは、郵便番号辞書アプリの($All)ビューに対して、getDocumentByKey()メソッドで検索をしています。
 取得した結果をデータソースの各アイテムに渡しています。
 このコードは、画面にボタンを配置して、SSJSのスクリプトを実行するという形で設定してあります。


4.検索用のコードを記述する(CSJS)
 今度は、REST APIを使ってのコードです。
 SSJSと同様にボタンを配置します。ボタンのラベルは「REST APIを使った検索」としておきます。
REST APIによる検索ボタン

 REST APIの呼び出しは、今回はクライアントサイドのJavaScriptとして記述します。
// 送信先
var svn = "http://サーバのhost名";
var dbn = "Xpages/ZipCode.nsf";
var endpoint = "/api/data/collections/unid/D76B3FEBE958BECF49257B8C00037E9D";

// 入力した郵便番号
var skey = document.getElementById( "#{id:zip71}" ).value;

// URLを生成
var url = svn + "/" + dbn + endpoint + "?search=FIELD zip7 CONTAINS " + encodeURI(skey);

// XMLHttpRequestを作成
try {
    xmlhttp = new XMLHttpRequest();
} catch (e){
    // XMLHttpRequestの作成に失敗
}

// REST APIのセットと送信
xmlhttp.onreadystatechange = chkResponse;
xmlhttp.open('GET', url, true);
xmlhttp.setRequestHeader ( "Content-Type","text/xml; charset=utf-8" );
xmlhttp.send();

// REST APIのレスポンスの処理(正常時のみ処理する)
function chkResponse() {
if ( xmlhttp.readyState == 4 && xmlhttp.status == 200 ) {
     var ret = xmlhttp.responseText;
     var obj = JSON.parse( ret );

     document.getElementById( "#{id:prefectures1}" ).value = obj[0]['Prefectures'];
     document.getElementById( "#{id:cities1}" ).value = obj[0]['Cities'];
     document.getElementById( "#{id:address1}" ).value = obj[0]['Address'];
    }
}
07行目で、画面上に入力した郵便番号を取得しています。
10行目で、REST APIとして渡すhttpのURIを生成しています。

19~23行目でREST APIにリクエストを送信していますが、その準備として、12~17行目でXMLHttpRequestを作成しています。

※HTTP通信なので、非同期通信としています(21行目の命令の3つ目の引数・・・trueとすることで、非同期通信になる)。

リクエストを送信することで、Dominoからその結果がJSON形式で返されます。
どのような形で返ってくるかは、前半の最後に紹介した通りです。

25~34行目で、HTTPのレスポンスに対する処理を行っています。
27行目で、レスポンスの受信及びステータスのチェックを行っています。
受信完了(readyState=4)、ステータスがOK(status=200)であれば、正常なので、
その時に郵便番号のセット処理を行っています。

JSON 形式のデータで返ってきているので(28行目)、それをJavaScriptで取り扱える形式にする必要があります。
それが29行目のJSON.parse()という命令です。
これでJavaScriptのObject変数になります。

31~33行目で、画面上のフィールドにセットしています。
DominoからはJSON形式の配列で返ってくるので、obj[0]としています。2番目の['Prefectures']は、項目名を表しています。

実際のサンプル画面はこちら。
郵便番号検索アプリ

郵便番号を入力して、[REST APIを使った検索]ボタンをクリックすると、画面の「都道府県名」「市区町村名」「町域名」に該当する住所が表示されます。

[保存]をクリックすれば、文書に「都道府県名」「市区町村名」「町域名」も一緒に保存されます。

いかがでしょうか?
これでNotes/DominoのデータをREST API経由で、他のシステムと連携もできますし、
逆に、他のシステムのデータをREST API経由でNotesから利用することもできるようになります。

これでNotes/Dominoの活用の幅が広がることになりますので、ぜひチャレンジしてみてください。


では、また・・・



【PR】ノーツ/ドミノに関するお問い合わせは下記まで【PR】
単純なDBのカスタマイズから他アプリケーションとの連携までご要望にお応えします!

Lotus Notes/Domino カスタマイズとセキュリティ強化 - 株式会社エフ

Notes/Domino でREST APIを使ってみよう-前半-

こんばんは。Notes/Domino 9.0 SEが出荷されて、早2カ月が過ぎましたね(ダウンロード版の提供開始から含めると、3カ月かな?)。
クライアントガイドも発売されているので、もう多くの方が触れているのではないかと思います。

私も自宅でばっちりとつかっていますよ(職場の環境は事情により、まだ8.5.3なんですね・・・)。
ちなみに、自宅では、XPages Extension Library Japanの活動だったり、本ブログへの記事投稿のためのテストだったり、という形で利用しています(もちろん、全部仕事です)。

そんな中で、私が注目しているのは、REST APIです。
これも8.5.3 up1から利用できるようになったのですが、折角だからNotes/Domino 9.0 SEで動かしてみたいじゃないですか。
ということで、今日はREST APIについての話です。


本ブログの読者では知らない人はいないと思いますが、本題に入る前に、こちらのボタンをクリックしましょうね。
にほんブログ村 IT技術ブログへ


では、始めましょう。
まず、「Domino データサービス」とは何でしょうか?
  • Dominoサーバ上のNotesアプリケーションへHTTPプロトコルを利用してアクセスするためのサービス
  • サーバ単位、アプリケーション単位、ビュー単位でアクセス制御を可能(文書はアクセスする/しないの二択)
  • データの作成/読み込み/更新/削除(いわゆるCRUD)をサポートしている
  • データフォーマットはJSONである
(参考:テクてく Lotus 技術者夜会 03/16 Lotus Notes/Domino Upgrade Pack とは

・・・Notes/Domino漬けの皆さんには、よくわからないですよね。
ここは、実際に使ってみましょう。

残念ながら、これはDominoサーバが必要になりますので、クライアントしかないという方は、本ブログの画面ショットのみで雰囲気を味わってください。

1.DominoサーバでDominoデータサービスが利用できるように設定する
 ドミノディレクトリのサーバ文書を編集モードで開きます 
Dominoサーバ文書を選択して編集モードで開く
「インターネットプロトコル」タブを開きます
インターネットプロトコルタブを選択する
「Domino Web Engine」タブを開きます
Domino Web Engineタブを選択する
最下層にある「Domino アクセスサービス」まで移動する
 そのセクションにある「有効なサービス」欄に"Data"と入力します。
Dominoアクセスサービス欄にある「有効なサービス」に入力する
[保存して閉じる]アクションをクリックして、サーバ文書を保存します。
 ※ここで、「有効なサービス」欄に直接値を入力しましたが、
  これはドミノディレクトリの設計の不備によるものです。
  詳しくは、Domino Data Service を使うときの設定を参照してください。
  記事では、Domino 8.5.3 up1となっていますが、
  Domino 9.0でも同様の設定が必要だと思います。

 サーバ文書の設定が完了したので、それを反映させます。
 Dominoサーバを再起動・・・といきたいところですが、今回はHTTP関連の修正だったので、
 次のコマンドをサーバコンソールで入力すればOKです。
 tell http refresh
サーバコンソールで「tell http refresh」を入力
これでDominoデータサービスの利用準備ができるようになりました。


2.NotesアプリケーションでDominoデータサービスが利用できるように設定する
 次にDominoデータサービスを利用するNotesアプリケーションの設定を行います。
 実はこれが大事なんです。
 社外秘のデータを取り扱っているようなNotesアプリケーションは
 Dominoデータサービスの適用範囲外にしたいというときに、
 サーバでDominoデータサービスを利用できるようにしてしまっただけで、
 サーバ配下の全アプリケーションがDominoデータサービスの適用範囲になってしまうと、
 困ってしまいます(ACL は当然有効なのですが、やはり 気持ちの良いものではないですよね)。

 では、設定していきましょう。
 まず、Dominoデータサービスの対象にしたいNotesアプリケーションを選択して、
 アプリケーションのプロパティを開きます。
 ここでは、日本郵便のサイトからデータをダウンロードして登録した、
 郵便番号データを格納した「郵便番号辞書」Notesアプリケーションを選択します。
 ※日本郵便のサイトにあるzipデータをダウンロード、解凍してできたCSVの内容を
  ノーツ文書として登録する機能を保有しているものです。
  こんなのもNotes/Dominoでできるんですよ。すごいですね!
郵便番号辞書のプロパティ
一番右側のタブ(詳細タブ)を開きます。
 一番下にある「IBM Domino データサービスを許可」の値を「ビューと文書」に変更します。
「IBM Dominoデータサービスを許可」を変更する
これでデータベース自体の設定が完了しました。
 今度は、ビューの設定を行います。
 Domino DesignerでNotesアプリケーションを開きます。
Domino Designerで郵便番号辞書アプリを開く
今回は、($All)ビューでDominoデータサービスが利用できるようにするので、
 ($All)ビューを開きます。その際、ビューのプロパティも開きます。
 次に、プロパティの右から二番目の「詳細」タブを開きます。
ビュープロパティの詳細タブを開く
「Webアクセス」の中にある「IBM Domino データサービスの操作を許可」にチェックをつけます。
ビューでDominoデータサービスを有効にする
ビューを保存します。
 これで、Notesアプリケーションの設定も完了しました。

3.実際にNotesアプリケーションのデータを見てみる
 Dominoデータサービスが利用できるようになったはずなので、実際のデータを見てみましょう。
 REST APIはJava やJava Script等で利用できるのですが、
 いきなりアプリケーションを作りこむ前に、ブラウザで確認してみましょう。
 そうですね。REST APIはHTTPプロトコルを使っているので、ブラウザ上でデータの確認ができるのです。

 Notesアプリケーションにどのようなビューがあるのかの一覧を表示するURIです。
 http://サーバのhost名/Notesアプリケーションパス名/api/data/collections
 実行結果が下図です。
郵便番号辞書アプリのビュー一覧
「@title」というのがビュー名を表しているのですが、
 日本語文字はUnicodeでエンコードされているので、注意が必要です。
 さきほど、Dominoデータサービスが利用できるように設定した($All)は英語名だけなので、
 どこにあるかわかりますね。

 では、($All)ビューにはどんな文書が含まれているのかを取得するURIです。
 http://サーバのhost名/Notesアプリケーションパス名/api/data/collections/unid/ビューのUNID
 なお、ビューのUNIDは、さきほどのビューの一覧の中に、「@unid」として表記されています。

($All)ビューの文書一覧
ちなみに、Dominoデータサービスの利用を許可していないビューにアクセスしようとしても、
 HTTP 403(閲覧禁止)のエラーになります。

 さらに、今度は文書へアクセスしてみましょう。
 URIはこちらです。
 http://サーバのhost名/Notesアプリケーションパス名/api/data/documents/unid/文書のUNID
 文書のUNIDも、「@unid」として表記されています。
郵便番号辞書アプリの文書の一つ




zip5とかzip7、Prefecturesとかが文書のフィールド名で「:」の後にあるのが、その値です。

と、ここまでは他のサイトでも紹介してありました。
オリジナリティを出すために、もう少し。

文書の検索をしたい場合にどうすればよいか?をやってみましょう。
文書のUNIDを調べるくらいなら、REST APIなんか使わないで、普通にNotesアプリケーション作った方がいいですもんね。
ということで、郵便番号で検索してみましょう。


準備として、Notesアプリケーションに全文索引を作成しておきましょう。
そうしたら、次のURIを入力します。
http://サーバのhost名/Notesアプリケーションパス名/api/data/collections/unid/ビューのUNID?search=検索条件
http://サーバのhost名/Notesアプリケーションパス名/api/data/documents?search=検索条件

上は、ビューでの検索で、下は文書の検索です。

検索条件は全文検索に入力するような形です。
今回の例でいえば、
FIELD zip7 CONTAINS 1030011
です。
zip7は7桁の郵便番号が格納されているフィールド名です。
1030011は検索したい郵便番号です。

ビューでの検索結果

文書の検索結果

ビューの検索は、ビューの列情報も一緒に表示されますが、文書の検索の場合、文書UNIDと文書の更新日しか表示されないですね。
ということで、比べても分かるように、必要な情報がビューに設定してあれば、ビューの検索の方が便利です。


ここまでくれば、アプリケーションへの応用はもう一息ですね。
続きを書きたいところですが、結構難しい話なので、今日はここまでとします。

続きは後日・・・




【PR】ノーツ/ドミノに関するお問い合わせは下記まで【PR】
単純なDBのカスタマイズから他アプリケーションとの連携までご要望にお応えします!

Lotus Notes/Domino カスタマイズとセキュリティ強化 - 株式会社エフ