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
You must be logged in to post a comment.