Domino 管理者 - Domino REST API について知っておくべきこと (パート 3)

2024/3/26 - 読み終える時間: 10 分

What you need to know about the HCL Domino REST API (Part Three) の翻訳版です。

HCL Domino REST API について知っておくべきこと (パート 3)

2024年3月12日

著者: Heather J Hottenstein / Technical Advisor

Domino Rest API ブログシリーズのパート 1 とパート 2 では、Domino REST API を Domino サーバーにインストールして構成する方法について説明しました。この記事では、外部アプリケーションが Domino アプリケーション、そのデータ、および設計要素に安全にアクセスできるようにするコンポーネントを作成する方法を学びます。

スキーマ、スコープ、OAuth Apps とは

デフォルトでは、Domino REST API から利用できるデータベースはありません。有効にする Domino データベースは自分で決めます。そして、これらのデータベースに対して、特定の設計要素を選択し、許可されるアクションを定義できます。これを Domino アプリケーションの公開と呼びます。Domino アプリケーションの公開は、管理者と開発者の間で共有されるアクティビティです。次の図に示すように、開発者はスキーマを作成し、管理者はスキーマを有効にして、スコープと OAuth アプリケーションを作成します。

スキーマ - 利用可能な設計要素はスキーマと呼ばれます。スキーマは、データベースの指定された設計リソースの JSON ファイルです。Domino データベースでは、フォーム、フィールド、ビュー、エージェントが含まれます。スキーマを作成および更新するには、NSF への Designer アクセスが必要です。スキーマは、Domino REST API、Domino REST API GUI（Admin UI）、またはスキーマ JSON ファイルを編集する Domino Designer を使用して作成できます。

これでエイリアスが作成されます。これを使用して、Domino REST API 経由でデータベースにアクセスできます。1 つの NSF を、異なるセキュリティ設定や異なる設計要素の定義など、複数のエイリアスの下で使用できます。

スコープ - スコープは、スキーマが誰に公開されるかを定義し、スキーマを使用するときに許可される最 大アクセスを指定します。Domino Administrator は Domino アプリケーションの定義されたスキーマを使用してスコープを作成し、Domino Keep 構成（keepconfig.nsf）データベースに保存します。スコープを作成および更新するには、keepconfig.nsf へのエディタアクセスが必要です。スコープを作成する際、管理者は DRAPI 経由でアクセスする際の最大許容アクセス数を定義します。しかし、これはACLを変更するものではなく、ACLを上書きするものでもない。たとえば、あるユーザーがデータベースへの読者権限を持っていて、許可される最大アクセス権がエディターである場合、そのユーザーは読者権限を維持します。

アプリケーション管理 - OAuth - ユースケースによっては、これはオプションのステップと見なされます。Domino REST API は、スコープと外部システムのコールバック URL を使用してアプリケーションを定義することで、外部システムで使用する OAuth/OIDC 制御アクセスを提供します。作成された文書は Domino Keep Configuration（keepconfig.nsf）データベースに保存されます。管理 UI を使用してアプリケーションを作成すると、アプリケーション ID とアプリケーションシークレットが生成されます。外部システムは、OAuth を使用して Domino REST API にアクセスする際にこれらを使用します。

Domino REST API GUI (Admin UI)

Admin UI は、DRAPI 経由でアクセス可能な Domino アプリケーションのスキーマ、スコープ、 アプリケーションを作成、管理するための使いやすいインターフェースを提供します。Web ブラウザとデータポート 8880 を使用してアクセスします。Domino サーバーの場合、URL はサーバーのホスト名の後に 8880 のポートを付けたもので、例：https://rock.adventure.com:8880。

1 . Web ブラウザを使って、http://serverhostname:8880 または http://127.0.0.1:8880 にアクセスします。

2 . 構成をクリックします。

3 . Domino ディレクトリの個人文書に従って、ユーザー名とインターネットパスワードを入力します。

4 . [LOG IN] をクリックします。

Domino REST API Admin UI ページが表示されます。

Admin UI を使用してスキーマ、スコープ、OAuth アプリケーションを作成する方法を見てみましょう。

注：以下の手順とスクリーンショットは、Domino V14.0 サーバー上で DRAPI 1.0.9 を使用して作成されています。異なるバージョンの DRAPI を使用している場合、若干の違いに気づくかもしれませんが、基本的なコンセプトは同じです。

スキーマの作成

1. 左側のナビゲーターバーでアイコン をクリックします。

2. [+ Add Schema] をクリックします。

3. スキーマの作成]をクリックします。

注：スキーマをインポートするオプションについては、この記事の後半で説明します。

4. 表示されるダイアログボックスで、[Database] フィールドのドロップダウンをクリックしてデータベースを選択します。

5. アイコンの横のドロップダウンをクリックして画像を変更します（オプション）。

6. スキーマ名には、スキーマを表す名前を入力します。スキーマ名はすべて 1 語で、一意でなければなりません。つまり、特定の Domino サーバーで定義された他のスキーマが同じ値を持つことはありません。

7. Schema Description (スキーマの説明) には説明を入力します。

8. Formula Engine は Domino のままにしておきます。

9. [Save Schema］をクリックして保存します。

10. 新しく作成されたスキーマのカードを表示するには、"Only show schemas configured with scopes" (スコープで構成されたスキーマのみ表示) をオフに切り替えます。

11. カードをクリックします。

最初に、マーケティングフォームを公開します。

12. Active をクリックし、スキーマにマーケティングフォームを追加します。

13. マーケティングフォームの左にある編集アイコン をクリックします。

14. 左側の ＋ アイコンをクリックして、すべてのフィールドをスキーマに追加します。

15. FullNameフィールドをクリックします。アクセス設定を変更できることに注意してください。

16. Save をクリックします。

注：［Mode Formula Settings］セクションには、Domino REST API で実行できることをさらに定義するオプションがあります。たとえば、デフォルトでは Delete Access の Formula は @False で、削除は許可されていません。この値を @True に変更すると文書の削除が許可されます。

注：上のスクリーンショットでは、右上の領域に[クローンモード]と[+追加モード]というボタンがあります。フォームモードは文書とそのデータへのアクセスを管理するための設定です。ユースケースに応じて、フォームごとに複数のモードを設定し、エンドポイントに応じて異なるアクセスを提供できます。管理者UIには、特別な目的を提供する4つのモード、default、dql、odata、rawがリストされています。

17. 上部でスキーマの名前をクリックします。

18. データベースビューをクリックします。

19. ($All) ビューで [Active] をクリックします。

20. ($All) の左側にある編集アイコンをクリックします。

21. すべてのビュー列をスキーマに追加するには、[+Add All] をクリックします。

22. Save をクリックします。

23. Source – Text Mode をクリックします。これがJSONで表現されたスキーマです。

この同じ情報はリソースファイルとして保存され、Domino NSF の設計の一部となります。Domino Designer クライアントを使用して、[Resources] - [Files] でこのファイルを確認できます。

注： 前述のように、スキーマは一般に Domino アプリケーション開発者が作成します。開発者は Domino Designer クライアントまたは REST API Admin UI を使用してスキーマをエクスポートできます。REST API Admin UI の［スキーマのエクスポート］および［スキーマのインポート］ボタンは、アプリケーションのプロモーション/デプロイメントプロセスの一部として使用することを目的としています。つまり、アプリケーション開発者はスキーマのソース ページにあるエクスポート ボタンを使用してスキーマを作成し、エクスポートします。エクスポートされたスキーマは JSON ファイルとして保存されます。開発者はこの JSON ファイルを管理者に提供します。その後、管理者はスキーマのインポートボタンを使用し、JSONファイルを選択することで、それぞれのデータベースに新しいスキーマを作成します。

スコープの作成

スキーマができたので、スコープを作成します。

• Web ブラウザで開いている Domino REST API Admin UI に戻ります。
• 左上の領域で［概要］をクリックします。
• 左側のナビゲーターでアイコン をクリックします。
• スコープの追加]をクリックします。
• ダイアログボックスの右側で、[スコープ名]、[説明]、[Domino サーバー]、[最大アク セスレベル]、[スコープアイコン]を入力/選択します。
• Add]ボタンをクリックします。

注：最大アクセスレベルは DRAPI 経由のアクセスに関するものです。データベースの ACL は更新されません。Domino データベースの ACL で定義されたユーザーのアクセスは、それを超えることはありません。たとえば、ユーザーが ACL でリーダーとして定義され、スコープの最大アクセスレベルがエディターである場合、そのユーザーは DRAPI 経由で文書を作成できません。

スコープにカードが追加されました。さらに、Domino Keep 構成（keepconfig.nsf）データベースに文書が作成されました。

• DRAPI がインストールされているサーバーの Domino Administrator クライアントを開きます。
• Files タブを選択します。
• Domino Keep Configuration（keepconfig.nsf）データベースを開きます。
• アクティブ - データベース を選択します。
• 同じスコープ名の文書を開きます。

アプリケーションの作成

Domino データベースを DRAPI で利用できるようにする最後のステップとして、OAuth を使用して外部アプリケー ションからアクセスできるアプリケーションを作成します。

データベースのユースケースによっては、スコープとスキーマだけで十分な場合もあるので、アプリケーションの作成は必要な場合もあれば不要な場合もあります。

1. Web ブラウザで開いている Domino REST API Admin UI に戻ります。

2. 左側のナビゲータでアイコン を押します。

3. [+ Add Application] をクリックします。

4. Add New Application ダイアログボックスで、Application Name、Description、 Callback URL、Startup Page、Scope、Contacts、Icon を入力/選択します。

5. [Add] ボタンをクリックします。

注：コールバック URL は、DRAPI を介して Domino にアクセスする外部アプリケーションから提供され ます。

注：ドロップダウンメニューからスコープを選択した後、[+] ボタンをクリックします。

アプリケーションのカードが表示されます。

自動的に生成されたApp IDに注目してください。これは DRAPI を通じて Domino アプリケーションにアクセスする外部アプリケーションに提供されるものです。さらに、アプリケーションシークレットを生成する必要があります。

6. アプリケーションカードの右上にマウスを置くと、アイコンのセットが表示されます。

7. 最初のアイコンをクリックします。

DRAPI を通じて Demo データベースにアクセスする外部アプリケーションに、アプリケーション ID とアプリケーションシークレットを提供します。Id と Secret をクリックして値をクリップボードにコピーするだけです。

さらに、Domino Keep Configuration（keepconfig.nsf）データベースに文書が作成されました。

8. DRAPI がインストールされているサーバーの Domino Administrator クライアントを開きます。

9. Files タブを選択します。

10. Domino Keep Configuration、keepconfig.nsf、データベースを開きます。

11. Active – Applications を選択します。

12. 同じアプリケーション名の文書を開く

このブログシリーズを楽しんでいただき、Domino REST API を Domino サーバーにインストール、設定、管理するのにお役に立てれば幸いです。ご不明な点がありましたら、お気軽にお問い合わせください。