Design Automation API：adskZipMigration オプション

Design Automation API に新しく adskZipMigration オプションを導入しています。ここでは、なぜ adskZipMigration を導入したのか、そして、導入によって解決される問題についてご紹介しておきたいと思います。

背景と問題

AutoCAD コアエンジンと Revit コアエンジンは、指定するパラメータの条件によっては Activity で指定した zip パラメータの localName を無視することがあります（すべてのケースではありません）。この影響で、localName 内で指定されたサブフォルダではなく、ジョブのルートフォルダや作業フォルダ（期待した場所ではない）に ZIP ファイルが解凍される場合があります。

簡単な例を見てみましょう。

素材ファイルを指定する入力パラメータを考えると、Activity の zip パラメータに 'true' に設定され、pathInZip パラメータが null でない場合が当てはまります。この場合、ドキュメント上の説明では、WorkItem の URL を通して渡された zip ファイルは、Design Automation の実行環境である仮想マシンの 'inputs' フォルダに解凍されるはずです。

#	Activity	Workitem	Arg direction	Comments
1	zip==true	pathInZip!=null	input	Zip is uncompressed to the folder specified in localname. Any path reference to this argument will expand to full path of pathInZip.（入力指定した Zip は localname で指定されたフォルダに展開される。この引数へのパス参照は pathInZip のフルパスに展開される。）

{
	"activityId": "aps.DrawingGeneration+prod",
	"arguments": {
		"InputFile": {
			"zip": true,
			"localName": "inputs", // サブフォルダ input 内に ZIP ファイルが展開されることを期待
			"pathInZip": "Template.dwg",
			"url": "url to download zip file"
		},
		"Result": {
			"url": "url to upload results",
			"localName": "outputs",
			"verb": "put",
			"headers": {
				"x-ms-blob-type": "BlockBlob",
				"Content-type": "application/octet-stream"
			}
		},
		"onComplete": {
			"url": "abc.url",
			"verb": "post"
		}
	}
}

ところが、上記期待とは異なり（Design Automation API 側の問題で）、現在、いずれの ZIP ファイルも作業フォルダに解凍されてしまっています。

期待した展開先：（正しい動作）

T:\Aces\Jobs\8213a96d225b4ba6848797a5d212f868\inputs\Template.dwg

実際の展開先：（誤った動作）

T:\Aces\Jobs\8213a96d225b4ba6848797a5d212f868\Template.dwg

このため、この動作を修正してしまうと、一部の開発者がアプリ側で（誤った動作に依存する）実装済の入力ファイル取得処理が失敗してしまうことになります。

新たなソリューションは？

そこで、（本来の動作に沿った実装と誤った動作に対応した実装）両者の動作が尊重されるように、いくつかの変更を加えています。

zip ファイルは古い（正しくない）場所と新しい（正しい）場所の両方に解凍されますが、「2 次解凍」（新しい場所への解凍）によるエラーはすべて無視します。

「2 次解凍」（アプリ実装を変更する必要があることを示す）をおこなう必要がある場合には、移行に関する警告をレポートログに記録します。

ログ例：:

Warning: Zip Migration: the input of 'inputs' is unzipped to the correct location of 'T:\Aces\Jobs\d278348cb72b4a40b8d6ac6ff3720066\vararg_inputs'.]
[Runner] [INFORMATION] [0] [Runner] [EC2AMAZ-88Q8Q37] [WiID=d278348cb72b4a40b8d6ac6ff3720066. Warning: Zip Migration: the input of 'inputs' is unzipped to the correct location of 'T:\Aces\Jobs\d278348cb72b4a40b8d6ac6ff3720066\inputs'.]

また、正しい場所への解凍によるエラーを無視せざるを得ない場合は、レポートログに実装変更の警告を記録します。
WorkItem に新しい引数 adskZipMigration を用意して、正しい動作に沿った実装を持つアプリ/プラグイン/スクリプトをテスト出来るようにしています。（zip ファイルは localName で指定されたサブフォルダにのみ解凍されます。この場合、レポートログへの記録はありません。）

WorkItem リクエストボディペイロードの例：

{
   "activityId": "myNickName.mytest+Latest",
   "arguments": 
   {
      "input": {xxxxxxxx},
      "result": {yyyyyyyy},
      "adskZipMigration" : true
   }
}

ご対応のお願い

上記ケースにおいて、当面の間（いまのところ 2023年12月までを予定）、WorkItem 実行時に ZIP ファイルを両方の場所に解凍し、必要に応じて実装の移行を促す警告を発します。前述のとおり、移行が必要な場合には、レポートログで内容を把握出来るようにしています。古い動作を完全に停止する前に、（該当する実装の移行がうまく進んで、）少なくとも 2 週間は移行警告を検出しなくなることを目標にしています。

ご不明な点がございましたら、Get Help までお問い合わせください。

※ 本記事は Design Automation: Introducing the New `adskZipMigration` Argument | Autodesk Platform Services から転写・翻訳、補足したものです。

By Toshiaki Isezaki