Direct S3 アプローチ対応（暫定）SDK

ご注意：このブログ記事で紹介している SDK は、当社の開発者支援チームによって開発および保守されているものです。Autodesk Platform Services の公式 SDK を提供する取り組みは現在進行中であり、来年早々には公式 OSS SDK をリリースする予定です。

2022年3月、Data Management OSS (Object Storage Service) の Direct-to-S3 アプローチへの移行について も記事でデータをアップロード/ダウンロードするための新しい最適化されたアプローチと、.NET および Node.js 用の新しいロジックの参照実装を発表しました。今回、新しい Direct S3 アプローチによるアップロード/ダウンロードが .NET と  Node.js 用の SDK にも追加されましたので、アプリケーションで新しい効率的なデータ転送を有効にする方法をご案内いたします。

OSS へのアップロード

OSS（Object Storage Service）にデザインファイルをアップロードする場合、アプリケーションは通常、例えば次のように SDK の ObjectsApi#uploadObject メソッドを使用されているはずです。

.NET:

// ...

var api = new ObjectsApi();
api.Configuration.AccessToken = token;
var obj = await api.UploadObjectAsync(bucketKey, objectKey, contentLength, content);

// ...

 

Node.js:

// ...

const api = new ObjectsApi();
const obj = await api.uploadObject(bucketKey, objectKey, contentLength, content, {}, null, token);

// ...

このメソッドはまだ利用可能ですが、現在は非推奨としてマークされています。S3 への直接アップロードに切り替えるには、当社の SDK の最新バージョンにアップグレードし、代わりに ObjectsApi#uploadResources メソッドを使用してください。

.NET:

// Upgrade the `Autodesk.Forge` NuGet package to version 1.9.7 or newer
var api = new ObjectsApi();
api.Configuration.AccessToken = token;
var results = await api.uploadResources(bucketKey, new List<UploadItemDesc> {
    new UploadItemDesc(objectKey, content)
});

 

Node.js:

// Upgrade the `forge-apis` npm package to version 0.9.4 or newer
const api = new ObjectsApi();
const results = await api.uploadResources(
    bucketKey,
    [{ objectKey: objectKey, data: content }],
    {},
    null,
    token
);

uploadResources メソッドは、同時にアップロードされる複数のオブジェクトを受け入れ、アップロードされた個々のオブジェクトに対応する結果のリストを常に返します。各結果には、error（アップロードが失敗したかどうかを示すブール値のフラグ）、completed （アップロードに対する完全なレスポンスで、成功した場合はオブジェクトの詳細、失敗した場合はエラーの詳細が含まれます）などのプロパティが含まれます。

.NET:

var results = await api.uploadResources(bucketKey, new List<UploadItemDesc> {
    new UploadItemDesc(objectKey1, content1),
    new UploadItemDesc(objectKey2, content2),
    new UploadItemDesc(objectKey3, content3)
});
foreach (var result in results)
{
    if (result.Error)
    {
        throw new Exception(string.Format("Upload failed: {0}", result.completed.ToString()));
    }
    else
    {
        var json = result.completed.ToJson();
        Console.WriteLine(json.ToObject<ObjectDetails>());
    }
}

 

Node.js:

const results = await api.uploadResources(
    bucketKey,
    [
        { objectKey: objectKey1, data: content1 },
        { objectKey: objectKey2, data: content2 },
        { objectKey: objectKey3, data: content3 }
    ],
    {},
    null,
    token
);
for (const result of results) {
    if (result.error) {
        throw `Upload failed: ${result.completed}`;
    } else {
        console.log(result.completed);
    }
}

また、uploadResources メソッドに追加のオプションを渡して動作を調整したり、コールバック関数を渡してアップロードの進捗を監視したり、アップロードに時間がかかりすぎる場合にアクセストークンを更新するコールバック関数を渡したりすることも可能です。詳細については、Github の SDK リポジトリを参照してください。

• .NET: https://github.com/Autodesk-Forge/forge-api-dotnet-client/blob/v1.9.7/src/Autodesk.Forge/Api/ObjectsApi.cs#L4818-L4840
• Node.js: https://github.com/Autodesk-Forge/forge-api-nodejs-client/blob/v0.9.4/src/api/ObjectsApi.js#L1325-L1352

また、新しいSDKのメソッドをすでに使用している Simple Viewer チュートリアルを確認することもできます。

OSS からのダウンロード

OSS からオブジェクトのダウンロードでは、既存のアプリケーションは通常、SDK（.NET、Node.js）から ObjectsApi#getObject メソッドを使用しているはずです。アップデートされた SDK では、ObjectsApi#uploadResources と同様のシグネチャを持つ ObjectsApi#downloadResources  メソッドを使用することができるようになりました。

.NET:

var results = await ObjectsAPI.downloadResources(
    bucketKey,
    new List<DownloadItemDesc>() {
        new DownloadItemDesc(objectKey1, "arraybuffer"),
        new DownloadItemDesc(objectKey2, "arraybuffer"),
        new DownloadItemDesc(objectKey3, "arraybuffer")
	},
	new Dictionary<string, object>() {
        // { "minutesExpiration", 5 },
        // { "useCdn", true }
    },
    // onDownloadProgress,
    // onRefreshToken
);

 

Node.js:

const results = await objectsApi.downloadResources(
    bucketKey,
    [
        { objectKey: objectKey1, responseType: 'arraybuffer' },
        { objectKey: objectKey2, responseType: 'arraybuffer' },
        { objectKey: objectKey3, responseType: 'arraybuffer' }
    ],
    {
        // minutesExpiration: 5,
        // useCdn: true,
        // onDownloadProgress: (data) => { ... },
        // onRefreshToken: async () => { ... },
    },
	oAuthTwoLeggedClient,
    oAuthTwoLeggedClient.getCredentials()
);

各オプションの詳細については、GitHub の SDK リポジトリを参照してください。

• .NET: https://github.com/Autodesk-Forge/forge-api-dotnet-client/blob/v1.9.7/src/Autodesk.Forge/Api/ObjectsApi.cs#L4634-L4648
• Node.js: https://github.com/Autodesk-Forge/forge-api-nodejs-client/blob/v0.9.4/src/api/ObjectsApi.js#L1128-L1147

※ 本記事は Direct-S3 upload and download with SDKs | Autodesk Forge の内容をもとに翻訳・加筆修正したものです。

By Toshiaki Isezaki