Dominoアクセスサービスを使用したRESTサービスのプレイブック
27
RESTサービスのプレイブック 加藤 満 Domino アクセスサービスを使用した
-
Upload
mitsuru-katoh -
Category
Technology
-
view
417 -
download
3
description
Domino のデータサービスを試して見たい方への簡単なガイダンスです
Transcript of Dominoアクセスサービスを使用したRESTサービスのプレイブック
RESTサービスのプレイブック
加藤 満
Domino アクセスサービスを使用した
この資料について
この資料では、IBM (Lotus) Dominoで利用できるDominoアクセスサービス(以降DAS)を理解するための実践的なガイダンスです。
動作環境
– Notes/Domino 8.5.3 FP5 UpgradePack1 適用
– Notes/Domino 9 Social Edition
DAS設定の3つのステップ
※8.5.3 でDASを利用するには UpgradePack1が適用されていることが前提になります。
1. Domino Directory 内のサーバー文書に対しての設定
2. データ交換する対象のデータベースの設定
3. データ交換する対象のビューの設定
※DASでできること• サーバー上のデータベースのリストを読み込む
• 特定のデータベースのビューとフォルダーのリストを読み込む
• 特定のビューまたはフォルダーの設計を読み込む
• 特定のビューまたはフォルダーのエントリーを読み込む
• 文書を作成、読み込む、更新、削除
Domino Directory の設定
ドミノサーバー文書
– 「インターネットプロトコル」ー「Domino Web Engine」タブ
• 「Domino アクセスサービス」セクションの有効なサービスにアルファベットの「Data」を入力
※この項目はUpgradePack1が適用されていないドミノサーバーでは無効です※別途「インターネットサイト」文書を作成してWebサイトを構築している場合は、「設定」タブにDomino アクセスサービスのセクションがあります
Domino Directory の設定 (続き）
– サーバー文書を保存した後、Domino サーバーを再起動するか、次のコンソールコマンドを入力
• tell http refresh
以上でDomino サーバー上の設定は完了です。
DASが正常に動作するかを確認するには、
http://{ホスト名}/api/data のURLを
ブラウザに入力します。
右のように、ドミノサーバー上のデータベース
の一覧がJSON形式で表示さればOKです。
※ダブルバイト（漢字）はUNICODE
データ交換する対象のデータベースの設定
データベースプロパティの最後のタブ
– Lotus Domino データサービスを許可のプロパティ
• なし
• ビューのみ
• ビューと文書
ここでは「ビューと文書」を
選択します。
データ交換する対象のビューの設定
ビュープロパティでのデータサービスを許可のプロパティ
– Lotus Domino データサービスの操作を許可にチェック
ビューコレクションリソース
特定のデータベース内のビューとフォルダーのリスト取得のURI
– http://{ホスト}/{データベース}/api/data/collections
– @title: ビューまたはフォルダーのタイトル
– @folder: フォルダーの場合「true」
– @unid: ビューまたはフォルダーのユニバーサルID(UNID)
ビュー設計リソース
ビューおよびフォルダーの設計取得のURI
– http://{ホスト}/{データベース}/api/data/collections/unid/{unid}/design
@name: 列のプログラム名@titile: 列ヘッダータイトル@width: 列の幅@field: 「true」は文書内のフィールドを参照、
「false」は計算結果
次のURIでも同様のものが取得可能http://{ホスト}/{データベース}/api/data/collections/name/{ビュー名}/design
ビューエントリーリソース
ビューおよびフォルダーのエントリのリスト取得URI
– http://{ホスト}/{データベース}/api/data/collections/unid/{unid}
@href: このビューエントリのURI@link: 対象となる文書のURI@unid: 文書のユニバーサルID(UNID)
列に対する値: 列のプログラム名とそれに対応する値
ビューエントリーリソース(続き)
デフォルトのURIでは取得するコンテンツの範囲は10個(0-9の範囲)
– サンプルデータベースでは300文書のうち10文書分が表示されている
次の10エントリを取得するには
http://{ホスト}/{データベース}/api/data/collections/unid/{unid}?ps=10&page=1
– 上記の例での「ps」は取得するページのサイズを10とし、ページ番号1ページより(0ページ目から開始するので実質２ページ目)
ビューエントリーリソース(続き)
その他の主要なクエリーパラメーター
名前 型 オプション
説明
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 指定した階層のインデントレベルをもつエントリを返す
文書リソース
文書取得URI
– http://{ホスト}/{データベース}/api/data/documents/unid/{unid}
@href: この文書のURI@unid: 文書のユニバーサルID(UNID)@form: 文書作成に使用される
フォーム名
文書アイテムに対するフォールド名とその値
REST を使用したノーツ文書のCRUD
REST Web サービスのコンシューマー（クライアント）側へノーツ文書内の情報を他システムへ提供をする場合は、これまで見てきた方法を使用する。
コンシューマー側から、ノーツ文書内に情報を作成したり更新するには、コンシューマー側でプログラムを用意する必要がある。
– 言語はプラットフォームによるがJava言語がもっとも標準
CRUD
– 更新：PUT
– 作成：POST
– 読み取り：GET
– 削除：DELETE
以降でCRUDを行なうのにすべてプログラミングするのは大変なので、ここでは「Poster」というFireFoxのアドオンツールを使用して検証する
Poster
Posterのインストール
– http://addons.mozilla.org/ja/firefox/addon/poster/
– インストール後、ツールメニューの下に起動のメニュー
Poster
Posterの起動
Posterによるノーツ文書読み込み
これまでのRESTの操作で使用してきたURIを画面のURLに入力し、「GET」ボタンをクリック。
– データベースアクセスに認証が必要な場合は、「User Auth」にユーザー名とそのHTTPパスワードを入力
Posterによるノーツ文書読み込み
アクセスが成功するとステータス 200 が帰り、JSON形式の情報がレスポンスとして返ってきます。
Posterによるノーツ文書読み込み
既存の文書リソースでビューにある一番先頭の文書を取得する次のURIを入力します。
– http://{ホスト名}/Employees.nsf/api/data/documents/unid/073F4DF555D4983549257C8D00157A3B
Posterによるノーツ文書更新
前のページと同じURIを用いて、今度は更新（PUT）を実行します。
– 前のページで返ってきた内容から ＠xxxxx をのぞくフィールドと値の部分をコピーし、年齢（Age）の値を50に変更し、Content to Send に指定します。
※Content Type: application/jsonの指定は必須です。
※今回更新したい内容はAgeだけですが、他のフィールドも指定しなければなりません。指定しない場合は、フィールドがなくなりますので要注意です。その為、ノーツ文書の更新は、既存の文書内のフィールドを読み取ってから、すべてのフィールドに対して新たに値をセットするプログラミングが必要です。
Posterによるノーツ文書更新
ステータスが200で、成功したのを確認し、ノーツ文書が正しく変更されているか確認してください。
Posterによるノーツ文書新規作成
続いて、ノーツ文書を新規作成します。新規追加するフィールドとその値は、Content to Send に残っている内容に少し手を加えたものにします。– Age、Name、AlterNameを下の赤字のように変更します。
{
"Age”:13,
"AlterName":”Katsuo Isono",
"Gender":"\u5973",
"PhoneCarrier":"\u30C9\u30B3\u30E2",
"Name":”Katsuo Isono",
"CellPhone":"090-2753-7590",
"BloodType":"AB\u578B",
"Married":"\u672A\u5A5A",
"Prefecture":"\u6771\u4EAC\u90FD",
"Email":"[email protected]",
"Birthday":"1982-01-22T15:00:00Z",
"Comment":"\u5DE6\u30EB\u30FC\u30FB\u5225\u53E3\u6D3E"
}
URLを次のようにし、「POST」ボタンをクリックします。– http://{ホスト
名}/Employees.nsf/api/data/documents?form=Employee&computewithform=true
Posterによるノーツ文書新規作成
ステータスが201になって成功したことを確認します。 ノーツクライアントに戻って、一覧ビューの一番最後に今回のデータが追加されたの
を確認してください。
Posterによるノーツ文書の削除
先ほど作成した文書を削除しますが、文書を特定するためのステップと削除のステップが必要です。
文書の特定にはUNIDを知る必要がありますが、ここではsearchパラメーターでKatsuo Isonoを探します。（Katsuo Isonoという言葉が一意でユニークであることが前提）
– http://{ホスト名}/Employees.nsf/api/data/documents?search=KatsuoIsono
Posterによるノーツ文書の削除
返ってきた内容の中のUNIDを使用してURIを次のように指定します。
– http://{ホスト名}/Employees.nsf/api/data/documents/unid/{前ページで分かったUNID}
DELETE の選択と、右の丸いボタンをクリックします。
Posterによるノーツ文書の削除
返ってきた内容の中のUNIDを使用してURIを次のように指定します。
– http://{ホスト名}/Employees.nsf/api/data/documents/unid/{unid}
DELETE の選択と、右の丸いボタンをクリック。
データ交換のユーザー認証
RESTサービス使用の際のユーザー認証には
– Dominoサーバーへの Basic 認証
– セッション認証
の両方をサポート
