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