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

<本記事は2019年12月10日に Forge Viewer v7 にあわせて一部改定しています。>

前回、Postman で 3-legged 認証の Callback URL を使った認証プロセスの設定と方法をご紹介しました。今回は、認証後にユーザの A360 のプロジェクト内に保存されているデザインファイルにアクセスして、Viewer 上に 3D モデルを表示する手順をご案内していきます。Postman を使った 3-legged 認証・認可(OAuth v2)（2023年8月追記）を見比べていただくと、手順を含めた違いをご理解いただけるはずです。

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

実際の手順と endpoint の説明に入る前に、A360 が持つ構造を見ていきます。2-legged 認証の際には、Object Storage Service（OSS）上に作成した Bucket を使って、デザインファイルをアップロード→変換→表示の順で使用していました。Forge アプリの開発者は、その開発者だけがアクセスする Bucket を操作対象にしていたので、データアクセスに関わる操作はシンプルでした。

一方、A360 は少し複雑です。ストレージ内の論理構造は、次の図のようになっています。Forge では、Data Management API でこれらの構造にアクセスしていくことになりますが、ここでは、まず、基本的な役割と解説しておきます。

Hub（ハブ）：

オートデスクには A360、Fusion Team、BIM 360 Team など、複数の異なるクラウドサービスがありますが、ユーザがこれらクラウドサービスを Subscription を購入した際には、必ず1つの Hub に関連付けられます。もし、他の Hub 上にある Project への招待を受け入れた場合には、本来関連付けられた Hub 以外の Hub にも関連付けられます。すなわち、1 つのアカウントで複数の Hub を持つことが出来ます。

Project（プロジェクト）：

1 つの Hub には複数の Project を持つことが出来ます。Project を作成出来るのは Administrator 権限を持つユーザで、Hub 内に作成出来る Project 数は、無償版の 5 Project を除いて無制限です。Project 直下には、デザインファイルなど、アップロードしたファイルが Item（アイテム） という単位で格納されます。また、Project 直下に Folder（フォルダ）を作成して、更に、その配下に Item を持つことも出来ます。Item と Folder は、A360 を利用するユーザによって任意にアップロード/作成されることになります。

Version（バージョン）：

Item はバージョン管理の対象になります。同じ名前の Item を同じ場所（Project 直下、ないしは、Folder 直下）にアップロードすると、 Item の新しいバージョンとして認識されます。また、Fusion 360 のように、デザインファイルを直接編集して内容を更新した場合でも、新しいバージョンとして認識されます。Data Management API では、バージョン付けされた Item を、バージョンを指定して個々にアクセス出来るようになっています。指定された Item バージョンは、OSS 上に格納されたデザインデータと直接関連付けられています。

それでは、A360 上のデザインファイルを Forge Viewer で表示するまでの手順を、endpoint とともに見ていきましょう。なお、Access Token は、Postman による 3 legged 認証 の手順で既に取得しているものとします。

ここでアクセスするストレージは、サインイン画面で A360 にサインインして、Forge アプリ（ここでは Postman）にアクセス許可を与えた A360 ユーザのストレージ領域になる点に注意してください。

1.Hub へのアクセス

アクセスするユーザがいくつの Hub に関連付けられているかは、調べてみないとわかりません。まずは、 Data Management API の endpoint https://developer.api.autodesk.com/project/v1/hubs、メソッド GET を使って、関連付けられた Hub のリストを取得してみます。

この endpoint を呼び出すと、JSON レスポンスで返されます。この中に、関連付けられた Hub の情報が含まれています。この後の操作で、特定の Hub に含まれる Project → Folder → Item → Version の順にアクセスしていくことになります。特定の Hub の詳細情報にアクセスするには、ここで取得した JSON 内の "id" 値が必要となります。

{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": {
      "href": "https://developer.api.autodesk.com/project/v1/hubs"
    }
  },
  "data": [
    {
      "type": "hubs",
      "id": "a.YnVzaW5lc3M6bXlpMzYy",
      "attributes": {
        "name": "俊明 伊勢崎",
        "extension": {
          "type": "hubs:autodesk.core:Hub",
          "version": "1.0",
          "schema": {
            "href": "https://developer.api.autodesk.com/schema/v1/versions/hubs%3Aautodesk.core%3AHub-1.0"
          },
          "data": {}
        }
      },

特定の Hub へアクセスして詳細情報を取得するには、endpoint https://developer.api.autodesk.com/project/v1/hubs/:hub_id、メソッドGET を利用します。:hub_id に当たる部分は、前述の https://developer.api.autodesk.com/project/v1/hubs から得られた当該 Hub の id となります。

1.Hub へのアクセス.postman_collectionをダウンロード

2.Project へのアクセス

アクセスしたいデザインデータを持つ Hub の情報を得られたら、次に、Hub 配下の Project を取得します。Hub 内のすべての Project を得るには、endpoint https://developer.api.autodesk.com/project/v1/hubs/:hub_id/projects、メソッド GET を利用します。このレスポンスで、すべての Project の情報が JSON で返されます。

Project が持つ id が分かれば、特定の Project 情報のみを取得することが出来ます。その場合、使用する endpoint は https://developer.api.autodesk.com/project/v1/hubs/:hub_id/projects/:project_id、メソッドは GET です。もちろん、URI 中の :hub_id は Hub の id、:project_id は Project の id です。

{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": {
      "href": "https://developer.api.autodesk.com/project/v1/hubs/a.YnVzaW5lc3M6bXlpMzYy/projects/a.YnVzaW5lc3M6bXlpMzYyIzIwMTYxMDE5NDcyODYyNTE"
    }
  },
  "data": {
    "type": "projects",
    "id": "a.YnVzaW5lc3M6bXlpMzYyIzIwMTYxMDE5NDcyODYyNTE",
    "attributes": {
      "name": "My Project",
      "extension": {
        "type": "projects:autodesk.core:Project",
        "version": "1.0",
        "schema": {
          "href": "https://developer.api.autodesk.com/schema/v1/versions/projects%3Aautodesk.core%3AProject-1.0"
        },
        "data": {}
      }
    },

このendpoint の呼び出しを実行すると、返される JSON レスポンスに Project 直下の Folder を表す rootFolder 情報を得ることが出来ます。

Project 直下の rootFolder には、endpoint https://developer.api.autodesk.com/project/v1/hubs/:hub_id/projects/:project_id/topFolders、メソッド GET で直接アクセスすることも出来ます。

2.Project へのアクセス.postman_collectionをダウンロード

3.Folder へのアクセス

Project 直下の rootFolder にアクセスすることが出来たら、その配下の Item、または、Folder にアクセスすることが出来るようになります。Folder 内には、Item か Folder が格納されていると考えられます。すべてをリストするには、endpoint https://developer.api.autodesk.com/data/v1/projects/:project_id/folders/:folder_id/contents、メソッド GET を使用します。ここで返される JSON 中で、Type 値が "folders" になっているのが、rootFolder 内の Folder、同じく、Type 値が "items" になっているのが Item です。それぞれ、id を持っているので、適切な endpoint で指定することで、Folder や Item の詳細を得ることが出来ます。

特定の Folder の id が分かれば、endpoint https://developer.api.autodesk.com/data/v1/projects/:project_id/folders/:folder_id、メソッド GET で Folder 詳細を取得することもできます。

3.folder-へのアクセス.postman_collectionをダウンロード

4.Item へのアクセス

Item は、実際に A360 にアップロードしたファイルに相当します。特定の Item に辿り着くことが出来れば、3D モデルや 2D 図面の表示をおこなうことが出来ることになります。注意が必要なのは、変換処理です。2-legged 認証時には、Bucket へデザインファイルをアップロードして、Viewer 表示用に変換する処理は、Forge アプリを開発する開発者がプログラムでおこなう必要がありました。A360 クラウドサービスの場合、A360 のユーザがデザインファイルをアップロードすると、A360 上での表示のため、A360 自身が自動的に変換処理をおこないます。従って、もし、A360 による変換処理が完了していて、かつ、Viewable と呼ばれる SVF ファイルが生成されていれば、そのドキュメント ID（URN）を取得することで、直ぐに JavaScript コードを介してクライアントの Web ブラウザでデザインを表示することが出来ます。

残念ながら、Folder 内保存されている Item 一覧だけを取得する API はされていないので、3.Folder へのアクセス で紹介した endpoint https://developer.api.autodesk.com/data/v1/projects/:project_id/folders/:folder_id/contents、メソッド GET で目的の Item の id を得る必要があります。

目的の Item の id が取得できたら、Item 詳細を取得出来ます。使用する endpoint は https://developer.api.autodesk.com/data/v1/projects/:project_id/items/:item_id、メソッドは GET です。この endpoint で取得した JSON には、Item に複数の Version が存在している場合でも、常に最新の Version 情報が含まれます。取得した Item の Version は、"versionNumber" の値で判別することが可能です。

  "included": [
  {
    "type": "versions",
    "id": "urn:adsk.wipprod:fs.file:vf.gBoEOhq6SIacqwFPaVx9pA?version=3",
    "attributes": {
      "name": "Diesel_Car_JNR.f3d",
      "displayName": "Diesel_Car_JNR.f3d",
      "createTime": "2016-12-09T02:08:42.0000000Z",
      "createUserId": "200708030638689",
      "lastModifiedTime": "2016-12-09T02:08:42.0000000Z",
      "lastModifiedUserId": "200708030638689",
      "versionNumber": 3,
      "mimeType": "application/vnd.autodesk.f3d",
      "storageSize": 49945660,
      "fileType": "f3d",
      "extension": {
        "type": "versions:autodesk.core:File",
        "version": "1.0",
        "schema": {
          "href": "https://developer.api.autodesk.com/schema/v1/versions/versions%3Aautodesk.core%3AFile-1.0"
        },
        "data": {}
      }
    },

もし、JSON 内に "derivatives" が存在している場合、A360 が変換処理を実行した形跡と考えることが出来ます。"derivatives" セクション内の id 値が、ドキュメントID、つまり、URN になります。

 "derivatives": {
   "data": {
     "type": "derivatives",
     "id": "dXJuOmFkc2sud2lwcHJvZDpmcy5maWxlOnZmLmdCb0VPaHE2U0lhY3F3RlBhVng5cEE_dmVyc2lvbj0z"
   },

ただし、ここに id を見つけることが出来ても、そのまま Forge Viewer に表示出来るとは限りません。この場合、A360 などのクラウドサービスか、Model Derivative API が変換した際の Manifest（マニフェスト）をチェックしてみてください。Manifest は、デザインファイルの変換時に変換状況や結果を記したもので、endpoint https://developer.api.autodesk.com/modelderivative/v2/designdata/:urn/manifest、メソッド GET で JSON を取得することが出来ます。Manifest 内の "derivative" セクションで、変換結果を示す "status" 値が success、変換処理の進行状況を示す"progress" 値が complete、変換後の形式を示す "outputType" 値が Viewer 表示用の svf であるなら、ドキュメントID（URN）を指定して 3D モデルを表示させることが出来るはずです。

{
  "type": "manifest",
  "hasThumbnail": "true",
  "status": "success",
  "progress": "complete",
  "region": "US",
  "urn": "dXJuOmFkc2sud2lwcHJvZDpmcy5maWxlOnZmLmdCb0VPaHE2U0lhY3F3RlBhVng5cEE_dmVyc2lvbj0x",
  "version": "1.0",
  "derivatives": [
    {
      "name": "Diesel_Car_JNR.f3d",
      "hasThumbnail": "true",
      "status": "success",
      "progress": "complete",
      "outputType": "svf",
      "children": [
        {

Item が持つすべてのバージョンの詳細を取得する場合には、endpoint https://developer.api.autodesk.com/data/v1/projects/:project_id/items/:item_id/versions、メソッド GET を利用することも出来ます。返される JSON には、各 Version の指定で利用する id （URN ）が含まれます。

4.Itemへのアクセス.postman_collectionをダウンロード

5.Version アクセス

A360 は、Version 毎に異なる id（URN）を保持していますので、A360 上の操作で特定の Version を削除しない限り、指定した Version 情報を取得して個別に Viewer で表示するようなことも出来ます。4.Item へのアクセス で紹介した endpoint https://developer.api.autodesk.com/data/v1/projects/:project_id/items/:item_id/versions、メソッド GET で、参照したい Version のid を取得してください。

  {
    "type": "versions",
    "id": "urn:adsk.wipprod:fs.file:vf.gBoEOhq6SIacqwFPaVx9pA?version=1",
    "attributes": {
      "name": "Diesel_Car_JNR.f3d",
        "displayName": "Diesel_Car_JNR.f3d",
        "createTime": "2016-12-06T05:01:30.0000000Z",
        "createUserId": "200708030638689",
        "lastModifiedTime": "2016-12-06T05:01:30.0000000Z",
        "lastModifiedUserId": "200708030638689",
        "versionNumber": 1,
        "mimeType": "application/vnd.autodesk.f3d",
        "storageSize": 49943955,
        "fileType": "f3d",
        "extension": {
          "type": "versions:autodesk.core:File",
          "version": "1.0",
          "schema": {
            "href": "https://developer.api.autodesk.com/schema/v1/versions/versions%3Aautodesk.core%3AFile-1.0"
          },
        "data": {}
      }
   },

個々の id が取得出来たら、endpoint https://developer.api.autodesk.com/data/v1/projects/:project_id/versions/:version_id、メソッド GET で、指定した Version 情報を得ることが出来ます。このとき、Version の id は、URL encode（URL エンコード） する必要があります。URL encode は、http://www.urlencoder.org/ サイトでおこなうことが出来ます。例えば、上記 JSON にある urn:adsk.wipprod:fs.file:vf.gBoEOhq6SIacqwFPaVx9pA?version=1 は、urn%3Aadsk.wipprod%3Afs.file%3Avf.gBoEOhq6SIacqwFPaVx9pA%3Fversion%3D1 にエンコードされるはずです。

取得した JSON から "derivatives" 配下の id 値を読み取ってください。この値が、その Version の URN になります。もちろん、その URN で直ぐに表示可能か否かは、Model Derivative API で Manifest をチェックすることで判別可能です。

5.Version へのアクセス.postman_collectionをダウンロード

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

ここまでの手順で Viewer に表示する URN を得ることが出来たことになります。

次の 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 起動はお勧めしません。ご注意ください。

ここでは、Folder に新しい Item、Version をアップロードしたり、アップロードした Item や Version を変換する endpoint には言及していませんが、適切な endpoint を使用することで、それらを実装することも出来ます。ここまでの内容で、 Forge が提供する Data Management API や Model Derivative API の RESTful API の利用方法は把握できるかと思います、後は、Forge ポータルのリファレンスを参照しながら、Postman で各 endpoint をお試しいただけるはずです。

By Toshiaki Isezaki