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}}}"