GAM イベントのサブスクリプションの目的は、GAM イベントの実行時に追加 (外部) コードを自動的にトリガーすることです。つまり、GAM イベントを実行した後 (GAM ユーザーの作成など) に、カスタムイベントを自動的に実行できるようにします。
Users テーブルがあり、ユーザー情報が GAM の Users テーブルと重複している例について考えます。
Users テーブルは最新の状態に保つ必要があります。つまり、GAM ユーザーが更新 (作成または削除) された場合は、それに合わせて Users テーブルを更新する必要があります。
このような場合、次の疑似コードを使用します:
&GAMUser.Save()
//Users テーブルに必要な変更を加えるプロシージャーを呼び出す。
GAM ユーザーを更新するすべての部分にこのコードを検討しなくてもよいように、GAM ユーザーの更新直後にこのコードを自動的にトリガーできます。
実行を宣言したコードを自動的にトリガーするイベントは、GAM ユーザーの
挿入、更新、削除と考えます。
言い換えると、いくつかのイベントにサブスクライブし、これらのイベントの実行時に (外部) コードをトリガーできるようにします。
- User_Insert: GAM ユーザーの挿入
- User_Update: GAM ユーザーの更新
- User_Delete: GAM ユーザーの削除
- User_UpdateRoles: ユーザーリストのロールの変更
- User_GetCustomInfo: このイベントを使用すると、ID プロバイダーがクライアントに送信する情報をカスタマイズすることができ、ユーザーが認証されるとき (SSO Web) またはトークン (OAuth 2.0) を要求したときに実行されます。このため、プロシージャーの出力は JSON を返す必要があります。共有する情報の構造を持つ SDT を使用することが推奨されます。
- User_SaveCustomInfo: このイベントは、GAM リモートログインまたはリモート REST 認証タイプ (OAuth 2.0) のログインが正常に終了したときにクライアントで実行されます。
- Role_Insert: ロールの挿入
- Role_Update: ロールの更新
- Role_Delete: ロールの削除
- Repository_Login: GAM ユーザーのログイン (任意の認証タイプをサポート)
- Repository_LoginFailed: ユーザーログインの失敗 (GAM エラー 11 または GAM エラー 18)
- Repository_Logout: GAM のログアウト
- Application_CheckPermissionFail: アクセス許可の検証の失敗
- User_OneTimePasswordValidUser。OTP コードを要求したユーザーに使用を許可するかどうかを確認します。
- User_OneTimePasswordGenerateCode。OTP コードを生成するための開発者イベントです。
- User_OneTimePasswordSendCode。OTP コードを送信するための開発者イベントです。
- User_OneTimePasswordValidateCode。OTP コードを検証するための開発者イベントです。
イベントをサブスクライブするには、イベントの実行時にトリガーされるプログラムを設定します。設定は
GAM API(1) または
Web Backoffice(2) を使用して行うことができます。詳細については後述します。
GAM イベントを監視するプログラムは、GeneXus で開発されていても、開発されていなくてもかまいませんが、いくつかの要件を満たしている必要があります。
まず、プログラムの署名が次のようになっている必要があります:
(in Character
&EventName, in Character
&jsonIn, out Character
&jsonOut)
入力値の説明:
- &EventName: GAMEvents ドメインに属します。
- &jsonIN: JSON 文字列で、その書式はプログラムがサブスクライブする GAM イベントによって異なります (詳細は下表を参照)。
- &jsonOUT: GAM トレース (有効になっている場合) への情報の出力に使用する JSON 文字列です。
[ Main program ] プロパティが
True になっている必要があります。
次に、&jsonIN の書式を検討します:
| イベント |
パラメーターを受け取る GAM オブジェクト |
| User_Insert |
GAMUser (jsonIN 書式は GAMUser オブジェクトから派生) |
| User_Update |
GAMUser |
| User_Delete |
GAMUser |
| User_UpdateRoles |
ロールが変更されたユーザーのリストを表す GAMGUID コレクション |
| User_GetCustomInfo |
GAMSession |
| User_SaveCustomInfo |
(自由形式) |
| Role_Insert |
GAMRole (jsonIN の書式は GAMRole オブジェクトから派生) |
| Role_Update |
GAMRole |
| Role_Delete |
GAMRole |
| Repository_Login |
GAMSession (jsonIN の書式は GAMSession オブジェクトから派生) |
| Repository_Logout |
GAMSession |
| Repository_LoginFailed |
GAMSession |
| Application_CheckPermissionFail |
GAMSessionLogCheckPermissionFail |
| User_OneTimePasswordValidUser |
GAMOTPEventSubscription |
| User_OneTimePasswordGenerateCode |
GAMOTPEventSubscription |
| User_OneTimePasswordSendCode |
GAMOTPEventSubscription |
| User_OneTimePasswordValidateCode |
GAMOTPEventSubscription |
次の例では、User_Insert イベントをサブスクライブしています。
Web Backoffice(2) で、 [ 設定 ] > [ イベントのサブスクリプション ] の順に選択し、次の図に示すようにイベントを定義します。
Java の設定 (この例では、Java のパッケージ名 = com.gameventssubscription)
| ステータス |
[ サブスクライブ済み ] 、 [ サブスクライブ解除済み ] のいずれかです。イベント実行時にプロシージャーをトリガーするためには、「サブスクライブ済み」にしておく必要があります。 |
| イベント |
任意のイベントを選択できるコンボボックスです。
|
| ファイル名 |
イベント実行を監視する .dll ファイルまたは .class ファイルの名前です。 |
| クラス名 |
パッケージが含まれるプログラムの名前です。 |
| メソッドの名前 |
GeneXus におけるプログラムのメソッドは常に「execute」です。 |
notifyuserinsert プロシージャーのコードは以下のとおりです:
Rules: Parm(in:&EventName, in:&jsonIN, out:&jsonOUT);
&GAMUser.FromJsonString(&jsonIN)
&MyUser.Load(&GAMUser.GUID) //&Myuser は BC に基づく
If &MyUser.Fail()
&MyUser = new()
Endif
&MyUser.MyUserGUID =&GAMUser.GUID
&MyUser.MyUserEmail = &GAMUser.EMail
&MyUser.MyUserName = &GAMUser.FirstName.Trim() +" "+ &GAMUser.LastName.Trim()
&MyUser.Save()
If &MyUser.Success()
//Ok
Else
//エラーに関する情報を指定して &jsonOUT パラメーターをロード。
Endif
User_GetCustomInfo イベントや User_SaveCustomInfo イベントの例については、「
GAM の ID プロバイダーからユーザーの追加情報を取得する方法」を参照してください。
プロシージャーがサブスクライブしたログインイベントがログイン時にトリガーされる場合、ログインがローカルで行われるかどうかにかかわらず、
そのプロシージャーで追加のコントロールを作成し、ログインをキャンセルしてセッションが生成されないようにすることができます。
たとえば、次のコードをログイン時にトリガーします:
&GAMSession.FromJsonString(&JsonIN)
For each
Where CustomerGUID = &GAMSession.User.GUID
Where CustomerActiveSubscription = True
//OK
When none
&GAMError.Code = GAMErrorMessages.UserInactive
&GAMError.Message = "The user's subscription is not valid."
&JsonOUT = &GAMError.ToJsonString()
Endfor
JsonOut の形式は GAMError である必要があります。JsonOut が空の場合に限り、ログインはキャンセルされません。
内部では、セッションが生成され、直ちに破棄されます。
イベントのサブスクリプションは、次の例に示すように定義できます:
&GAMEventSubscription = new() // &GAMEventSubscription は GAMEventSubscription データタイプ
&GAMEventSubscription.Description = "Inspecting the User Login"
&GAMEventSubscription.Event = GAMEvents.Repository_Login
&GAMEventSubscription.FileName = "aNotifyUserLogin.dll"
&GAMEventSubscription.ClassName = "GeneXus.Programs.anotifyuserlogin"
&GAMEventSubscription.MethodName = "execute"
&GAMEventSubscription.Save()
If &GAMEventSubscription.Success()
Commit
// サブスクリプションのアクティベーション:
&isOK = GAMRepository.SubscribeEvent(&GAMEventSubscription.Id, &GAMErrors)
If &isOK
Commit
Endif
Endif
イベント実行時にトリガーするプログラムを複数定義することもできます。
サブスクリプションは、GAMRepository の SubscribeEvent メソッドを使用して有効にする必要があります。
イベントをサブスクライブしているプログラムをイベントの同じ LUW (論理作業単位) に含めるためには、イベントをトリガーするコード (&GAMUser.save() または &GAMRole.save()) の後に
Commit コマンドを含めます。
これに対して、プログラムを同じ LUW に含めない場合は、プログラムの
[ Execute in new LUW ] プロパティを True に設定します。
Repository_Login メソッドと Repository_Logout メソッドでは、コミットが暗示的に実行されるので、明示的な実行は必要ありません。
同じ LUW 内に含められません。