主要な概念

Catalyst Circuitsの実装について学ぶ前に、いくつかの基本的な概念を詳しく理解することが重要です。

Circuitのコンポーネント

Catalyst Circuitのワークフロー設計には、ロジックとデータフローのオーケストレーションを支援するさまざまなコンポーネントが含まれています。

Circuitステート

ステートとは、特定の時点においてCircuitが置かれている特定の状態です。Circuitのそのステージで実行される特定のタスクまたはプロセスを定義します。

Circuitステートは大きく2つのカテゴリーに分類できます。

• フローコントロール: フローコントロールステートは、Circuit内のロジックとデータのフローをオーケストレーションします。Catalyst Circuitsでは以下のフローコントロールステートが利用可能です。
  

  • Pass
  • Branch
  • Parallel
  • Wait
  • Batch
  • Success
  • Failure

• ファンクショナル: ファンクショナルステートは、Circuit内で実行される実際の操作を定義します。Catalyst Circuitsでは以下のファンクショナルコントロールステートが利用可能です。
  

  • Function
  • Circuit

各ステートの詳細については、次のセクションで説明します。

Circuitは実行中にステップバイステップで1つのステートから次のステートに遷移します。Circuit内の各ステート間でロジックとデータフローが発生します。各ステートの設定には以下のプロパティが存在します。

• Previous state: 現在のステートの前に遷移したステート
• Next state: 現在のステートの後に遷移するステート

Circuitの開始はStartというキーで示され、Circuitの終了はEndというキーで、Circuitのスキーマティクスフロー図に示されます。

CircuitのJSONコードでは、ステートがnextキーを記述していない場合、それは最後のステートであり、ステートが他のいずれのステートでもnextとして参照されていない場合、それはCircuitの最初のステートです。サンプルJSONコードスニペットについてはこのセクションを参照してください。

入力、出力、および結果

Catalyst Circuitは一般的に、開始時に入力を受け取り、実行後に出力を提供します。これらはCircuit入力とCircuit出力と呼ばれます。

• Circuit入力: Circuitの実行を開始する際、JSON形式のキーバリューペアとしてCircuitに入力を提供する必要があります。Circuitの機能要素であるBasic I/O FunctionsはJSON形式の入力を処理するため、Circuit入力も同じ形式をサポートしています。開始時に提供された入力は、Circuit内の最初のステートに渡されます。

• Circuit出力: 入力JSONは、ワークフロー設計とアーキテクチャに基づいて、Circuit内のステートを通じて処理・遷移されます。最後のステートが遷移された後、Catalystは実行完了後にCircuitの最終出力を生成します。

コンソールから各実行の詳細な実行ログと履歴を確認できます。

入力JSONを操作して各ステートの処理にカスタム入力を提供したり、必要に応じて各ステートの処理出力の一部を選択して次のステートに渡したりできます。処理されたステートの結果を入力JSONに動的に含めて渡すこともできます。

これらは、Circuitステートの以下のプロパティによって実行されます。

• Input path:
  

入力パスは、ステートの入力の一部を選択し、処理のためにステートのタスクに渡します。例えば、ステートの入力JSONが以下の場合：

{
name: Amelia Burrows
gender: F
age: 33
} 

nameとgender変数のみをステート（例：ファンクション）の入力として送信したい場合、ファンクションの入力パスを$.name,genderと設定できます。これはJSONオブジェクトnameとgenderを入力パスとして参照します。

Catalystは外部のJsonPathライブラリをインポートして、Circuit内のステートの入力パス、出力パス、結果パスを定義します。そのため、パス定義ではJsonPathでサポートされているすべての式を使用できます。JsonPath構文については、GitHubドキュメントを参照してください。

• Output path:

出力パスは、ステートの出力の一部を選択し、処理のために次のステートに渡します。例えば、ステートの出力JSONが以下の場合：

[
26,
"John Kemper",
  {
    "streetAddress": "Sunshine Avenue",
    "city": "Austin",
    "postalCode": "630-0231"
   }
]

出力からageとnameオブジェクトの値（26、John Kemper）のみを選択して次のステートに渡すには、ステートの出力パスを$.age,nameと設定します。

• Result path:

結果パスは、ステートの入力の一部とステートの実行結果を組み合わせて、ステートの出力とします。つまり、ステートの結果をステートに提供された入力JSONに追加し、JSONを変更できます。この変更されたJSONをステートの出力として次のステートの処理に渡すことができます。

例えば、Circuit内のファンクションがpresentDaysとtotalWorkingDaysという2つのオブジェクトを含む入力JSONを処理するとします。ファンクションの処理出力は、出力内のattendancePercentageという変数に割り当てられる新しい値を生成します。

attendancePercentageで得られた値を元のJSONに含めたい場合、結果パスを$.attendancePercentageと指定できます。JSONは以下のように変更されます。

[
  	180,
  	200,
  	90
	]

ここで、presentDaysの値は180、totalWorkingDaysは200、attendancePercentageは90です。

この出力を次のステートの処理に渡すことができます。

Circuitステート

前述の通り、Circuitステートはフローコントロールステートまたはファンクショナルステートにグループ化できます。各ステートの詳細と、利用可能な設定について学びましょう。

これはCircuitの_Builder View_です。このセクションでは、参考のために各ステートで利用可能な設定の画像を表示します。Circuitの作成とステートの追加手順については、実装セクションを参照してください。

Function

ファンクションステートは、Basic I/O Functionを表すファンクショナル要素です。ファンクションステートはCircuitのコア要素であり、ロジックの大部分がここで処理されます。他のすべてのフローコントロールステートは、Circuit内のファンクション処理を操作・カスタマイズするのに役立ちます。

コンソールでCircuitを設定する際に、Circuit内のすべてのステートの名前を入力し、タイプを選択し、次のステートを選択できます。設定ウィンドウの下にあるDelete Stateをクリックして、特定のステートを削除できます。

ファンクションステートを選択すると、ドロップダウンリストからCatalystプロジェクトに設定されているBasic I/O Functionとリンクできます。

エラー処理:

ファンクションステートは、ファンクション実行中に頻繁に発生するエラーを処理するためのエラー処理をサポートしています。On TimeOut、On Authorization Failure、またはOn Execution Failureエラー時に実行されるアクションを設定できます。

エラーのチェックボックスをクリックして有効にします。3つのエラーハンドラーはすべて、RetryとFallbackの2つのデフォルトアクションをサポートしています。RetryまたはFallbackをクリックして有効にします。

リトライオプションは、特定のエラーが発生した場合にファンクション実行を再試行します。リトライでは以下のプロパティを設定できます。

• Delay: 最初のリトライを試みる前の待機時間を定義します
• Attempt: リトライ試行回数を定義します
• Step Delay: 各試行間の待機時間を定義します

フォールバックオプションは、すべてのリトライが失敗した場合に実行するアクションを設定するために使用されます。リトライが失敗した場合に、Circuit内の別のステートにフォールバックすることを選択できます。

ドロップダウンリストからフォールバック先のステートを選択します。_Result_にエラートレースのパスをJsonPath構文で入力します。リトライ試行が失敗した場合、Circuitはここで設定されたステートに設定され、エラートレースが生成されます。Saveをクリックしてハンドラーを保存します。

3つのデフォルトエラー（On TimeOut、On Authorization Failure、On Execution Failure）のエラーハンドラーは、すべて同じアクションと設定を持ちます。

これらのデフォルトエラーハンドラーに加えて、カスタムエラーを定義し、そのエラーを受信した際に発生するアクションを処理できます。特定のエラーが発生した場合のカスタムエラーハンドラーを処理するようにファンクションをコーディングできます。

ステートの設定内の_Error Handling_の下にあるAdd Custom Errorをクリックします。

ポップアップウィンドウのヘッダーにカスタムエラーの名前を入力します。例外タイプとしてError CodeまたはError Messageを選択できます。いずれの場合も例外値を指定します。これはエラー発生時に表示されるエラーメッセージまたはコードです。

デフォルトのエラーハンドラーと同様に、カスタムエラーに対してもRetryとFallbackの両方を有効にして設定できます。設定後にSaveをクリックします。

削除アイコンをクリックしてカスタムエラーを削除できます。

CatalystはBasic I/O Functionの200番台（200-299）のすべてのHTTPステータスコードを実行成功とみなします。ファンクションがレスポンスで200番台以外のステータスコード（例：502）を返した場合、Circuitsはファンクションのエラー処理設定でカスタムエラーハンドラーの一致を確認します。一致が見つかった場合、設定されたロジックが実行されます。エラーコードが処理されていない場合、Circuit実行は失敗とみなされます。

エラーメッセージを設定した場合、ファンクションのロジック内で必要に応じて処理できます。

入力/出力:

このセクションで説明した通り、ファンクションステートの入力パス、出力パス、結果パスを設定できます。このセクションからファンクションに渡す個別のパラメータも設定できます。

入力パスを使用して、ファンクションに渡すJSON Circuit入力から特定のパラメータセットを選択できます。

例えば、Circuitに渡される入力JSONが以下の場合：

"personalDetails":{
      "name":"Patricia Boyle",
      "age" : 26,
	   "address":"13, Orchid Lane, NY"
	},
"company":"Zylker Corporation",
"empDetails":{
"department":"Sales",
"designation":"Sales Manager"
}

Circuit内に設定されたファンクションにそのペイロードとして入力全体を渡す必要がある場合、Circuitの開始時にデフォルトの方法でCircuitに渡すことができます。この入力のキーバリューペアは、ファンクションのパラメータとして自動的に渡されます。

特定のパラメータセットのみをファンクションに渡す必要がある場合、入力パスにパラメータセットのキーを設定できます。例えば、companyとempDetailsパラメータのみを渡すには、JsonPath構文を使用してファンクションへの入力パスを$.company,empDetailsと指定します。

_Parameters_オプションを使用して、ファンクションに渡す個別のパラメータを選択することもできます。このオプションでは、JSON Circuit入力に存在しない追加の値をファンクションに渡すこともできます。Add Parametersをクリックしてパラメータと値を追加します。

例えば、nameとdesignationのみをパラメータとしてファンクションに渡すことを選択できます。nameとdesignationをパラメータキーとして設定し、JsonPath構文でパラメータ値としてパスを入力します。Removeをクリックしてパラメータを削除できます。

Catalyst Basic I/O Functionのレスポンスは、キーoutputを使用してファンクションの出力を配信します。Circuit内でファンクションを設定する際、ファンクションの出力パスや結果パスにoutputキーを明示的に指定する必要はありません。

Catalystはデフォルトで処理し、出力値を自動的に配信します。ファンクションの出力を後続のステートに渡すようにCircuitが設定されている場合、Catalystは追加の設定なしに自動的に出力をペイロードとして渡します。

例えば、ファンクションの以下のJSON出力は、

[
180,
90
]

Circuit実行中にペイロードとして、Circuit内の次のステートへのJSON入力として渡されます。

Circuitの実行ログは、ファンクションステートについて、実行されたファンクションと、その特定のファンクションのログを含むCatalyst Logsへのリンクを提供します。

Circuit

Circuitステートは、ネストされたCircuitを表します。親Circuit内で別のCircuitを処理できます。Circuitステートがトリガーされると、Catalyst Circuitsで設定された通りに子Circuitが実行されます。

子Circuit内にさらにネストされたCircuitを持つこともできます。これにより、複雑なワークフローパターンに対して1つの複雑なCircuitを設定するのではなく、異なる目的のためのシンプルで独立したCircuitを設定し、相互にネストすることが可能です。

Circuitステート内の_Circuit Name_ドロップダウンボックスから、参照名を使用して子Circuitを選択できます。Circuitステートに対して親Circuit自体を選択することもできます。これにより、ロジックを設定可能なループで同じCircuitが実行されます。

Circuitステートも、ファンクションステートと同様にデフォルトエラーハンドラーとカスタムエラーハンドラーをサポートしています。ただし、ファンクションステートとは異なり、CircuitステートのデフォルトまたはカスタムエラーハンドラーにはRetryという1つのアクションのみがあります。リトライとカスタムエラーハンドラーの情報については、Functionセクションを参照してください。

すべてのリトライ操作が失敗した場合に実行するアクションのロジックを独自に記述できます。例えば、Circuitを再実行するか、終了して問題に関する通知を送信するようにコーディングできます。

前のセクションおよびFunctionステートで説明した通り、入力パス、出力パス、結果パスを設定してCircuitステートを通過するJSONデータを操作できます。

Circuitの実行ログは、簡単に参照できるように、ネストされたCircuitのログへのリンクも提供します。

Pass

Passステートは、Circuit内のあるステートから別のステートにデータを渡すフローコントロールステートです。デフォルトでは、前のステートからのJSON入力データをそのまま次のステートに渡します。

前のセクションで説明した通り、入力パス、出力パス、結果パスを設定して、Passステートを通過するJSONデータを操作できます。例えば、入力パスを設定して、JSONデータの一部のみを次のステートに渡すことができます。

Passステートには、入力パス、出力パス、結果パスに加えて、resultという新しいプロパティもあります。これは他のステートでは利用できません。

resultプロパティにより、JSONに新しいオブジェクトを追加し、変更されたJSONを次のステートに渡すことができます。

例えば、name、age、genderオブジェクトを含む入力JSONに、Passステートの結果パスとして$.locationという新しいパラメータを追加できます。resultボックスにlocationの値を入力できます。変更されたJSONには、name、age、gender、locationオブジェクトが含まれます。

Branch

Branchステートは、Circuitのワークフローに条件を設定し、それらの条件に基づいてタスクを実行することを可能にします。入力データが特定の基準セットを満たす場合、Circuitのフローに分岐を作成し、各分岐で異なるステートを実行できます。

例えば、Circuit内のBranchの前のステートの出力がJSONオブジェクトstatusの値をcompleteまたはincompleteとして生成すると仮定します。statusがcompleteの場合、CircuitがSuccessステートに遷移する必要があります。statusがincompleteの場合、CircuitがFailureステートに遷移する必要があります。

この結果を達成するには、条件を$.status == ‘complete’として追加し、「Go To」をSuccessステートに設定します。同様に、別の条件を$.status==‘incomplete’として追加し、Failureステートに設定します。

Add Conditionをクリックして条件を追加し、条件を入力してその分岐の次のステートを選択できます。必要なタイプとしてそのステートを設定します。Removeをクリックして条件を削除できます。

Catalystでは、Branchステートの条件文に以下の演算子がサポートされています。

条件文は以下の組み込み関数もサポートしています。

条件内でオブジェクトのパスにアクセスするためにJsonPath構文も使用できます。

Branchステートには、Branchステート全体の次のステートとリンクできるデフォルトパスウェイがあります。設定された条件がいずれも満たされない場合、デフォルトの分岐が辿られ、そのステートが実行されます。

前述の通り、Branchステートの入力パスと出力パスを設定できます。

Parallel

Parallelステートは、順次ではなく複数のステートを並列で処理することを可能にします。

2つのステートを並列で処理するように割り当てると、両方のプロセスが同時に開始され、入力、出力、結果が同時に処理・生成されます。ステートも同時に終了します。Circuitが実行された後、実行ログから並列処理を確認できます。

例えば、2つのファンクションを並列で実行する必要がある場合、それぞれに2つのステートを追加し、Parallelステート内のパスとして設定できます。

Add Pathをクリックして、並列処理で実行する必要がある各ステートのパスを追加します。パスの名前を入力し、ステートタイプを設定できます。

前述の通り、Parallelステートの入力パス、出力パス、結果パスを設定できます。

Wait

Waitステートは、Circuitの実行を特定の時間一時停止し、再開して次のステートに遷移することを可能にします。

例えば、前のステートの処理後に3秒の遅延でファンクションの実行をトリガーする必要がある場合、これを使用できます。設定で遅延時間を秒単位で設定できます。

前述の通り、Waitステートの入力パスと出力パスを設定できます。

Batch

Batchステートは、ファンクションまたはCircuitをバッチとして反復的に複数のジョブで実行することを可能にします。バッチ処理により、大量の入力やタスクをセットで処理し、サーバーに過大な負荷がかからないようにできます。

入力にJSONオブジェクトの配列が含まれている場合、Batchステートを使用して各JSONオブジェクトを同時に処理できます。このBatchステートにより、設定されたジョブ数に基づいて、関連付けられたファンクションまたはCircuitが並列で複数回トリガーされます。

例えば、Basic I/O Functionが多数の顧客にメールを送信するように設定されている場合、Batchステートで処理し、ジョブ数を10に設定することで、1回のイテレーションでファンクションが10回同時に実行されます。10のジョブが実行されると、次のイテレーションで別の10のジョブが開始されます。ファンクションまたはCircuitの複数のインスタンスが実行されるため、タイムアウトエラーが発生しないことが保証されます。

バインドタイプとドロップダウンリストからCircuit参照名またはファンクション名を選択して、Batchステートを特定のファンクションまたはCircuitにバインドできます。Batchステートの以下のプロパティを設定できます。

• Collection path: JsonPath構文で記述されたJSONリストを含むパス
• Collection variable: JSON出力を格納するために割り当てられた変数

例えば、JSON入力に以下のように2つのJSONオブジェクトのリストが配列として含まれているとします。

{
"userList":[{"name":"Paul"},{"name":"Max"}]
}

この入力をファンクションに関連付けられたバッチに渡します。コレクションパスを$.userlistと定義し、リスト配列を含むオブジェクトがそのパスにあることを示します。コレクション変数をuserと入力し、出力を保持する変数として割り当てます。

ジョブ数を2と入力すると、nameオブジェクトを返す関連付けられたファンクションが2回並列で呼び出され、入力が渡されます。最初のイテレーションの出力は以下のように生成されます。

{
"userList": [{"name": "Paul" },{"name": "Max"}],
"user":{"name": "Paul"}
}

2番目のイテレーションの出力には、nameパラメータにMaxの値が割り当てられています。

{
"userList": [{"name": "Paul" },{"name": "Max"}],
"user":{"name": "Max"}
}

両方のイテレーションは同時に実行されます。バッチの結果パスに$.userlistを割り当てると、JSONリストを含む出力を次のステートに渡すことができます。

Catalystは、Batchステートで最大10のジョブを実行できます。これはバッチの設定で定義できます。

Batchステートは、Circuitステートと同様にデフォルトおよびカスタムエラーハンドラーをサポートしています。デフォルトまたはカスタムエラーハンドラーには、Retryという1つのアクションがあります。リトライとカスタムエラーハンドラーの情報については、Functionセクションを参照してください。

すべてのリトライ操作が失敗した場合に実行するアクションのロジックを独自に記述できます。例えば、Circuitを再実行するか、終了して問題に関する通知を送信するようにコーディングできます。

Batchステートの入力パス、出力パス、結果パスを設定できます。

ファンクションステートと同様に、Batchステートで処理されるファンクションに動的にパラメータを渡すこともできます。詳細はFunctionセクションを参照してください。

Circuitの実行ログは、Batchステートについて、実行されたファンクションまたはCircuit、およびそのファンクションのログを含むCatalyst Logsへのリンクを提供します。

Success

Successステートは、Circuit内で実行された前の操作またはタスクの成功を判定するために使用される終了ステートです。ユーザーの参考のために実行の成功を表すために使用されます。

例えば、分岐内でFailureステートとともにSuccessステートを使用して、異なる条件に基づく2つのプロセスの結果を示したり、ファンクション実行の後に使用して実行の成功を示したりできます。

Successステートは、そのCircuit内の特定のパスの最終ステートであるため、設定やプロパティはありません。その後に次のステートを設定することはできません。

Successステートに対して入力パスや出力パスを設定することもできません。

Failure

Failureステートも、Circuit内で実行された前の操作またはタスクの失敗を判定するために使用される終了ステートです。ユーザーの参考のために実行の失敗を表すために使用されます。

Successステートと同様に、また他のシナリオでもプロセスやタスク実行の失敗を示すためにFailureステートを使用できます。

Failureステートは、そのCircuit内の特定のパスの最終ステートであるため、次のステートを設定することはできません。このステートが遷移された場合の参考のために、エラーメッセージとオプションの理由を指定できます。

Failureステートに対して入力パスや出力パスを設定することはできません。

JSONコード

前述の通り、コンソールからJSON形式でCircuitを直接コーディングすることもできます。

_Code View_セクションでは、コードを直接操作できます。フロー図でステートをドラッグ＆ドロップすると、コードが自動的に生成されます。詳細は実装セクションを参照してください。

ステート名はJSONオブジェクトであり、そのプロパティはそのオブジェクトのキーバリューペアです。typeやnextなどのプロパティは、すべてのステートで共通に使用されます。ステートがnextキーを記述していない場合、それはCircuit内の最後のステートです。ステートが他のいずれのステートでもnextとして参照されていない場合、それはCircuitの最初のステートです。

Circuitのコーディング時には、標準のJSON構文に従う必要があります。

以下はCircuitのサンプルコードスニペットです。

Circuit URL

CatalystプロジェクトでCircuitを作成すると、一意の呼び出しURLが自動的に生成されます。このエンドポイントURLからCircuitをトリガーできます。このURLをアプリケーションのコードに実装したり、必要に応じて使用できます。

Circuitの URLはコンソールから取得できます。

Circuit URLは以下の形式です：

https://project_domain_name.environment_type.zohocatalyst.com/baas/v1/project/_project_ID_/circuit/circuit_ID/execute

このURLはHTTP POSTメソッドで呼び出す必要があります。

project_domain_nameはプロジェクトのドメイン名です。environment_typeは、開発環境で作業している場合はdevelopmentです。それ以外の場合、environment_typeはURLに含まれません。