革新テクノロジの反映とサービス向上の一環として、オートデスクは、基盤となる AWS S3 Bucket(バケット)からの直接アップロードとダウンロードを可能にする Data Management API の新しいエンドポイント セットをリリースしました。この direct-to-S3 アプローチの主な利点は、パフォーマンスです。
オートデスク社内でのテストと検証では、特に大容量ファイルのアップロードとダウンロードの速度が大幅に向上していることが継続して確認されています。
どのように? オブジェクトが OSS(Object Storage Services)Bucket へのアップロード/からのダウンロード時、オートデスクは AWS S3 ストレージを使用しています。
現在のバイナリ転送アプローチでは、オートデスクのプロキシを介してデータを移動させますが、新しい direct-to-S3 アプローチでは、基盤となる S3 Bucket と Object に直接アクセスすることが可能になります。
Data Management のストリーミング エンドポイントを 2022年9月30日 12月31日に廃止予定
オートデスクは、2022 年 9 月 30 日12 月 31 日に、現在のプロキシ (developer.api.autodesk.com) と直接ファイルをアップロード、また、ダウンロードする現在のバイナリ転送ストリーミング用のエンドポイントのアプローチを廃止し、同日以降は転送を許可しない方針です。
2022 年 9 月 30 日12 月 31 日までに、影響を受ける API を使用する既存の Forge アプリを新しい direct-to-S3 方式に移行する必要があります。
影響を受ける API エンドポイントに関する最新情報は下記をご確認ください。
影響を受ける API:
- Data Management API : Bucket と Object: PUT object、 PUT resumable、 GET object エンドポイントが削除されます。同エンドポイントを使用している Forge アプリは、次の Data Management OSS の Direct-to-S3 アプローチ セクションで詳しく説明する signeds3upload と signeds3download に移行する必要があります。
- Model Derivative API : GET Derivatives エンドポイントは、新しいエンドポイントGET Fetch Derivative Download に移行してください。
- Viewer::v7.68 以前のバージョンを使用している場合、Viewer の初期化時にエンドポイント オプションを追加または変更する必要があります。他のオプションの変更は必要ありません。
var options = {
endpoint: 'https://cdn.derivative.autodesk.com'
// keep other options unchanged
};
- BIM 360 Docs PDF Export :GET export エンドポイントは、追加のS3署名付きURL、(すなわち、レスポンス内のsignedUrlフィールド)を提供するように更新されます。この署名付きURLを呼び出すことで、実際のコンテンツをダウンロードすることができます。現在の link フィールドは、移行期間中の互換性のために、まだ機能しています。 詳しくはこちらをご覧ください。
次の API は影響を受けませんが、アプリには相互依存性がある可能性があります :
- Design Automation API:OSS は、Design Automation API の WorkItem で入出力用のストレージに OSS Bucket 使用している場合です。Design Automation API 自体に変更はありません。次の Data Management OSS の Direct-to-S3 アプローチ セクションで解説しているように、WorkItem が OSS に保存されている場合、新しい useCdn=trueクエリーパラメータを使用して署名付き URL を取得する既存のエンドポイントを使用することができます。Autodesk Construction Cloud または BIM 360 を使用している場合には、次の Data Management API 項の手順を参照してださい。
- Autodesk Construction Cloud & BIM 360: OSSは、これらのサービスのストレージとして一般的に使用されています。ストレージへのアクセス方法にはありません。次の Data Management API 項の手順を参照してださい。
- Data Management API :Projects、Folders 、Files : ファイルをアップロード、およびダウンロードするアプリは、署名付き S3 URL (Signed S3 URL)使用する必要があります。
- BIM 360/Autodesk Build Cost API : Cost API にいては、変更はありません。今回の更新は、変更の影響を受ける Data Management API に依存するアップロード/ダウンロードのワークフローに対するものです。Data Management API を使用して Docs のファイルをアップロード/ダウンロードされている方は、すでにこの変更についてご存じかと思われます。詳しくはこちらをご確認ださい。
影響を受けない API:
- Authentication API(OAuth API)
- Data Visualization API
- Token Flex API
- Webhooks API
- Assets API
Data Management OSS の Direct-to-S3 アプローチ
ファイルをアップロード、あるいは、ダウンロードするためには、Forge アプリは署名付き URL を生成してバイナリ ファイルをアップロード、ダウンロードする必要があります。疑似シナリオに沿った、おおまかな手順は次のとおりです。
アップロード
-
アップロードするファイルのパート数を算出
-
注意:最後の 1 つを除き、アップロードする各パートは 5 MB(1024×5)以上であること
-
-
GET buckets/:bucketKey/objects/:objectKey/signeds3upload?firstPart=<index of first part>&parts=<number of parts> エンドポイントを使用して特定のパートのファイルをアップロードするための、最大 25 の URL を生成
-
パート番号は 1 から始まるものと仮定
-
例えば、10 番パートから 15 番パートまでのアップロード用 URL を生成するには、<index of first part> を 10 に、<number of parts> を 6 に設定
-
このエンドポイントは、後で追加の URL を要求したり、アップロードを確定するために使用する uploadKey も返す
-
-
残りのパート ファイルを、対応するアップロード URL にアップロード
-
レスポンスコードが 100~199、429、500~599 の場合、個々のアップロードの再試行を検討する(例えば指数関数的バックオフを使用)
-
レスポンスコードが 403 の場合、アップロード用 URL の有効期限が切れているため、上記手順 2. へ戻る
-
アップロード用 URL をすべて使い切ってしまい、まだアップロードする必要があるパートが存在する場合、手順 2. に戻って URL を生成する
-
-
POST buckets/:bucketKey/objects/:objectKey/signeds3upload エンドポイントを使用して、ステップ 2. からの uploadKey 値を使用してアップロードを確定させる
ダウンロード
-
GET buckets/:bucketKey/objects/:objectName/signeds3download エンドポイントを使ってダウンロード URL を生成
-
新しい URL を使用して、AWS S3 から直接 OSS オブジェクトをダウンロード
-
応答コードが 100~199、429、500~599 の場合、ダウンロードの再試行を考慮する(例えば指数関数的バックオフを使用)
-
署名付き URL の有効期限は、既定値で 2 分です(※minutesExpiration パラメータで最大 60 分まで設定可能)。有効期限が切れる前にダウンロードまたはアップロード処理を開始することが重要です。シングルまたはマルチパートのアップロードの場合、署名付き URL を再度要求することができます。アップロードとダウンロードの手順については、Step-by-Step Documentationを参照してください。
以後公開するブログ記事では、Node.js、.NET Core/.NET サンプルについてご紹介します。
ご不明な点やご質問がありましたら、[email protected] までお問合せください。
*免責事項
署名付き URL を生成する場合、URL が公開された場合のアクセス延長を避けるため、できるだけ短い有効期限を使用することが重要です。
※ 本記事は Data Management OSS (Object Storage Service) migrating to Direct-to-S3 approach | Autodesk Forge から転写・翻訳して一部加筆したものです。
By Toshiaki Isezaki
コメント
コメントフィードを購読すればディスカッションを追いかけることができます。