Design Automation API：adskDebug オプション

Design Automation API を利用したタスクの実行単位を WorkItem と呼んでいます。WorkItem の実行時には、タスクを処理するための仮想環境がクラウドに動的に作成されて、WorkIem の実行終了とともに破棄されます。

なんらかの要因で WorkItem の実行が失敗してしまった場合、GET workitems/:id エンドポイントで得られる JSON レスポンスや、同レスポンスにあるレポートログ（report.txt）の URL を取得、ダウンロードして原因を特定していくのが一般的です。

ただ、レポートログの参照のみでは、仮想環境上で使用、あるいは、生成/編集されたファイルを物理的に入手して調べることが出来ません。WorkItem が使用したファイルを入手出来れば、内容を解析する手助けにもなります。

このような場面では、昨年追加された adskDebug オプションを使用することが出来ます。

WorkItem 呼び出し時に POST workitems エンドポイントのリクエストボディ（ JSON ペイロード）に次のように指定すると、WorkIem 実行時に使用した作業フォルダ（T:\Aces\Jobs\3dd248b6f8d14946b670a30362e2ddbd フォルダのような）の内容を ZIP 圧縮して、ダウンロードするための URL がレポートログに追記されるようになります。

// Create WorkItem

var payload =

{

"activityId": "MyDAapp.TestHarness+dev",

"arguments": {

"Input": {

"url": "urn:adsk.objects:os.object:" + BUCKET_KEY + "/" + SOURCE_NAME,

"headers": {

"Authorization": "Bearer " + credentials.access_token

},

"verb": "get"

},

"Params": {

"url": "data:application/json," + paramsJSON

},

"Output": {

"url": "urn:adsk.objects:os.object:" + BUCKET_KEY + "/" + RESULT_NAME,

"headers": {

"Authorization": "Bearer " + credentials.access_token

},

"verb": 'put'

},

"adskDebug": {

"uploadJobFolder": true

},

"onComplete": {

"verb": "post",

"url": "http://dummy/api/oncomplete"

}

}

};

GET workitems/:id エンドポイントでレスポンスを得ると、 "debugInfoUrl" から ZIP ファイルのダウンロード URL を得ることが出来ます。

...

{

"status": "failedInstructions",

"reportUrl": "https://dasprod-store.s3.amazonaws.com/workItem/<<長いので省略>>",

"debugInfoUrl": "https://dasprod-store.s3.amazonaws.com/workItem/<<長いので省略>>",

"stats": {

"timeQueued": "2023-03-07T01:16:31.7905734Z",

"timeDownloadStarted": "2023-03-07T01:16:31.9004055Z",

"timeInstructionsStarted": "2023-03-07T01:16:32.7135692Z",

"timeInstructionsEnded": "2023-03-07T01:16:37.7145756Z",

"timeUploadEnded": "2023-03-07T01:16:38.2854694Z",

"bytesDownloaded": 2560980,

"bytesUploaded": 427790

},

"id": "3dd248b6f8d14946bd70a30362e2ddbd"

}

ダウンロードした ZIP ファイルには、既に破棄されている仮想環境の作業フォルダのファイルとローミングフォルダが含まれます。Design Automation API for Revit の場合には、ジャーナルを見つけて調査に利用することが可能です。

GET workitems/:id エンドポイントが返すレポートログのダウンロード URL（"reportUrl" 値）の有効期間は 1 時間です。
adskDebug オプションで用意される ZIP ファイルのダウンロード URL は、エンジン毎にシステム内部で設定されるMaxAllowedPendingTime 値（非公開）＋3600 秒です。
adskDebug オプションの利用はデバッグ用途に限定して利用してください。デプロイした本番環境での利用は無意味です。

By Toshiaki Isezaki