Design Automation API：Direct-to-S3 アプローチを簡素化する新機能

すでに何度かご案内していますが、Direct-to-S3アプローチの導入にともない、Data Management API でファイルアップロードとダウンロードをおこなうエンドポイントと、同じくアップロードとダウンロードに関係する他の API のエンドポイントが廃止、または変更が加えられます。

既存のアプリは、使用する API によって移行作業が必要になります。対象の API やエンドポイント、実装については、Data Management OSS (Object Storage Service) の Direct-to-S3 アプローチへの移行について（内容更新）の記事をご確認ください。

この変更は、Design Automation API で WorkItem が素材ファイルを OSS Bucket からダウンロードしたり、結果ファイルを OSS Bucket にアップロードしたりする場合にも適用されます。既存アプリが Design Automation API を利用していて、かつ、WorkItem 内の入出力ファイル指定に OSS Bucket（含む、Autodesk Docs/BIM 360 Docs）を指定している場合には、新しい Direct-to-S3 アプローチをお使いいただけるようになります。日本でも動作を確認することが出来ましたので、ご案内いたします。

具体的には、Design Automation API の WorkItem で、"urn:adsk.objects:os.object:<Bucket name>/<Object key>" 形式の入力/出力 URL をサポートしました。この方法は、Design Automation API の Step by step tutorials に記された方法を大幅に簡素化するものです。

新し方法を採用すると、Direct-to-S3 アプローチのエンドポイントセットで署名付き S3 URLを生成する必要がなくなります。必要となるのは objectId とアクセストークンのみです。

objectId とは、Model Derivative API や Viewer で使用される URN（ドキュメント ID）の BASE64 エンコード前の値（文字列）を指します。objectId を取得・準備するための詳細は次とおりです。

OSS Bucket からの入力ファイルの場合：

Bucket から objectId を検索し、GET Objects でオブジェクト情報を取得することができます。

OSS Bucket からの出力ファイルの場合：

ストレージを作成してダミーのファイルを用意、objectIdを取得することもできますが、ストレージの作成やダミーファイルは必須ではなく、"urn:adsk.objects:os.object:<BucketKey>/<ObjectKey>" の形式で直接作成できます。例として、design.automation-nodejs-revit.parameters.excel をご参照いただくことが出来ます。

Autodesk Docs からの入力ファイルの場合：

ファイルのバージョンは GET Version で取得し、objectId は response.data.relationships.storage.data.id で確認することができます。例は、こちらでご確認いただけます。

Autodesk Docs からの出力ファイルの場合：

新しいファイルをアップロードや新しいバージョンを追加する全体のプロセスは、チュートリアルをご参照ください。step 3 では、POST projects/:project_id/storage エンドポイントを使用して、OSS にファイルをアップロードできるストレージの場所を作成します。この際、objectId は response.data.id で取得することが出来ます。例：こちらを参照

なお、OSS Bucket 内の objectId は、VS Code 用の Forge Extension でも確認することが出来ます。

objectId の用意が出来たら、それをアクセストークンとともに WorkItem の URL に渡します。アクセストークンはストレージに対する十分なアクセス権限（Scope）を持っている必要があります。例えば、入力ファイルの objectId には data:read 、出力ファイルには data:write が必要。

{
  "activityId": "mynickname.myactivity+prod",
  "arguments": {
    "rvtFile": {
      "url": "urn:adsk.objects:os.object:revit_da_integration_tests/CountIt.rvt",
      "verb": "get",
      "headers": {
        "Authorization": "Bearer <access_token>"
       }
    },
    "result": {
      "verb": "put",
      "url": "urn:adsk.objects:os.object:revit_da_integration_tests/result.txt",
      "headers": {
        "Authorization": "Bearer <access_token>"
       }
    }
  }
}

この新機能を使用すると、Design Automation API のタスクを自動的に処理するようになります。

Design Automation API は、objectId とアクセストークンを使って Direct-to-S3 アプローチの署名付き URL を作成し、WorkItem 内部でダウンロード/アップロードを実行出来ます。
アクセストークンが期限切れの場合、Design Automation API は提供された有効なアクセストークンを延長します。1 時間後に署名付き URL が期限切れになる心配はもうありません。
OSS への大容量ファイルのアップロードは、マルチパートアップロードがデフォルトでサポートされます。
OSS Bucket と ACC（Autodesk Docs）/BIM 360（BIM 360 Docs）の Bucket の両方が動作しますが、後者が所有するBucket には 3-legged トークンを使用するなど、適宜正しいトークンを提供する必要があります。

必要に応じて design.automation-nodejs-revit.parameters.excel サンプルですべての実装をご確認ください。

なお、この機能では、アップロード用署名付き URL 取得（GET buckets/:bucketKey/objects/:objectKey/signeds3upload）に “useAcceleration=true” パラメータ、ダウンロード用署名付き URL 取得（GET buckets/:bucketKey/objects/:objectKey/signeds3download）に “useCdn=true” パラメータが、それぞれ内部的に指定されています。

ご質問gは、[email protected] までメールをお送りください。

By Toshiaki Isezaki