Qmonus SDK 拡張ヘッダについて
本ページではAPI実行時に使用可能な拡張ヘッダについて簡単に解説します。拡張ヘッダは開発者が意識して使う頻度は多くない想定ですが、機能としてお使いいただくことは可能です。
x-xaas-api-key
ログオンAPIを実行する際にAPI鍵を指定します。
詳しくは認証・認可を参照ください。
x-auth-token
外部から公開されたAPIを呼び出す際に取得したAPIトークンを指定します。
詳しくは認証・認可を参照ください。
x-xaas-illusion
Scenarioをx-xaas-illusionで指定したIllusion空間で実行します。
詳しくはテスト駆動型開発を参照ください。
x-xaas-schedule-datetime
時刻を指定することでScenarioを予約登録します。
詳しくはWebフック予約を参照ください。
x-xaas-direct-routing
X-Xaas-Direct-Routingで指定されたURLに転送します。
x-xaas-static-routing
ルートエントリのターゲットエンドポイントをx-xaas-static-routingで指定されたエンドポイントに変換します。
Scenarioからcalloutで使用する場合、static_routeの引数に指定した値がセットされます。
詳しくはAPIルーティングを参照ください。
x-xaas-xid
Transactionを区別するための拡張ヘッダです。
xidはget_transactions関数で取得が可能です。
x-xaas-scenario-cancellable
PUT /xaas APIを使用してabortしたtransaction処理を操作する場合において、処理の進行方向(cancelまたはrecovery)を指定できます。
followまたはbreakthroughの指定が可能です。
followの場合、操作はcancelableオプションに従いますが、breakthroughが指定されている場合は無視されます。
x-xaas-scenario-resume-index
Scenarioを指定したToyblockから実行します。
Transaction Modeがenableの場合にのみ使用可能です。
r = await callout("/test", method="POST", headers={"x-xaas-scenario-resume-index": "2"})
x-xaas-scenario-suspend-index
Scenarioを指定したToyblockで停止します。
Transaction Modeがenableの場合にのみ使用可能です。
r = await callout("/test", method="POST", headers={"x-xaas-scenario-suspend-index": "2"})
x-xaas-scenario-breakpoint
Scenarioの指定したToyblockにbreakpointを作成します。
Transaction Modeがenableの場合にのみ使用可能です。
r = await callout("/test", method="POST", headers={"x-xaas-scenario-breakpoint": "2"})
x-xaas-scenario-breakaction
Scenarioがbreakpointで停止した際の動作を指定します。
x-xaas-scenario-breakpointと併用することで続けてcancelやrecoveryを実施することが可能です。
Transaction Modeがenableの場合にのみ使用可能です。
r = await callout("/test", method="POST", headers={"x-xaas-scenario-breakpoint": "2", "x-xaas-scenario-breakaction": "cancel"})
r = await callout("/test", method="POST", headers={"x-xaas-scenario-breakpoint": "2", "x-xaas-scenario-breakaction": "recovery"})
x-xaas-callback-url
Transaction完了後、設定したURLにTransaction情報をPOSTします。
Scenarioで実装されているtransaction_callback_urlと同等の機能を提供します。
転送先URLが「指定したURL/{xid}」になるため、POST先のRouting設定が必要になります。
送信するTransaction情報はRequest.Bodyに設定されます。
Transaction Modeがenableの場合にのみ使用可能です。
r = await callout("/test", method="POST", headers={"x-xaas-callback-url": "/callback"})
# POSTされるTransaction情報の例
{'xid': 'xxxxxxxxx', 'xname': 'xxxxxxxxxx', 'xdomain': 'Default', 'xtype': 'testScenario', 'native': {'scenario_name': 'testScenario', 'instance': 'instance123456789', 'length': 3}, 'timeout': 600, 'expire_callout': None, 'checkpoint_recovery': 'lastone', 'checkpoint_cancel': 'all', 'callback': {'url': '/callback', 'xglobals_only_body': False, 'path_combine_with': 'xname'}, 'email': None, 'status': 'Complete', 'transitions': [{'begin': 'Processing', 'timestamp': '2023-01-01T12:00:00.261846+09:00'}, {'commit': 'Complete', 'timestamp': '2023-01-01T12:00:00.486373+09:00', 'reason': 'All process completed.'}], 'create': '2023-01-01T12:00:00.261846+09:00', 'crash_recovery_policy': 'Idempotency', 'expires': '2023-01-01T12:00:00.272019+09:00', 'destroy_time': '2023-01-01T12:00:00.486313+09:00', 'previous_status': 'Processing', 'xglobals': {'instance': '1b01c4ac4d1c11eea6cb56e11ce90430', 'POST': 'POST', 'PUT': 'PUT', 'DELETE': 'DELETE', 'GET': 'GET', 'PATCH': 'PATCH', '__ENDPOINT__': {'url': 'http://apigw:9000/test', 'method': 'POST'}, 'xid': 'xxxxxxxxxx', 'xname': 'xxxxxxxxxx', '_cancellations': []}}
x-xaas-trace-id
実行結果をRedisに転送します。
Redisにアクセスし、対象のPUBSUBチャンネルをサブスクライブすることで実行結果を確認することができます。
r = await callout("/test", method="POST", headers={"x-xaas-trace-id": "key"})
# Redisで受信した実行結果
"{\"id\":\"ad0760e6510411ee89ed362b5182ea16\",\"timestamp\":\"2023-09-12T09:38:21.972556+09:00\",\"utctimestamp\":\"2023-09-12T00:38:21.972592+00:00\",\"channel\":\"xaas.routing.trace.channel\",\"instance\":\"fa9148c4da994c6189223cb6e2e06d41\",\"host\":\"127.0.0.1\",\"port\":9000,\"pid\":15,\"role\":\"APIGW\",\"data\":{\"trace_id\":\"key\",\"route\":\"/test/transaction\",\"direction\":\"ingress\",\"pipeline\":\"request_spec_validation\",\"action\":{\"request_spec_validation\":[{\"usage\":\"testTransaction\",\"command\":\"callout\",\"method\":\"POST\",\"schema\":{\"response\":{\"normal\":{\"codes\":[200]}}}}]},\"input\":{\"url\":\"/test\",\"method\":\"POST\",\"headers\":{\"User-Agent\":\"Qmonus/v23.1LTS-patch20230703\",\"Accept\":\"*/*\",\"Accept-Encoding\":\"gzip,deflate\",\"Content-Type\":\"application/json\",\"X-Xaas-Auth-Token\":\"DPMkMdXSSE8yhi2DMqHa/p5RI9HMRsGEr06x5t15HQRtbK6tmOG70luzyyqHeFCjuCEunuG+7RsWj6ljt6isSFimDRjnmPvGAjYMeunNRfMhlC7wdM6cuhRrSaNcsULCp4JkwGe6227kcqfcqo9j2TBMvl06iE99JBBlYpAKM6lGW8BB+GSBgngXtDSF1io17AyvRx4iwebhoyL/woX7LGXmC+xxTj6ZyPT+tlSjNYk=\",\"X-Xaas-Family-Key\":\"hogehoge\",\"X-Xaas-Trace-Id\":\"key\",\"X-Xaas-Qmonus\":\"local\",\"Connection\":\"close\",\"Host\":\"scenario:9000\"},\"body\":null}}}"