HCL Domino REST API Part 2: スキーマとスコープの設定
本記事では、HCL Domino REST API についてさらに掘り下げ、 スキーマとスコープの設定を通じてデータアクセスと統合を強化する方法を解説します。
前回の記事では、Domino Server と REST API 環境のセットアップを行いました。今回は、 HCL Notes アプリケーションのアクセスパラメータを設定し、構造化されたデータ取得とセキュアな API 連携を実現していきます。
REST API の設計
設定に入る前に、HCL Domino REST API が HCL Notes アプリケーション（.nsf ファイル）をどのように API として公開するのかを理解しておきましょう。
この API を使用すると、開発者は HCL Notes アプリケーション内のフォーム、ビュー、エージェントを API エンドポイントとして操作できるようになります。
以下の図は、Domino REST API 内でデータベース、スキーマ、スコープがどのように連携するかを示しています。
詳細については、HCL Domino の公式ドキュメントをご参照ください： Understanding Domino REST API
Domino の NoSQL ライクなアーキテクチャでは、スキーマを使用してフォーム、ビュー、エージェントを API データモデルとして公開します。 これらのスキーマによって、API 経由でアクセス可能な要素が決まり、開発者は HCL Notes アプリケーションから 派生した構造化データモデルを扱うことができます。
フォームはデータモデルの基盤として機能し、各フォームで読み取り可能なフィールドと書き込み可能なフィールドを指定します。 ビューはドキュメントのコレクションをクエリして表示する手段を提供し、エージェントは API 経由で実行できるように公開できます。
スキーマは「スコープ」を通じて公開され、スコープは OAuth アプリケーションに紐づけられます。 認証・認可のプロセスで、リクエストされたスコープによって API がアクセスできるスキーマが決まります。
Domino REST API には、MAIL、$DATA、$DECRYPT などの 基本スコープも含まれており、メールやデータへのアクセス権限を管理します。
スコープの詳細については、 こちらをご覧ください。
対象アプリケーション
本ガイドでは、顧客情報を管理する Demo.nsf アプリケーションを公開します。 このアプリケーションには、「Customer」フォームや「Customers」ビューなど、データを整理・表示するための要素が含まれています。
HCL Notes アプリケーションの REST API 設定
API 環境を構成しただけでは、HCL Notes アプリケーションに直接アクセスすることはできません。 Domino REST API 管理インターフェース（通常はポート 8880）から スキーマとスコープを設定する必要があります。
- 管理画面を開き、Configuration をクリックします。
- Domino Server の資格情報を使用してログインします。
- インターフェースを使用して、スキーマ、スコープ、OAuth アプリケーションを設定します。
スキーマの追加
HCL Notes アプリケーションの要素を API 経由で公開するには、まずスキーマを作成する必要があります。
- Schema Management に移動し、+Add Schema をクリックします。
- 新しいスキーマを作成するか、既存のスキーマをインポートするかを選択できます。今回は新規作成するので、Create Schema を選択します。
- 接続された Domino Server 上の .nsf ファイルの一覧が表示されます。公開するアプリケーションを選択し、 Schema Name と Description を入力して、Add をクリックします。
- これでスキーマの基盤が作成されます。デフォルトでは、スコープが設定されているスキーマのみが表示されるため、 すべてのスキーマを表示するには Only show schemas configured with scope のチェックを外してください。
スキーマへのフォームとビュー要素の追加
次に、このアプリケーション内のどのフォーム、ビュー、エージェントを API として公開するかを設定していきます。
- Customer フォームの追加：
- まず、Customer フォームを選択します。
- Domino Designer では、フォームは以下のように表示されます。
- デフォルトとして設定するかどうかを確認するプロンプトが表示されます。確認してデフォルトに設定してください。
- Customer フォームのフィールド設定：
- 次に、対象フォームを開き、このフォーム内のどのフィールドを API として公開するかの定義を追加します。
- Customer フォームを開きます。
- 左側の項目リストから「+」ボタンをクリックしてフィールドを追加します。
- このフォーム内のどのフィールドを API として公開するかを定義します。
- Field Type や Read/Write 権限などのプロパティを設定します。
これでフォーム要素の公開設定は完了です。
- Customers ビューの追加：
- Database Views タブに移動します。
- Customers ビューを有効化します。
- ビューはそのまま使用することもできますが、API 公開用にエイリアスを指定することも可能です。
-
本ガイドでは詳しく触れませんが、エージェントも API 経由で実行できるように公開できます。
スコープの追加
スキーマの設定が完了したら、API としてアクセスできるようにスコープを追加します。
- Scope Management に移動し、+Add Scope をクリックします。
- Demo スキーマを選択し、Scope Name と Description を入力して追加します。
これで API リクエストを行うための設定が完了しました。
基本的な内部利用であれば、これで十分です。ただし、外部サービスとの連携を予定している場合は、 複数のスコープをまとめたアプリケーションを OAuth アプリケーションとして登録し、 認証・認可プロセスを実装することができます。
まとめ
スキーマとスコープを設定し、HCL Notes アプリケーションを HCL Domino REST API 経由で公開する方法を解説しました。この設定により、HCL Notes アプリケーション内の フォーム、ビュー、エージェントへのセキュアで構造化されたアクセスが可能になり、外部システムとのシームレスな連携を実現できます。
次回のパートでは、Postman を使用して API コールを実行し、設定したエンドポイントを操作する方法を紹介します。 REST API 経由でデータを取得・操作する方法を実演します：HCL Domino REST API Part 3: Postman から REST API を使用する。