AndroidアプリでREST経由でNotesデータにアクセスする：XPagesでスマホWebアプリ開発入門（番外編）（2/3 ページ）

XPagesから離れて、AndroidのネイティブアプリからREST APIを呼び出してNotes/Dominoデータにアクセスします。

[佐藤淳，日本アイ・ビー・エム Lotusテクノロジー開発]

DominoデータサービスのデータフォーマットはJSON

　先述のように、Dominoデータサービスを利用する際に用いられるデータのフォーマットはJSONです。Lotus Notes/Dominoアプリに格納されているデータはデータコンバータによってJSONへ変換され、Lotus Notes/Dominoアプリのデータの取得や更新などが行えます。

　例えば、Lotus Domino上のアプリの一覧をDominoデータサービスで取得した場合、Lotus Domino上のLotus Notes/Dominoアプリのリストが以下のようなJSONデータで表現されます。

[
  {
      "@title":"Administration Requests",
      "@filepath":"admin4.nsf",
      "@replicaid":"8525786A034D582B",
      "@template":"StdR4AdminRequests",
      "@href":"http://acme.com:80/admin4.nsf/api/data/collections"
  },
  {
      "@title":"Java AgentRunner",
      "@filepath":"AgentRunner.nsf",
      "@replicaid":"8525671400725208",
      "@template":"",
      "@href":"http://acme.com:80/AgentRunner.nsf/api/data/collections"
  },
  {
   ……
   }
]

　それぞれのJSONプロパティの意味は以下のようになっています。

@title	Lotus Notes/Dominoアプリのタイトル。日本語がタイトルに使われている場合はUnicodeでエンコードされる
@filepath	Lotus Notes/Dominoアプリの実体であるNSFファイルへのパス。Lotus Dominoのデータディレクトリをルートとしている
@replicaid	Lotus Notes/Dominoアプリを識別するためのレプリカID。この値はサーバ内で一意の値になる
@template	Lotus Notes/Dominoアプリのベースとなっているテンプレート名。テンプレートタイトルとは異なる。テンプレートを使用していない場合はブランク
@href	そのLotus Notes/Dominoアプリのビューやフォルダの一覧を表示するコレクションを取得するための参照URL

　同様に、DominoデータサービスでLotus Notes/Dominoアプリ内の文書の詳細情報を取得した際には以下のようなJSONフォーマットのデータが返ってきます。

{  
"@href":"http://acme.com:80/XPagesExt.nsf/api/data/documents/unid/5D006566E919779E852578B7004A6019",
    "@unid":"5D006566E919779E852578B7004A6019",
    "@noteid":"906",
    "@created":"2011-06-22T13:32:22Z",
    "@modified":"2011-08-21T14:39:31Z",
    "@authors":["CN=Admin/OU=Lotus/O=Lotus","CN=rperronadmin/O=rtest","Anonymous"],
    "@form":"Contact",
    "$UpdatedBy":"CN=Admin/OU=Lotus/O=Lotus;CN=rperronadmin/O=rtest;Anonymous",
    "$Revisions":"06/22/2011 09:32:22 AM;06/22/2011 09:33:17 AM;08/15/2011 12:16:31 PM;08/15/2011 12:19:31 PM;08/15/2011 12:27:52 PM;08/15/2011 12:29:54 PM;08/15/2011 02:30:35 PM;08/15/2011 03:54:14 PM;08/15/2011 03:55:25 PM;08/18/2011 11:08:34 AM;08/18/2011 11:11:29 AM",
    "FirstName":"Barney",
    "LastName":"Bloomberg",
    "EMail":"[e-mail]",
    "City":"New York City",
    "Number":1.75,
    "Date":
     ["2011-07-21T20:21:00Z","2011-08-01T14:38:00Z"],
    "Body":
    {
        "contentType":"text/html",
        "data":"Just <b>sales</b>.",
        "type":"richtext"
    }
}

　それぞれのJSONプロパティの意味は以下のようになっています。

@href	参照している文書にアクセスするためのURL
@unid	この文書を識別するためのユニバーサルID。この値は、サーバ内で一意
@noteid	この文書を識別するためのノートID。この値は、このアプリ内で一意
@created	この文書が作成された日時
@modified	この文書が最後に編集された日時
@authors	この文書の作成者と編集者
@form	この文書に関連付けられているフォーム名。Lotus Notesからこの文書を開く際に、ここで指定されているフォームが使用される
{itemname}	文書が持つフィールド名と、そこに格納されているデータ。リッチテキストの場合には、MIMEでその内容が表示される

　Dominoデータサービスを用いて文書を作成する際には、その文書と関連付けるフォーム名の情報をパラメータにセットし、文書の中身をJSONデータの形式で送信（POST）します。そのときJSONデータには上記の表の{itemname}の項目を指定します。Dominoデータサービスを利用したLotus Notes/Dominoアプリのアクセス方法については、この後の章で詳細に解説します。

Dominoデータサービスを設定する

　Dominoデータサービスでは、サーバ単位、アプリ単位、ビュー単位でアクセス設定を行う仕組みが用意されています。デフォルトでは、すべてアクセスができないようになっており、システム管理者やアプリの管理者が必要に応じてアクセスを許可するように設定できます。

　Dominoデータサービスを利用するには、以下の3つの手順が必要となります。

1. Lotus DominoでDominoデータサービスを有効にする
2. アプリごとにDominoデータサービス経由でのアクセスを有効にする
3. アプリのビューごとにDominoデータサービス経由でのアクセスを有効にする

　まず、Lotus Dominoでの設定はDominoディレクトリ（names.nsf）内に格納されているサーバの設定情報が記されているサーバ文書、または、インターネットサイトが有効になっている環境では、Webの設定情報が記されているWebサイト文書で行います。

1. Lotus NotesまたはDomino AdministratorからDominoディレクトリを開き、サーバ文書またはWebサイト文書を開く
2. Lotus Dominoが提供するHTTPタスクの設定項目である「DominoWebEngine」タブを開く
3. 「Dominoアクセスサービス」フィールドに「データ」を選択
4. 修正したサーバ文書またはWebサイト文書を保存
5. Lotus DominoのHTTPタスクを再起動

　以上で、Lotus Domino上でDominoデータサービスが有効になります。

　なお、この設定に関連してLotus Notes/Domino5.5.3 Upgrade Pack 1では、サポート文書「IBM 日本語版 Lotus Domino で Domino データサービス (DDS) が利用できない - Japan」に記載された制限があります。

　次に、DominoデータサービスでアクセスをするLotus Notes/Dominoアプリの設定を行います。

1. 対象のLotus Notes/DominoアプリをDomino Designerで開き、「アプリのプロパティ」を開く
2. 「詳細」タブに移動し、「AllowDominoData Service:」に「Views Only」または「Views and documents」を設定（図3）

図3　アプリにおけるDominoデータサービスの設定

　「AllowDominoData Service:」は、デフォルトでは「Never」となっており、DominoデータサービスでLotus Notes/Dominoアプリにアクセスできません。

　「Views only」を設定することでLotus Notes/Dominoアプリのビュー、フォルダのコレクションや、それらに格納されている文書の一覧の取得が行えるようになります。「Views and documents」と設定すると、ビュー、フォルダのデータへのアクセスに加えて、Lotus Notes/Dominoアプリに格納されている文書の詳細情報にアクセス可能になります。

　文書に関しては閲覧だけではなく新規作成や既存文書の更新および削除も行えます。目的に応じて、どちらかを設定してください。文書の更新や削除を行うためには、対象となるアプリのアクセス制御リスト（ACL）でユーザーのアクセス権が適切に設定されている必要もあります。

　最後に、実際にDominoデータサービスでアクセスをするLotus Notes/Dominoアプリのビューのオプションを設定します。

1. Domino Designerで対象となるビューの設計開き、プロパティを表示
2. プロパティのインフォボックスで「詳細」タブに移動し、「Lotus Dominoデータサービスの操作を許可」にチェックを入れる
3. ビューの設計を保存

　以上でDominoデータサービスを利用できます。動作を確認するために、Webブラウザから以下のURLにアクセスします。

http(s)://{Lotus Dominoホスト名}/{Dominoデータサービスを有効にしたアプリファイル名}/api/data/collections
例
http://acme.com/hoge.nsf/api/data/collections

　正しく設定がされていると、対象のLotus Notes/Dominoアプリのビューとフォルダの一覧をJSON形式のデータで取得できます。正しく設定がされていないと、エラーメッセージがレスポンスデータとして返ってきたり、Lotus Dominoのコンソール上に表示されたりするので、その内容を参考に設定を見直してください。

図4　DominoデータサービスをWebブラウザを用いて動作検証