メインコンテンツへスキップ

Forguncyサポート

[V8] ユーザーアカウント管理をREST APIで行う

Forguncyサポートチーム
  • 更新

Forguncyのユーザー管理サービスを操作する方法は次の４つあり、新しいユーザーの作成や削除など、ユーザー管理に必要な操作を行うことができます。
ここでは「４．ユーザーアカウント管理REST API」を利用して、組織の追加や削除、および組織へのユーザの追加や削除を実装する方法を、サンプルプロジェクトを使用して説明します。

Forguncyのユーザー管理サービスを操作するさまざまな方法

  1. ユーザー管理コマンド
    コマンドで指定する方法です。上記のリンク先からプラグインをダウンロードしてインストールすることで、本コマンドが使用できるようになります。操作が一番容易で、多くの必要な操作を行うことができます（組織の追加や拡張属性の操作などはできません。これらの操作を行いたい場合は、ユーザーアカウント管理 REST APIを使用してください）。
    サーバーサイドコマンドかスケジュールタスクでのみ使用することができます。
  2. カスタムJavaScript
    Forguncyが提供するカスタムJavaScriptを記載する方法です。ユーザーの追加や削除、およびロールを指定したユーザーの追加や削除のみが行えます。
  3. カスタムWeb API
    Visual Studioを使用してForguncyが提供するカスタムWeb APIを使ったDLLを作成し、そのDLLをForguncyのプロジェクトに組み込んで使用する方法です。ユーザーの追加や削除と、登録されているForguncyのすべてのユーザーアカウント情報の取得のみが行えます。
  4. ユーザーアカウント管理REST API
    Forguncyが提供するユーザーアカウント管理REST APIを使用する方法です。HTTPリクエスト送信コマンドより呼び出して使用します。細かな設定が行えますが、REST APIによるユーザー情報の変更は、ユーザー情報ビューに即時反映されません。このため、ユーザー情報ビューを同時に使用する場合は、ユーザー管理コマンドの方法で操作するようにしてください。

ユーザーアカウント管理REST APIを使用する際に必要な各種プラグイン

添付のサンプルプロジェクトは次のプラグインを使用しています。起動時に「プラグインのインストール」ダイアログが表示された場合、ダウンロードしてインストールしてください。

アクセス権限

添付のサンプルプロジェクトは組織情報を変更するため、Administratorおよび「担当者」ロールを持つユーザ以外はアクセスできないように設計されています。アクセス許可の問題が表示される場合は、アクセス権のあるユーザーで再ログインしてください。アクセス権のあるユーザーはログインページに記載しています。

また、ユーザーアカウント管理REST APIはForguncy Serverがインストールされているコンピューターからの呼び出しにおいてのみ動作します。このため、REST APIの呼び出しはすべてサーバーサイドコマンドによって実装されており、その実行権もサーバーサイドコマンドの［アクセス許可の設定］に依存しています。

サンプルプロジェクトの機能紹介

メインページ

  1. 組織、メンバーの一覧表示
    ページロード時のコマンドにより、B2セルに設定されている組織の配下組織をリストビュー1に表示します。リストビュー2,3,4はそれぞれ対応するU5,B19,U21セルのコマンドに、リストビューの表示処理を設定しています。リストビュー1のレコードが選択されることで、「カレントレコード変更時のコマンド」により、それぞれのセルの値が変わりリストビューが再表示されます。
    リストビューに表示する組織および組織のメンバーは組織情報取得API（GetOrganizationInfos）によって取得しています。それぞれのリストビューに対応するAPI実行結果をメインページ右側に表示しています。
    mceclip0.png
    「すべて表示」ボタンを押下すると、API実行結果表示モーダルが表示され、展開された実行結果を確認できます。
    APIから取得した実行結果を「JSONデータの設定(リストビュー)」コマンドで対応するリストビューに展開しています。
    プラグイン / プラグイン（要ダウンロード） / JSONデータソースコマンド / JSONデータの設定(リストビュー)
    このコマンドでは［サンプルJSONデータの設定］から実行結果のJSONデータを設定することで、そこから解析されたプロパティ名が、［JSONパス］、［リストビュー列］のドロップダウンリストで選択できるようになります。
    mceclip5.png
    ユーザーの氏名表示にはODataを利用しています。これは、組織情報取得API（GetOrganizationInfos）の実行結果から、所属しているユーザーのユーザーIDしか取得できないためです。リストビューのセルにODataを利用する場合、行毎にODataの問い合わせ処理が発生するため表示処理が遅くなる場合があります。本サンプルでは１つの組織に所属するユーザ数が、表示処理に影響を与えるほど大きな件数にはならないと想定して実装しています。
  2. 組織の追加
    組織名を入力して「組織の追加」ボタンを押下することで、リストビューに表示されている組織と同じ階層に組織を追加できます。組織の追加には、組織追加API（AddOrganization）を利用しています。
    メインページ右側の「組織/メンバー操作API」欄にAPIの実行結果が表示されます。データの操作を伴うAPIは実行結果から処理が正常終了したかを確認する必要があるため、「JSONデータの設定(通常セル)」を利用して実行結果からResultプロパティとMessageプロパティの値を取得しています。
    正常終了（Resultプロパティの値がtrue）のとき、対応するリストビューのデータを再取得し、入力された組織名をクリアします。
    エラーのとき、Messageプロパティの値をエラーメッセージとして画面に表示します。
    mceclip3.png
  3. 組織の削除
    リストビューの「削除」リンクを押下することで、組織が削除されます。削除の実行前に警告を表示します。組織の削除には、組織削除API（DeleteOrganization）を利用しています。結果の表示、および正常終了/エラーのときの動作は「2.組織の追加」と同様です。
  4. ユーザーの検索
    「ユーザーの検索」ボタンを押下すると。ユーザー選択モーダルがポップアップします。モーダルで選択したユーザーが入力セルに転記されます。
  5. 組織のメンバーの追加
    「ユーザーを追加」ボタンを押下することで、リストビューで選択されている組織にユーザーを追加できます。ユーザーの追加には、組織のメンバー追加API（AddUsersToOrganization）を利用しています。結果の表示、および正常終了/エラーのときの動作は「2.組織の追加」と同様です。
  6. 組織のメンバーの削除
    リストビューの「削除」リンクを押下することで、組織からユーザーを削除できます。この操作では、ユーザーのアカウントは削除されません。ユーザーの削除には、組織のメンバー削除API（RemoveUsersFromOrganization）を利用しています。結果の表示、および正常終了/エラーのときの動作は「2.組織の追加」と同様です。

ユーザー選択モーダル

ユーザー情報ビューから、ユーザー名と氏名でユーザーを検索、選択できるページです。

API実行結果表示モーダル

API実行結果であるJSON文字列を整形して表示します。文字列の整形処理はページロード時のコマンドに、「JavaScriptコードの実行」コマンドを設定して実装しています。コード内で利用しているJSON.stringify(), JSON.parse()はJavaScriptの標準組み込み関数です。

組織名変更ページ

組織の一覧表示、およびAPI実行時の挙動については、メインページと同様に実装されています。

  1. 組織名の変更
    リストビューから組織を選択し、新しい組織名を入力して「名称を変更」ボタンを押下することで組織名を変更できます。組織名の変更には組織情報の変更API（UpdateOrganizationInfo）を利用しています。

組織メンバー一覧

ユーザー情報ビューをもとに、ユーザの組織所属情報を一覧表示します。

TIPS

その他、REST APIを利用した実装パターンをいくつか紹介しています。単機能のため、説明はページに記載しています。

  1. 組織の情報をテーブルに保存する
  2. サーバーサイドコマンドでAPIの実行結果をテーブルに保存する
  3. APIの実行結果をドロップダウン項目として利用する

サーバーサイドコマンド

ユーザーアカウント管理REST APIの実行（HTTPリクエストの送信）

サーバーサイドコマンドでREST APIを実行する場合の設定手順を説明します。

  1. ［全般］タブから［アクセス許可の設定］をする
    特にデータの更新が発生する処理については、［アクセス許可の設定］を特定のユーザーのみに制限することを強く推奨します。
    mceclip4.png
  2. ［パラメーター］タブでパラメーターを設定する
    対象のREST APIにパラメーターが存在し、パラメーターを任意に変更したい場合はパラメーターを設定しておきます。［パラメーターの名前］は任意で構いません。
    mceclip1.png
  3. コマンドを設定する
    基本的に「HTTPリクエストの送信」コマンドを利用して、REST APIを呼び出す動きとなるためコマンドのつくりは大きく変わりません。
    • ユーザーアカウント管理のベースURL取得
      デバッグ環境、サーバー環境の違いで問い合わせ先のURLが変動するため、ベースURLを本コマンドによって取得します。
    • HTTPリクエストの送信
      • ［リクエストボディ］タブの［URL］に呼び出すAPIのURLを指定します。この時、「Origin/UserService」は上記で取得したベースURLに置き換えます。
      • ［データの形式］は「オブジェクト」を指定します。
      • ［JSON形式のデータを送信］をチェックします。
      • キーにAPIのパラメーターを設定し、値に対応するサーバーサイドコマンドのパラメーターを設定します。API側で必須となっているパラメーターはすべて設定する必要があります。
      • ［結果を格納するパラメーター名］に任意のパラメーター名を指定します。
        mceclip2.png
      • ［リクエストヘッダー］タブで、キー「Content-Type」に「application/json」を指定します。この設定は［JSON形式のデータを送信］にチェックを入れているため必要となります。
        mceclip3.png
    • リターン（コマンドの終了）
      リターンメッセージに［結果を格納するパラメーター名］を指定します。リターンコードを200としている理由については、本記事のエラーの取り扱いについてを参照ください。
  4. テスト実行で動作を確認する
    ページに組み込む前にテスト実行にて動作を確認します。URLやパラメーターの設定誤りを事前に検知できます。

サーバーサイドコマンドのつくりは大きく変わらないため、既存のコマンドを複製してURLとパラメーターを変更することで別のREST APIの実行コマンドを作成可能です。

REST APIにはパラメーターに配列を要求するものがあります。組織のメンバー追加API（AddUsersToOrganization）の設定例を参考にしてください。

エラーの取り扱いについて

本サンプルのサーバーサイドコマンドでは、コマンド実行時のリターンコードをすべて200に設定しています。未設定の場合、サーバーサイドコマンドは正常終了時にリターンコード0を返す仕様となっていますが、ネットワーク接続エラーなどでも一部リターンコードが0で終了する場合があります。このため、本サンプルでは問題発生時に「少なくともサーバーサイド処理は問題なく出来ていること」を切り分けるため、サーバーサイドコマンドが正常終了した場合に、リターンコード200を返すよう設定しています。

また、ページからサーバーサイドコマンドを実行したとき、リターンコード200が返らなかった場合、担当者へ連絡を誘導するつくりとしています。これは多くの場合、正常終了でないエラーはエンドユーザーでは解決できない問題であるためです。例えば、入力間違い（既存の組織名を追加しようとするなど）はエンドユーザーが対応可能ですが、権限エラーコード403や上記のネットワーク接続エラー0の場合などは、エンドユーザーが対応できない場合が多いと思われます。

エラー発生時のユーザーの誘導については運用設計に関わりますので、作成するアプリケーションの性質に合わせて実装してください。

その他注意事項

ユーザー情報ビューを使わない理由について

REST APIによるユーザー情報の変更はユーザー情報ビューに即時反映されない場合があります。一方でユーザー管理コマンドを利用してユーザー情報を更新した場合は、ユーザー情報ビューが即時反映されます。

プラグイン / プラグイン（要ダウンロード） / ユーザー管理コマンド

本サンプルではこの問題を回避するために、メインページではユーザー情報ビューを利用せず、REST APIで実行結果を取得しています。

  • 原因

    ユーザー管理コマンドとユーザーアカウント管理REST APIは、ユーザー情報を変更に同じロジックを使っており、ともに非同期で実行されます。​この２つの違いは、ユーザー管理コマンドのみが、ユーザー情報の更新日時の書き換え、および、キャッシュのクリアを行うという点です。​

    ユーザーやロールが格納されているテーブルはサーバー側のユーザーアカウント情報データベースに格納されています。​それに対して、ユーザー情報ビューは、アプリケーション毎に、そのアプリケーション用の内部データベースに作られます。​
    ユーザー管理コマンドでサーバー側のユーザーアカウント情報データベースを変更すると、ユーザー情報の更新日時をチェックして、各アプリケーションの内部データベース（ユーザー情報ビュー）を非同期で更新します。​このため、ユーザー管理コマンドでユーザー情報を変更すると、ユーザー情報ビューが即時更新されるようになります。​

    しかし、ユーザーアカウント管理REST APIでユーザー情報を変更した場合、ユーザー情報の更新日時は書き換わらないためユーザー情報ビューは即時更新されません。しばらく待つと同期が行われ、更新されます。​

添付のサンプルプロジェクトは、Forguncy 8.0.6.0以降のバージョンで読み込むことができます。