Postman による Viewer 利用手順の理解 - 2 legged 認証

先日の ブログ記事 で Postman による RESTful API のテストについてご紹介しました。今回は、Forge Viewer で 3D モデルを表示するまでの処理を、Postman を使ってトレースしてみたいと思います。ここでは、最もシンプルな 2-legged 認証 を利用して、任意に作成した Bucket にファイルをアップロード、変換して Viewer に表示するまでを、endpoint に対応する Postman のコレクションで説明していきます。

このブログ記事には、使用する RESTful API の endpoint 毎に、Postman のコレクションを記載していますので、順次、ダウンロードして Postman にインポートしてお使いください。コレクションのインポートは、Postman ウィンドウ左上の [Import] ボタンから実行することが出来ます。

なお、コレクション内部に指定されているアクセストークン（Access Token）や Bucket 名（Bucket Key）、アップロードするファイル（Object Key）などは、適宜、ご自身の環境でお使いになるものに書き換えてください。

実際に RESTful API で endpoint 毎の処理をテストする手順は次のとおりです。

それでは、順に endpoint と処理内容を見ていきます。

1. forge.autodesk.com からアカウント登録とアプリの作成（手動）

Forge ポータルでアプリを登録して Forge Platform API の利用に必要な Client ID（Consumer Key）と Client Secret（Consymer Secret）を取得します。この処理は、手動でおこなう必要があります。具体的な手順は、過去のブログ記事 Forge API を利用するアプリの登録とキーの取得 を参考にしてください。

2. アクセストークンの取得

Forge Platform API で RESTful API を使用する場合には、1. で取得した Client ID（Consumer Key）と Client Secret（Consymer Secret）から Access Token を取得して呼び出しに利用する必要があります。この処理には、Authentication API を利用します。

今回は、2-legged 認証で Forge が提供する OSS（Object Storage Service）の領域にアクセスするので、使用する endpoint は https://developer.api.autodesk.com/authentication/v1/authenticate、メソッドは POST となります。

（2023年7月追記）Authentication API（OAuth API）は v1 から v2 に移行しています。詳細は、OAuth2 v1 から v2 への移行ガイド の記事を確認してください。

開発中のアプリ（同一の Client ID/Consumer Keyと Client Secret/Consymer Secret）で作成したすべての Bucket を列挙するには、endpoint https://developer.api.autodesk.com/oss/v2/buckets、メソッド GET が利用可能です。

2. アクセストークンの取得.postman_collectionをダウンロード

Authentication API（OAuth API）v2 Postman コレクションは、Postman を使った 2-legged 認証(OAuth v2) からダウンロードすることが出来ます。

ダウンロードした Postman コレクションを使った Access Token の取得の手順を次の動画で確認することが出来ます。

3. バケットの作成

2-Legged 認証では OSS 上に一意な名前で Bucket を作成して、ファイルをアップロード、変換を経て、Viewer への表示を準備します。Bucket の作成とデザインファイルのアップロードには、Data Management API を使用します。Bucket 作成時には、名称とともに Bucket Policy を指定する必要があります。詳細は、過去のブログ記事 Bucket に関してのサマリー をご確認ください。

Bucket の作成に使用する endpoint は https://developer.api.autodesk.com/oss/v2/buckets、メソッドは POST となります。

既に登録されている Bucket について、特定の Bucket が存在するかを知るためには、endpoint https://developer.api.autodesk.com/oss/v2/buckets/:bucketKey/details、メソッド GET を利用することが出来ます。上記 URI 中の :bucketKey 部は照会したい Bucket 名で置き換えてください。この endpoint は、Bucket 内のデザインファイルの列挙にも利用することが可能です。

3. バケットの作成.postman_collectionをダウンロード

ダウンロードした Postman コレクションを使って Bucket を作成したり、有無をチェックしたりする方法を次の動画で確認することが出来ます。

4. デザインファイルのアップロード

Bucket を新規作成、または、既存 Bucket の情報が取得出来たら、Viewer で表示させたいデザインファイルをアップロードします。アップロードに使用する endpoint は https://developer.api.autodesk.com/oss/v2/buckets/:bucketKey/objects/:objectName で、メソッドは PUT です。上記 URI 中の :bucketKey と :objectName 部分は、それぞれアップロード先となる Bucket 名とアップロードするファイル名を URL エンコード された値に置き換えてください。

2019年2月末から、リクエストヘッダーに Content-Length 情報を含めてアップロードするファイルのサイズを明示化することが必須になります。Postman は自動的に Content-Length ヘッダー情報を付加するので、ここでは割愛していますが、実際にコーディングする際には注意が必要です。詳細は、Content-length ヘッダー指定要件の必須化 記事をご確認ください（2019年4月追記）。
ファイルアップロードは、新しい endpoint を使った AWS S3 への直接アップロードが2022年3月ににアナウンスされ、使用が推奨されています。詳細は、Data Management OSS (Object Storage Service) の Direct-to-S3 アプローチへの移行について をご確認ください。（2022年4月追記）。

Postman でファイルをアップロード指定する際には、 Header タブで指定する Content-Type パラメータに application/octet-stream を指定してください。また、Body タブでは、binary チェックボックスを有効にすると [ファイル選択] ボタンが表示されるので、アップロードするファイルを表示されるファイルダイアログで選択出来ます。

4. デザインファイルのアップロード-（ダウンロード）.postman_collectionをダウンロード

ダウンロードした Postman コレクションを使ってデザインファイルをアップロードしたり、バケット内のファイルをリストする手順を次の動画で確認することが出来ます。

5. 変換リクエスト

Bucket にデザインファイルがアップロードが完了したら、Viewer でストリーミング表示出来るようにファイルを変換します。変換に利用するのは Model Derivative API です。

Bucket 内のデザインファイルの変換指示に使用するのは、endpoint https://developer.api.autodesk.com/modelderivative/v2/designdata/job、メソッド POST です。

なお、この endpoint を利用する際には、変換対象のデザインファイルは URN と呼ばれるドキュメント ID を BASE64 エンコード して指定することが義務付けられています。Postman 利用時には、ファイルアップロード時に返された JSON レスポンスから objectId 部分を https://www.base64encode.org/ サイト等で変換して変換リクエストに利用してください。

例えば、fpd-japan-sample-bucket 名の Bucket に Bike frame.f3d （エンコード時 Bike%20frame.f3d）をアップロードした際には、次のような JSON レスポンス Body を得ることが出来ます。

{
"bucketKey": "fpd-japan-sample-bucket",
"objectId": "urn:adsk.objects:os.object:fpd-japan-sample-bucket/Bike%20frame.f3d",
"objectKey": "Bike frame.f3d",
"sha1": "aff3baa7e6ddd2053f669632ee69412bc70399fa",
"size": 9916386,
"contentType": "application/octet-stream",
"location": "https://developer.api.autodesk.com/oss/v2/buckets/fpd-japan-sample-bucket/objects/Bike%20frame.f3d"
}

ここでは、urn:adsk.objects:os.object:fpd-japan-sample-bucket/Bike%20frame.f3d が URN となるので、Base64 に変換して、dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6ZnBkLWphcGFuLXNhbXBsZS1idWNrZXQvQmlrZSUyMGZyYW1lLmYzZA== で変換指定をおこなうことになります。

URN を含め、SVF ファイルへの変換指定は、クライアントからの JSON 指定となります。Postman では Body タブで row チェックボックスを選択して直接 JSON を貼り付けて実行します。

この endpoint を実行した際の JSON レスポンス内の result パラメータに success が返れば、変換処理が正常に起動できたことになります。

なお、変換処理はすぐに完了するものではありません。ポーリング を実施して、変換処理が完了するかチェックする必要があります。ポーリングに利用するのは、endpoint https://developer.api.autodesk.com/modelderivative/v2/designdata/:urn/manifest、メソッド GET です。JSON レスポンスの status パラメータ値で変換状況を、progress パラメータ値で進捗状況を検出することが出来ます。

Converted_result

ストリーミング配信用に利用される内部ファイル形式は、SVF ファイルです。アップロードするファイル形式を SVF ファイル形式に変換可能か否かは、endpoint https://developer.api.autodesk.com/modelderivative/v2/designdata/formats、メソッド GET を利用します。JSON で返された SVF スコープ内に、該当するファイル拡張子があれば、そのデザインファイルを変換して Viewer に表示出来ることになります。

5. 変換リクエスト.postman_collectionをダウンロード

ダウンロードした Poatman コレクションを使ってデザインファイルを変換したり、変換状況をチェックをリストする手順を次の動画で確認することが出来ます。

6. クライアントからのアクセス

ここまでの手順で Viewer に表示する準備が整ったことになります。Viewer は JavaScript API でるため、Postman ではなく、表示に必要な処理を埋め込んだ HTML を用意する必要があります。

次の HTML ファイルをダウンロードして、accessToken パラメータに Access Token を、urn パラメータに SVF ファイル変換が終了したデザインファイルの URN を与えてみてください。

Viewer.htm をダウンロード

Viewer.htmの後に ? でパラメータを接続して、パラメータ間は & で統合します。例えば、Access Token が eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0.eyJjbGllbnRfaWQiOiJWMlpQcmNaR242eWVqTXRSNzZHM2lMR2pxRng 、ドキュメント ID（URN）が dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6ZnBkLWphcGFuLXNhbXBsZS1idWNrZXQvQmlrZSUyMGZyYW1lLmYzZA== の場合、C:\Forge-Workshop フォルダにダウンロード済みの Viewer.htm で表示するには、次のような指定で表示するドキュメントを引き渡すことが出来ます。

file:///C:/Forge-Workshop/viewer.htm?accessToken=eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0.eyJjbGllbnRfaWQiOiJWMlpQcmNaR242eWVqTXRSNzZHM2lMR2pxRng&urn=dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6ZnBkLWphcGFuLXNhbXBsZS1idWNrZXQvQmlrZSUyMGZyYW1lLmYzZA==

この HTML ファイルでは、URL パラメータに Access Token を指定しますが、表示確認を目的としたサンプルのためです。通常、Consumer Key、Consumer Secret も含め、Access Token の内容を含む実装は Web サーバー側の実装で隠蔽すべきです。
URL パラメータとして Access Token を渡した場合、Web ブラウザが持つ CORS(Cross-Origin Resource Sharing) を抑止するセキュリティ上の制限によって、表示が出来ない場合があります（ブラウザ依存）。Google Chrome の場合には、No 'Access-Control-Allow-Origin' header is present on the requested resource. 等のエラーが発生してしまいますので、Chrome の起動ショートカットにパラメータ、--disable-web-security --user-data-dir、または、--allow-file-access-from-files --allow-file-access --allow-cross-origin-auth-prompt を指定することで、このセキュリティ機能を無効化して開発時のテストをおこなうことが出来ます。もちろん、一般利用時には、この設定での Chrome 起動はお勧めしません。ご注意ください。
Viewer.htm では意図的に標準ボタン群を無効化しています（このような実装も可能です）。