Domino のデータサービスを試して見たい方への簡単なガイダンスです

1. RESTサービスのプレイブック
加藤満
Domino アクセスサービスを使用した

2. この資料について
この資料では、IBM (Lotus) Dominoで利用できるDominoアクセスサービ
ス(以降DAS)を理解するための実践的なガイダンスです。
 動作環境
– Notes/Domino 8.5.3 FP5 UpgradePack1 適用
– Notes/Domino 9 Social Edition

3. DAS設定の3つのステップ
※8.5.3 でDASを利用するにはUpgradePack1が適用されていることが前提になります。
1. Domino Directory 内のサーバー文書に対しての設定
2. データ交換する対象のデータベースの設定
3. データ交換する対象のビューの設定
※DASでできること
• サーバー上のデータベースのリストを読み込む
• 特定のデータベースのビューとフォルダーのリストを読み込む
• 特定のビューまたはフォルダーの設計を読み込む
• 特定のビューまたはフォルダーのエントリーを読み込む
• 文書を作成、読み込む、更新、削除

4. Domino Directory の設定
 ドミノサーバー文書
– 「インターネットプロトコル」ー「Domino Web Engine」タブ
• 「Domino アクセスサービス」セクションの有効なサービスにアルファベットの
「Data」を入力
※この項目はUpgradePack1が適用されていないドミノサーバーでは無効です
※別途「インターネットサイト」文書を作成してWebサイトを構築している場合は、「設定」タブ
にDomino アクセスサービスのセクションがあります

5. Domino Directory の設定(続き）
– サーバー文書を保存した後、Domino サーバーを再起動するか、次のコン
ソールコマンドを入力
• tell http refresh
以上でDomino サーバー上の設定は完了です。
DASが正常に動作するかを確認するには、
http://{ホスト名}/api/data のURLを
ブラウザに入力します。
右のように、ドミノサーバー上のデータベース
の一覧がJSON形式で表示さればOKです。
※ダブルバイト（漢字）はUNICODE

6. データ交換する対象のデータベースの設定
 データベースプロパティの最後のタブ
– Lotus Domino データサービスを許可のプロパティ
• なし
• ビューのみ
• ビューと文書
ここでは「ビューと文書」を
選択します。

7. データ交換する対象のビューの設定
 ビュープロパティでのデータサービスを許可のプロパティ
– Lotus Domino データサービスの操作を許可にチェック

8. ビューコレクションリソース
 特定のデータベース内のビューとフォルダーのリスト取得のURI
– http://{ホスト}/{データベース}/api/data/collections
– @title: ビューまたはフォルダーのタイトル
– @folder: フォルダーの場合「true」
– @unid: ビューまたはフォルダーのユニバーサルID(UNID)

9. ビュー設計リソース
 ビューおよびフォルダーの設計取得のURI
– http://{ホスト}/{データベー
ス}/api/data/collections/unid/{unid}/design
@name: 列のプログラム名
@titile: 列ヘッダータイトル
@width: 列の幅
@field: 「true」は文書内のフィールドを参照、
「false」は計算結果
次のURIでも同様のものが取得可能
http://{ホスト}/{データベー
ス}/api/data/collections/name/{ビュー
名}/design

10. ビューエントリーリソース
 ビューおよびフォルダーのエントリのリスト取得URI
– http://{ホスト}/{データベース}/api/data/collections/unid/{unid}
@href: このビューエントリのURI
@link: 対象となる文書のURI
@unid: 文書のユニバーサルID(UNID)
列に対する値: 列のプログラム名とそれ
に対応する値

11. ビューエントリーリソース(続き)
 デフォルトのURIでは取得するコンテンツの範囲は10個(0-9の範囲)
– サンプルデータベースでは300文書のうち10文書分が表示されている
 次の10エントリを取得するには
http://{ホスト}/{データベー
ス}/api/data/collections/unid/{unid}?ps=10&page=1
– 上記の例での「ps」は取得するページのサイズを10とし、ページ番号1ペー
ジより(0ページ目から開始するので実質２ページ目)

12. ビューエントリーリソース(続き)
 その他の主要なクエリーパラメーター
名前型オプ
ション
説明
start int Yes エントリの開始番号を指定（デフォルトは0で一番最初
count int Yes 返すエントリーの数を指定。デフォルトは10。
si int Yes エントリの開始番号を指定（デフォルトは0）
ps int Yes ページのサイズ
page int Yes ページ番号
search string Yes 全文検索クエリーで合致した文書のみを返す。（全文索引が作成されている
場合のみ）
searchmaxdocs int Yes 全検索クエリーで返す文書の数
sortcolumn string Yes 列のソートされたエントリーを返す
sortorder string Yes ソート順を指定。「ascending」「descending」
startkeys string Yes ソートされたエントリで開始をを指定したエントリから情報を返す
keys string Yes 指定したキーに合致したエントリーを返す。
例）?sortcolumn=Title&sortorder=ascending&keys=Document1
expandlevel int Yes 指定した階層のインデントレベルをもつエントリを返す

13. 文書リソース
 文書取得URI
– http://{ホスト}/{データベース}/api/data/documents/unid/{unid}
@href: この文書のURI
@unid: 文書のユニバーサルID(UNID)
@form: 文書作成に使用される
フォーム名
文書アイテムに対するフォールド名と
その値

14. REST を使用したノーツ文書のCRUD
 REST Web サービスのコンシューマー（クライアント）側へノーツ文書
内の情報を他システムへ提供をする場合は、これまで見てきた方法を使
用する。
 コンシューマー側から、ノーツ文書内に情報を作成したり更新するには、
コンシューマー側でプログラムを用意する必要がある。
– 言語はプラットフォームによるがJava言語がもっとも標準
 CRUD
– 更新：PUT
– 作成：POST
– 読み取り：GET
– 削除：DELETE
以降でCRUDを行なうのにすべてプログラミングするのは大変なので、ここ
では「Poster」というFireFoxのアドオンツールを使用して検証する

15. Poster
 Posterのインストール
– http://addons.mozilla.org/ja/firefox/addon/poster/
– インストール後、ツールメニューの下に起動のメニュー

16. Poster
 Posterの起動

17. Posterによるノーツ文書読み込み
 これまでのRESTの操作で使用してきたURIを画面のURLに入力し、
「GET」ボタンをクリック。
– データベースアクセスに認証が必要な場合は、「User Auth」にユーザー名
とそのHTTPパスワードを入力

18. Posterによるノーツ文書読み込み
 アクセスが成功するとステータス200 が帰り、JSON形式の情報がレス
ポンスとして返ってきます。

19. Posterによるノーツ文書読み込み
 既存の文書リソースでビューにある一番先頭の文書を取得する次のURI
を入力します。
– http://{ホスト
名}/Employees.nsf/api/data/documents/unid/073F4DF555D4983549
257C8D00157A3B

20. Posterによるノーツ文書更新
 前のページと同じURIを用いて、今度は更新（PUT）を実行します。
– 前のページで返ってきた内容から＠xxxxx をのぞくフィールドと値の部分
をコピーし、年齢（Age）の値を50に変更し、Content to Send に指定しま
す。
※Content Type:
application/json
の指定は必須です。
※今回更新したい内容はAgeだ
けですが、他のフィールドも指
定しなければなりません。指定
しない場合は、フィールドがな
くなりますので要注意です。
その為、ノーツ文書の更新は、
既存の文書内のフィールドを読
み取ってから、すべてのフィー
ルドに対して新たに値をセット
するプログラミングが必要です。

21. Posterによるノーツ文書更新
 ステータスが200で、成功したのを確認し、ノーツ文書が正しく変更さ
れているか確認してください。

22. Posterによるノーツ文書新規作成
 続いて、ノーツ文書を新規作成します。新規追加するフィールドとその値は、
Content to Send に残っている内容に少し手を加えたものにします。
– Age、Name、AlterNameを下の赤字のように変更します。
{
"Age”:13,
"AlterName":”Katsuo Isono",
"Gender":"u5973",
"PhoneCarrier":"u30C9u30B3u30E2",
"Name":”Katsuo Isono",
"CellPhone":"090-2753-7590",
"BloodType":"ABu578B",
"Married":"u672Au5A5A",
"Prefecture":"u6771u4EACu90FD",
"Email":"ishida_manami@example.com",
"Birthday":"1982-01-22T15:00:00Z",
"Comment":"u5DE6u30EBu30FCu30FBu5225u53E3u6D3E"
}
 URLを次のようにし、「POST」ボタンをクリックします。
– http://{ホスト
名}/Employees.nsf/api/data/documents?form=Employee&computewithfor
m=true

23. Posterによるノーツ文書新規作成
 ステータスが201になって成功したことを確認します。
 ノーツクライアントに戻って、一覧ビューの一番最後に今回のデータが追加されたの
を確認してください。

24. Posterによるノーツ文書の削除
 先ほど作成した文書を削除しますが、文書を特定するためのステップと
削除のステップが必要です。
 文書の特定にはUNIDを知る必要がありますが、ここではsearchパラ
メーターでKatsuo Isonoを探します。（Katsuo Isonoという言葉が一
意でユニークであることが前提）
– http://{ホスト名}/Employees.nsf/api/data/documents?search=Katsuo
Isono

25. Posterによるノーツ文書の削除
 返ってきた内容の中のUNIDを使用してURIを次のように指定します。
– http://{ホスト名}/Employees.nsf/api/data/documents/unid/{前ページ
で分かったUNID}
 DELETE の選択と、右の丸いボタンをクリックします。

26. Posterによるノーツ文書の削除
 返ってきた内容の中のUNIDを使用してURIを次のように指定します。
– http://{ホスト名}/Employees.nsf/api/data/documents/unid/{unid}
 DELETE の選択と、右の丸いボタンをクリック。

27. データ交換のユーザー認証
 RESTサービス使用の際のユーザー認証には
– DominoサーバーへのBasic 認証
– セッション認証
の両方をサポート