Scenario

開発の核となるプラグイン開発機能です。ワークフローを作成することができ、即座にAPIとして公開することも可能です。

Qmonus SDKで公開するマイクロサービスは、このScenarioリソースで作成します。Scenarioは、Frontalが提供するシナリオエディタ上でエンドポイントを定義し、ワークフローを作成することですぐにAPIとして公開することができます。

Scenarioは、ランタイムでトランザクションサービスと連携し、ワークフローの途中でクラッシュした場合のロールバックなどフロー制御をトランザクションサービスに委任できます。開発者は、フローエディタで正常な処理とエラー発生時のキャンセル処理を記述する必要がありますが、正常とエラー処理を分離して記述できるため処理を簡素化できます。

シナリオが保有する属性

属性	概要	備考
`workspace`	プラグインのワークスペースです。	詳細については、`Docs » リファレンス » ワークスペース`の章を参照してください。
`name`	シナリオの名前を指定します。	ユニークである必要があります。
`category`	シナリオのカテゴリを指定します。	シナリオを分類するためのラベルですが、カテゴリと同一名称の`Config`サービスを定義している場合、シナリオが呼び出されたときに自動的にシナリオの名前空間にインポートされます。詳細については、`Docs » 名前空間 » リファレンス » Scenarioにおけるプログラミング`の章を参照してください。
`method`	APIとして待機するHTTPメソッドを指定します。	-
`URI`	APIとして待機するHTTPパスを指定します。	-
`connect_timeout`	HTTPリクエストの接続タイムアウト値をAPIとして指定します。	シナリオを登録すると、当該シナリオAPIに向けるルーティング情報がAPI Gatewayに自動的に追加されます。その際、ルーティングの接続タイムアウト値はこの値で自動設定されます。
`request_timeout`	HTTPリクエストの要求タイムアウト値をAPIとして指定します。	シナリオを登録すると、当該シナリオAPIに向けるルーティング情報がAPI Gatewayに自動的に追加されます。その際、ルーティングの要求タイムアウト値はこの値で自動設定されます。上限は設定していませんが、極端に大きい値はメモリを圧迫する恐れがあるため注意が必要です。
`transaction mode`	トランザクションモードを指定します。	トランザクションモードを有効にしてステートフルなAPIにする場合は、`sync`または`async`のいずれかを指定できます。無効にすると、トランザクションサービスとは連携しません。 `sync`の場合、シナリオが呼び出された後、トランザクションがコミットされるかキャンセルが完了するまで、応答はブロックされます。処理中にクライアントがクラッシュしても、トランザクションの状態は維持されます。その場合、リカバリとキャンセルはトランザクション管理画面から実行するか、`Abort hook`でリカバリを自動化する必要があります。`sync`モードは、ロングトラザクションには適していないため、お勧めしません。
`xdomain`	トランザクションのドメインを指定します。	-
`xtype`	トランザクションのタイプを指定します。	-
`xname_use_counter`	トランザクション名の自動割り当てにカウンターサービスを使用するかどうかを指定します。	-
`xname`	トランザクション名を指定します。	カウンターを使用する場合は、カウンター名を指定してください。また、1ライナーのカスタムスクリプトを使用して生成することもできます。
`trasaction_timeout`	トランザクションのタイムアウトを指定します。	指定しない場合、起動パラメータ`--transaction_timeout`の値がデフォルトで適用されます。起動パラメータのデフォルトは`600秒`です。
`auto_rollback_mode`	自動的にロールバックを実行するかどうかを指定できます。	トランザクションモードの場合、シナリオの実行中にエラーが発生し中断した際にすぐに`cancel`に遷移してロールバックを実行するかどうかを指定できます。デフォルトは`False`です。
`auto_begin_mode`	トランザクションを自動的に開始するか、開発者が意図したタイミングで開始するかを指定します。	デフォルトは`True`です。`True`の場合にいつトランザクションを開始するかはワークフローの先頭のコマンドに依存します。先頭のコマンドが`request_validation`コマンドである場合、トランザクションの開始は次のコマンド開始時に行われます。先頭が`request_validation`でない場合は、トランザクションの開始が最初に行われてからコマンドが実行されます。これは`request_validation`が要求の妥当性チェックをするためのものであり、チェックエラーの場合は、`400 Bad Reqeust`を返却するため、トランザクションの開始を遅らせる必要があるからです。一方`False`に設定するケースは、リクエストのバリデーションがjsonschemaだけで実施仕切れないケースや実施できたとしてもエラーをカスタムのものにしたい場合です。その場合は、`False`にしてバリデーションを実装したコマンドの最後を`await context.qumons.begin()`とすることで開発者が意図したタイミングでトランザクションを開始してください。
`auto_response_mode`	HTTP自動応答モードを指定します。	`True`の場合、トランザクションの開始時に自動応答が返却されます。`False`の場合、開発者が意図したタイミングでカスタム応答を返すことができます。デフォルトは`True`です。`False`に設定した場合は、`context.session.finish`を使用してHTTPレスポンスを返却するようにしてください。返却しない場合は、APIクライアントがタイムアウトします。
`lock_keys`	ロックするキーを指定します。	トランザクションの開始時に指定されたリソースはロックされています。ワークフローの途中でロックを追加したり、解除したりすることも可能ですが、デッドロックを回避するためなるべく初期に全てのロックを取得するように設計することをお勧めしています。
`lock_retry_count`	ロックを取得できない場合の再試行回数を指定します。	デフォルトは`0`回です。
`lock_retry_interval`	ロックを取得できない場合の再試行間隔を指定します。	デフォルトは`0`秒です。
`transaction_callback_url`	コールバックURLを指定します。	トランザクション状態が決定されたときに指定されたコールバックURLにトランザクション情報をPOSTできます。
`transaction_callback_path_combine_with`	コールバックURLにトランザクションの識別子を指定できます。	トランザクション状態が決定されたときに`transaction_callback_url`にトランザクション情報がPOSTされますが、POST時のリクエストパスにトランザクションの識別子を指定させたい場合に`xid`もしくは`xname`を選択できます。
`transaction_callback_xglobals_only_body`	コールバックの本文を`xglobals`のみにするかどうかを指定します。	トランザクション状態が決定されたときに`True`の場合は`xglobals（シナリオのグローバル変数空間）`のみがPOSTされます。`False`の場合、xglobalsを含むすべてのトランザクション情報が本文に設定されます。
`additional_paths`	`URI`で指定した待ち受けパス以外に複数の待ち受けパスを設定したい場合に指定します。	シナリオを保存した際に`URI`で指定したリクエストパスへのルーティング登録がAPI Gatewayに対して行われますが、`additional_paths`が設定されている場合はそれらに該当するルーティング情報も登録されます。
`global_variables`	シナリオのグローバル変数を指定します。	シナリオでは複数のコマンドを配置できますが、コマンドを跨いで利用する変数はここで宣言する必要があります。グローバル変数は、トランザクションサービスへのバックアップの対象にもなります。複数のシナリオやデーモンで同じグローバル変数定義のセットを共有したい場合は、`VariableGroup`サービスを使用すると良いでしょう。
`routing_auto_upload_mode`	API Gatewayへのルーティング自動登録をするか否かを指定します。	デフォルトは`True`です。`False`の場合、開発者はルーティングをプラグインとして個別に定義する必要があります。ルーティングプレーンを切り替える操作をしたい場合やアクションパイプラインをカスタマイズしたい場合は、`False`に設定してください。
`routing_scope`	`routing_auto_upload_mode`が`True`の場合、自動登録されるルーティングのスコープを指定できます。	デフォルトは`local`スコープです。
`routing_spec`	`routing_auto_upload_mode`が`True`の場合、自動登録されるルーティングのAPI仕様を定義できます。	API仕様を定義した場合、API Gateway側でバリデーションが実行されます。

Note

transaction_callback_path_combine_withを設定した場合、以下のようにコールバックエンドポイントを変更します。

# transaction_callback_path_combine_with を xid で指定した場合
transaction_callback_url: http://apigw:9099/example/callbacks
transaction_callback_path_combine_with: xid
実際のコールバックエンドポイント: http://apigw:9099/example/callbacks/{xid}

Caution

workspaceについて

workspaceは各種プラグインの定義ファイルが格納されるディレクトリのような概念を指します。詳細はDocs » リファレンス » ワークスペースの章を参照してください。
また、一度リソースを保存したものについてはworkspaceの変更ができません。
こちらはworkspaceを指定せずに保存した場合でも同様であり、この場合はworkspace未指定の状態から変更することができなくなります。変更が必要な場合は新しく作成するなどの手法で変更してください。

Command

シナリオは、1つ以上のコマンドで構成されます。コマンドは、組込みコマンドとカスタムコマンドが提供されています。

単一コマンドのフロー制御

すべてのコマンドは、AOP Settingと呼ばれる個別のフロー制御にラップされています。処理フローは次のとおりです。

Pre condition
コマンド実行のすべきかどうかを判断する条件判定ブロックです。記述されたPython式がFalseの場合、コマンド本体は実行されません。
Pre processing
コマンド実行の前処理が記述できるブロックです。
Post condition
コマンド実行の事後状態が正常化否かを判断する条件判定ブロックです。
Post processing
コマンド実行の後処理が記述できるブロックです。
Repeat
コマンド実行の繰り返し条件を記述するブロックです。
Break condition
コマンド実行の繰返しを終了する条件を記述するブロックです。ブール値を返すPython式を設定します。
Continue condition
コマンド実行の繰返しの中で実行をスキップする条件を記述するブロックです。ブール値を返すPython式を設定します。
Except condition
例外を発生させるべきか否かを判断する判定ブロックです。Python式がTrueの場合、例外を送出し、トランザクションを中断します。
Command implementation
コマンド自体の実行です。scriptコマンドの場合は繰り返しや事前事後の処理自体を自由に記述できるため、Pre condition以外のブロックはほとんどのケースで利用されていません。

組込みコマンド

組込みコマンドは以下が提供されています。現在はrequest_validation、script、break point、serveコマンドのみが利用されているケースがほとんどです。それ以外のコマンドは後方互換のために残置されていますが、将来サポートされなくなる可能性があります。シナリオ全体の可読性や可搬性を考慮し、scriptコマンドを主体にプログラミングすることを推奨しています。

category	command	description
Transaction	lock `非推奨`	トランザクションロックを追加獲得する
	unlock `非推奨`	トランザクションロックを部分解除する
	allocate counter `非推奨`	カウンタ値を取得します
Scenario	request validation	HTTPリクエストをバリデーションする
	script	Pythonスクリプトを実行する
	sleep	スリープする
	break point	ワークフローを中断する
	open remote file `非推奨`	リモートホスト上のファイルを開く
	render template `非推奨`	テンプレートにレンダリングする
	snmp get `非推奨`	SNMP GetでMIBオブジェクトを取得する
	snmp bulk get `非推奨`	SNMP Bulk GetでMIBオブジェクトを取得する
Lambda	regist device `非推奨`	Device情報を登録する
	unregist device `非推奨`	Device情報を削除する
	get device `非推奨`	Device情報を取得する
	southbound callout `非推奨`	CLIプロキシを呼び出す
	parallel southbound callout `非推奨`	CLIプロキシを多重で呼び出す
	lambda event `非推奨`	イベントを発生させる
API Gateway	callout `非推奨`	HTTP呼び出しをする
	parallel callout `非推奨`	並列でHTTP呼び出しをする
	status poll `非推奨`	HTTPポーリングをする
	parallel status poll `非推奨`	並列でHTTPポーリングをする
	serve	ワークフローの途中でトランザクションをサスペンドし、指定されたリクエストパスでリダイレクトを待ち受ける詳しくは`https://docs.sdk.qmonus.net/tutorial/tutorial3/`を参照ください。

Note

初心者向けの組込みコマンドが用意されています。シナリオエディタに配置し、使用するパラメータを設定するだけです。ほとんどの上級ユーザーは、 script、request_validationと breakpoint、serveのみを使用します。したがって、将来的に組み込みコマンドを追加する予定はありません。

Tip

トランザクションモードおよびauto_begin_mode=Trueの場合、トランザクションはシナリオの開始時に自動的に開始されます。ただし、最初にrequest_validationコマンドを配置すると、コマンドを終了したときにトランザクションが開始されます。

request validationの設定例

HTTP header schema: HTTP headerのバリデーションを設定します。以下は設定例です。

{
    "type": "object",
    "properties": {
        "X-Xaas-Test": {
            "type": "string"
        }
    },
    "required": [
        "X-Xaas-Test"
    ]
}

HTTP body schema: HTTP bodyのバリデーションを設定します。以下は設定例です。

{
    "type": "object",
    "properties": {
        "id": {
            "type": "integer"
        },
        "password": {
            "type": "string"
        }
    },
    "required": [
        "id",
        "password"
    ]
}

HTTP query schema:HTTP queryのバリデーションを設定します。以下は設定例です。

{
    "type": "object",
    "items": {
        "name": {
            "type": "string"
        }
    },
    "required": [
        "name"
    ]
}

Exception handling: request validationで発生したエラーを処理します。発生したエラー内容は値「e」にValidationErrorとして渡され、e.messageでエラーメッセージを取得することが可能です。
Errorクラスを使用することでエラー内容をカスタマイズすることが可能です。

raise Error(
    400,
    reason=f"ValidationError!!: {e.message}",
    moreInfo=f"{e}"
)

キャンセレーション動作

コマンドはキャンセル動作を設定できます。シナリオとデーモンは、ダウンストリーム方向にコマンドを順番に実行します。ワークフローが途中で中断され、トランザクションサーバからキャンセルが実行された場合、中断されたコマンドのキャンセレーション動作が実行されます。キャンセレーション動作が正常に完了するとアップストリーム方向に順番にコマンドのキャンセレーションが実行されます。

キャンセルオプションには、以下の設定項目があります。

cancellable: キャンセルの可否を指定します。Trueの場合、キャンセルアクションを適用します。Falseの場合、キャンセルできないため処理が中断され、トランザクションが再度中断されます。ワークフローによっては、ある時点までロールバックすることが可能でもそれ以降はロールフォワードのみが許可される場合があります。このような場合は、ロールバックできないコマンドにFalseを設定してください。cancellable=Falseにもかかわらずトランザクションロックを強制的に解除する必要がある場合は、トランザクションキャンセル時にcancel_mode=breakthroughを指定することで強制的にキャンセルすることができます。

actions:

キャンセル操作を指定します。API呼び出しまたはカスタムスクリプトを記述できます。

Learn More

シナリオのプログラミングについてはDocs » リファレンス » ビルトインオブジェクトやDocs » 名前空間 » リファレンス » Scenarioにおけるプログラミングを参照してください。

Workflow demonstration movie