新しい APS Node.js SDK への移行

2023 年末に、新しい APS Node.js SDK をアナウンスしています。このプロジェクトはまだベータ扱いですが、正式な公開時にインターフェースに劇的な変更が加えられる可能性は低いため、Node.js アプリでこの新しい公式 SDK への移行を検討する良い機会です。

パッケージとインストール

SDK は、API 毎に個別の NPM パッケージに分割されて提供されています。

例えば、

などです。

そこで、”管理” モジュール @aps_sdk/autodesk-sdkmanager（SDK マネージャー）を同時に用意して、個々の API モジュールすべてに共有機能と設定（認証、レジリエンシー、ログ機能など）を提供しています。

本 SDK で利用可能なモジュールは、https://www.npmjs.com/~aps.sdk の [Dependents] タブで参照することが出来ます。

これらの依存関係をプロジェクトに追加するには、Node.js package manager などを使用して、SDK マネージャーと必要な API モジュールをインストールするだけです。

npm install --save @aps_sdk/autodesk-sdkmanager @aps_sdk/authentication @aps_sdk/oss @aps_sdk/model-derivative

初期化

各 API モジュールは、対応する APS サービスへのエントリポイントとなる *Client クラス（AuthenticationClient や OssClient など）を公開しています。これらのクラスのコンストラクタは、唯一のパラメータとして SDK マネージャーのインスタンスを要求とします。以下は、コード内でこれらのクライアントを初期化する例です。

const { SdkManagerBuilder } = require("@aps_sdk/autodesk-sdkmanager");
const { AuthenticationClient } = require("@aps_sdk/authentication");
const { OssClient } = require("@aps_sdk/oss");
const { ModelDerivativeClient } = require("@aps_sdk/model-derivative");

const sdkManager = SdkManagerBuilder.create().build();
const authenticationClient = new AuthenticationClient(sdkManager);
const ossClient = new OssClient(sdkManager);
const modelDerivativeClient = new ModelDerivativeClient(sdkManager);

SDK は ES6 モジュールもサポートしています。

import { SdkManagerBuilder } from "@aps_sdk/autodesk-sdkmanager";
import { AuthenticationClient } from "@aps_sdk/authentication";
import { OssClient } from "@aps_sdk/oss";
import { ModelDerivativeClient } from "@aps_sdk/model-derivative";

const sdkManager = SdkManagerBuilder.create().build();
const authenticationClient = new AuthenticationClient(sdkManager);
const ossClient = new OssClient(sdkManager);
const modelDerivativeClient = new ModelDerivativeClient(sdkManager);

認証とユーザー情報

2-legged でアクセストークンを生成するには、次のようにコーディングすることが出来ます。

// ...

import { AuthenticationClient, Scopes } from "@aps_sdk/authentication";

// ...

const twoLeggedCredentials = await authenticationClient.getTwoLeggedToken(APS_CLIENT_ID, APS_CLIENT_SECRET, [Scopes.DataRead, Scopes.ViewablesRead]); 
console.log(twoLeggedCredentials.access_token);

同じく、3-legged トークンを生成、または、リフレッシュトークンを得るには、旧 Forge Node.js SDK と似た次のようなコーディングを使用することが出来ます。

// ...

import { AuthenticationClient, ResponseType, Scopes } from "@aps_sdk/authentication";

// Generating the authorization URL
const url = authenticationClient.authorize(APS_CLIENT_ID, ResponseType.Code, APS_CALLBACK_URL, [Scopes.DataRead, Scopes.ViewablesRead]);
console.log(url);

// Exchanging temporary code for an access token
const threeLeggedCredentials = await authenticationClient.getThreeLeggedToken(APS_CLIENT_ID, temporaryCode, APS_CALLBACK_URL, {
    clientSecret: APS_CLIENT_SECRET
});
console.log(threeLeggedCredentials.access_token);

// Refreshing an access token
const refreshedCredentials = await authenticationClient.getRefreshToken(APS_CLIENT_ID, threeLeggedCredentials.refresh_token, {
    clientSecret: APS_CLIENT_SECRET,
    scopes: [Scopes.ViewablesRead]
});
console.log(refreshedCredentials.access_token);

最後に、取得済の 3-legged トークンからユーザー情報を抽出する方法を紹介しましょう。

const userInfo = await authenticationClient.getUserInfo(threeLeggedCredentials.access_token);
console.log(userInfo.name);

注：Authentication API v2 では、firstName フィールドと lastNameフィールドは name という単一のフィールドに置き換えられています。

エラーチェック

SDK はすべての HTTP リクエストで axios を使用します。SDK が例外をスローするたびに、エラーオブジェクトの err.axiosError に axios 固有の情報が含まれます。これは、例えば、API 呼び出しから非 2xx レスポンスを期待する場合など、特定のシナリオで便利です。

try {
    await ossClient.getBucketDetails(accessToken, bucketKey);
    console.log("Bucket exists");
} catch (err) {
    if (err.axiosError.response.status === 404) {
        console.log("Bucket does not exist");
    } else {
        throw err;  
    }
}

便利なメソッド

場合によっては、API クライアントが 2 つ以上の API リクエストを 1 つのメソッド呼び出しにまとめることがあります。例えば、OSS Bucket にファイルをアップロードする場合、アップロード URL を作成し、コンテンツを手動でアップロードし、最後にアップロード完了のリクエストを送信する代わりに、await ossClient.upload(APS_BUCKET, objectName, localFilePath, accessToken) を呼び出すような場面です。現在、SDK プロジェクトのドキュメントと変更履歴を作成しているので、そこでこれらのオプションを紹介する予定です。

その他のリソース

本 SDK の公式ドキュメントの準備が整う前に、サンプル（プロジェクトの GitHub リポジトリの一部：https://github.com/autodesk-platform-services/aps-sdk-node）や APS チュートリアル（https://tutorials.autodesk.io）をチェックすることで、使用方法の詳細を把握することが出来ます。

※ 本記事は Migrating to the new APS Node.js SDK | Autodesk Platform Services から転写・意訳したものです。

By Toshiaki Isezaki