カスタムイベントリスナー

はじめに

カスタムイベントリスナーは、エンドユーザーによってURLが呼び出されるたびに、ターゲット関数またはCircuitにデータを渡すために使用されます。コンポーネントで発生するイベントをカスタムイベントリスナーに関連付けることはできません。Catalystで作成するイベントリスナーは、コンポーネントイベントリスナーがデフォルトで存在するため、カスタムイベントリスナーになります。

カスタムイベントリスナーの動作を論理的な順序で理解しましょう:

1. カスタムイベントリスナーを作成すると、URLが生成されます。すべてのイベントルールに同じURLが使用されます。このURLをアプリケーションのコードに含めたり、必要に応じて使用できます。
2. カスタムイベントリスナーの各ルールを異なるターゲット関数またはCircuitに関連付けることができます。また、各ルールに対してイベントリスナーのURLのリクエストボディで異なるデータを送信することもできます。つまり、イベントリスナーのURL呼び出しは、毎回各ルールに対して異なる関数またはCircuitをトリガーし、異なるデータを送信するよう設定できます。
3. 複数のルールを同じターゲット関数またはCircuitに関連付け、毎回同じ関数またはCircuitに異なるデータを送信することもできます。これにより、異なるニーズに同じ関数またはCircuitを使用できます。
4. カスタムイベントリスナーのURLが呼び出されたときにどのルールをトリガーするかを識別するために、ルールにはルール識別子と呼ばれる変数が含まれています。カスタムイベントリスナーでルールを作成する際、識別子として一意の値を指定する必要があります。このルール識別子はそのルールにのみ関連付けられ、ターゲット関数またはCircuitをルールに関連付けます。
5. カスタムイベントリスナーはすべてのルールに同じURLを持つため、URLのリクエストボディにルール識別子の値を渡すことで、どのルールを呼び出すかを示すことができます。リクエストボディはJSON（_application/JSON_形式）で、キーをrule_identifierとしたキーバリューペアとしてこの情報を含む必要があります。必要に応じてリクエストボディに追加の情報を渡すこともできます。
6. URLはHTTP POSTメソッドでのみ呼び出すことができます。他のメソッドはリクエストのメッセージボディ内にフォームデータを含めることをサポートしていないためです。
7. イベントリスナーのURLが呼び出されると、Catalystはリクエストボディで指定されたルール識別子を、コンソールで設定されたそのイベントリスナーのルールと照合します。照合が成功すると、Catalystはそのルールをトリガーし、イベントデータをそのルールに関連付けられた関数またはCircuitに渡します。その後、イベントデータはターゲットCircuitまたはイベント関数内で処理され、必要なタスクを実行できます。照合が成功しない場合、失敗イベントとなります。

カスタムイベントリスナーの機能を例を使ってより理解しましょう:

CatalystプロジェクトでカスタムイベントリスナーをCatalystプロジェクトに作成するとします。イベントリスナーのURLは自動的に生成されます。ルール（rule_1）を作成し、ルール識別子の値を_ID1_とします。このルールはトリガーされるとターゲット関数_Func_を実行します。次に、ルール識別子が_ID2_の2番目のルール（rule_2）を作成し、トリガーされると同じ関数_Func_を実行します。つまり、_rule_1_と_rule_2_は同じ呼び出しURLを持ち、同じ関数を実行します。このURLをアプリケーションのロジック内の2つの異なる場所で使用します。

使用例1: ユーザーがクライアントのホームページのフォーム（Form 1）からデータを送信し、URLが呼び出されます。URLのボディのフォームデータでルール識別子をID1として指定します。

使用例2: ユーザーが別のフォーム（Form 2）でデータを送信し、同じURLが呼び出されます。URLのボディのフォームデータでルール識別子を_ID2_として指定します。

CatalystイベントリスナーはこのURLの呼び出しをリッスンしています。ユーザーが_Form 1_を通じてデータを送信すると、URLが呼び出されます。HTTPリクエストのボディには、以下のようにルール識別子を含むフォームデータが含まれます:

{
	"data": "Sample data from Form 1",
	"rule_identifier": "ID1"
}

Catalystがこのイベントをキャプチャすると、ルール識別子_ID1_をプロジェクトで設定された_rule_1_と照合します。照合が成功すると、関数_Func_をトリガーします。その後、以下のサンプルデータパターンでイベントデータを関数に渡します:

{
    "project_details": {
        "id": 57*************,
        "project_name": "Eventbus"
    },
    "event_bus_details": {
        "name": "ThirdPartyBus",
        "id": 13*************
    },
    "data": "Sample data 1",
    "current_project": {
        "id": 57*************,
        "project_name": "Eventbus"
    },
    "action": "Produce",
    "source_entity_id": 570000000003015,
    "rule_identifier": "com.abc",
    "source": "Custom",
    "event_time": 1568192053790
}

ユーザーが_Form 2_を通じてデータを送信すると、リクエストボディのrule_identifierの値が_ID2_として同じURLが呼び出されます。Catalystがこのイベントをキャプチャし、_ID2_を_rule_2_に関連付けると、関連するデータが_Func_に渡されます。データパターンはすべてのカスタムイベントリスナーのルールで同じです。

それでは、カスタムイベントリスナーを作成して設定しましょう。

カスタムイベントリスナーの作成

カスタムイベントリスナーを作成するには:

1. Catalystコンソールの_Amplify_にある_Event Listeners_セクションからCreate Event Listenerをクリックします。
   
   
2. カスタムイベントリスナーの名前と説明を入力します。タイプとしてCustom Eventsを選択します。
   
   
3. Createをクリックします。

カスタムイベントリスナーが作成され、IDとコンポーネントイベントリスナーと同じパフォーマンス統計とともにEvent Listenersページに表示されます。

タイルのViewをクリックしてイベントリスナーの詳細を確認できます。このページからイベントリスナーのURLにもアクセスできます。

カスタムイベントリスナーのURLは以下の形式です:

https://api.catalyst.zoho.com/baas/v1/project/project_id/event-bus/event_listener_id_/produce?ZCFKEY=_zcf_key

Project ID、Event Listener ID、および一意のZCF Keyの値が入力されます。

カスタムイベントリスナーでルールを作成する

カスタムイベントリスナーでルールを作成するには:

1. _Event Listeners_ページからカスタムイベントリスナーをクリックして開きます。

2. Create Ruleをクリックします。
   

3. ルールの名前、説明、およびルール識別子を入力します。
   

ターゲット関数またはCircuitに渡されるデータのサンプル構造がページに表示されます。

4. Target PointとしてFunctionまたはCircuitを選択します:

• Functionsをトリガーする場合:
  ドロップダウンリストからアクションとターゲットイベント関数を選択します。現在、ターゲット関数にデータを渡すためにProduceのみ選択できます。複数のターゲット関数を選択できます。
  
  

• Circuitをトリガーする場合:
  ドロップダウンリストからターゲットCircuitを選択します。現在、ターゲットCircuitにデータを渡すためにProduceのみ選択できます。複数のターゲットCircuitを選択できます。
  
  

5. Createをクリックします。

ルールがカスタムイベントリスナーに作成されます。イベントリスナーのページにその詳細とともに一覧表示されます。カスタムイベントリスナーのソースは常に「custom」です。

一覧からルール名をクリックすると、ルールの詳細とデータパターンが表示されます。

イベントリスナーのルール管理や処理済みイベントについて説明する前に、カスタムイベントリスナーの編集と削除について簡単に説明します。

カスタムイベントリスナーの編集

カスタムイベントリスナーの名前変更や説明の編集は以下の方法で行えます:

1. Event Listenersページからカスタムイベントリスナーを開きます。
2. ページ上部の省略記号メニューをクリックし、Editをクリックします。

3. イベントリスナーの詳細を更新し、Saveをクリックします。

カスタムイベントリスナーの削除

カスタムイベントリスナーを削除するには:

1. Event Listenersページからカスタムイベントリスナーを開きます。
2. ページ上部の省略記号メニューをクリックし、Deleteをクリックします。

3. 確認ポップアップでYes, Proceedをクリックします。