Autodesk Developer Blog : A360 View and Data サービス API 利用の手引き

今日は、View and Data サービス API を利用するための手順を、「クイックスタートドキュメント」としてご紹介したいと思います。オリジナルの英語ドキュメントは、Autodesk Web Services API ポータル から参照することが出来ます。

概要

Autodesk View and Data API は、次の 2 つのコンポーネントから構成されています。

認証とデータアップロードに利用する REST API
Web ブラウザベースのアプリケーションに埋め込んで利用する JavaScript クライアント API

このガイドは、上記 API を使って、アカウントの作成からブラウザでモデルを表示するまでをカバーします。

ワークフローはシンプルです。

アカウントを登録してアプリケーションを作成する。
認証 API を使ってアクセストークンを取得する。アクセストークンは、他のすべての API 呼び出しで必要になります。
オブジェクト（3D モデル/2D 図面）を保存するやめのバケット（バケツ）を作成する。
バケットにオブジェクトをアップロードして、ビューイングサービスでオブジェクトを表示できるようにトランスレーションをリクエストする。
この段階で、ビューワークライアントに渡すオブジェクトの URN（Uniform Resource Name）を得ることが出来ます。

注意：ドキュメントとこのガイドに加えて、 GitHub リポジトリにある View and Data API サンプルを参照することが出来ます。>> https://github.com/Developer-Autodesk/autodesk-view-and-data-api-samples

ステップ 1: アプリケーションの登録と作成

Autodesk View and Data API では、最初に http://developer.autodesk.com へアクセスして、アカウントを作成します。これをおこなうためには、“REGISTER” をクリックして、各項目に必要な情報を入力してください。もし、既に Autodesk ID をお持ちであれば、この登録は必要ありません。

http://developer.autodesk.com の “LOGIN” から、登録したアカウント情報を使ってデベロッパーポータルにログインします。

ログインが完了したら、画面中央の My Apps をクリックしてアプリケーションを作成します。

次の画面が表示されたら、”Add a new app ＋” をクリックして、作成するアプリケーションの情報を入力していきます。

”App Name” 項にアプリケーション名を、“Callback URL” 項にWebサイトの URLを入力してください。URLが未定の場合には、ダミーで結構です（http://null.net など）。
“Product” 項には、“View and Data API” を選択してください。
入力が完了したら [Create App] をクリックします。

注意: Callback URL は、OAuth2 の 2 段階認証用のものです。この段階でコールバックが、まだ、セットアップされていなくても結構です。ただし、処理のための、この項目の入力は必須です（ダミーでも）。

アプリケーションが作成されると、Consumer Key と Consumer Secret、Callback URL が表示されます。これらの値は、次のステップで必要になるものです。

注意： Consumer Key と Consumer Secret がグレーアウトされている場合には、アプリケーションが承認待ちであることを表しています。承認を得られるまで、認証と API 呼び出しを利用することは出来ません。

ステップ 2: アクセストークンの取得

このクイックスタートガイドでは、curl（http://curl.haxx.se/）を使ってすべてのリクエストをおこないます。もちろん、他の言語で記述されるクライアントでも、原則と書式は同じです。

アクセストークンを取得するためには、Consumer Key（client_id パラメータ）と、Consumer Secret（ client_secret パラメータ）を認証 API に渡す必要があります（Create an OAuth2 token）。

curl –data “client_id=obQDn8P0GanGFQha4ngKKVWcxwyvFAGE&client_secret=eUruM8HRyc7BAQ1e&grant_type=client_credentials” https://developer.api.autodesk.com/authentication/v1/authenticate –header “Content-Type: application/x-www-form-urlencoded” -k

サーバーからのレスポンスは、JSON ボディで 200 ステータス値を持ちます。

{ “token_type” : “Bearer”, “expires_in” : 899, “access_token” : “GX6OONHlQ9qoVaCSmBqJvqPFUT5i” }

このレスポンスは、アクセストークンと有効期間（秒単位）が含まれています。アプリケーションは、この情報を保持して、古いアクセストークンの期間終了後に新しいトークンを取得します。

ステップ 3: バケットの作成

“Buckets（バケット）” は、Autodesk View and Data API で使われるデータのためのコンテナです。ファイルをアップロードする前に、バケットを作成してデータ保持ポリシーを設定します。ポリシーには次の 3 つがあります。

Transient: 24 時間だけ存続するストレージキャッシュのようなもので、一時的に利用するオブジェクトには最適です。
Temporary: 30 日間存続するストレージです。後日必要としないデータのアップロードとアクセスに適しています。このタイプのバケットストレージは、サービスが課金された際の節約に役立つかも知れません。
Persistent: 削除されるまで存続するストレージです。2年間アクセスされていないアイテムは、アーカイブされることがあります。

バケット名で使用する文字には、いくつかの制限があります。例えば、バケット名には小文字しか含めることが出来ません。詳細は、API ドキュメントを参照してください。

POST /oss/{version}/buckets API を使ってバケットを作成します。（OSS Bucket and Object API v1.0 を参照）。

curl -k –header “Content-Type: application/json” –header “Authorization: Bearer GX6OONHlQ9qoVaCSmBqJvqPFUT5i” –data “{“bucketKey”:”mybucket”,”policy”:”transient”}” https://developer.api.autodesk.com/oss/v1/buckets

注意： この例では、Windows を利用しているので、JSON ペイロードがエスケープされています。他の OS では、これをおこなう必要はありません。

この例では、“Authorization: Bearer” ヘッダーパラメータがステップ 2 からのアクセストークンを含んでいます。

バケットが作成されると、すぐに、Get Bucket Details API を使って、その存在を確認します。

curl -k -H “Authorization: Bearer GX6OONHlQ9qoVaCSmBqJvqPFUT5i” -X GET https://developer.api.autodesk.com/oss/v1/buckets/mybucket/details

成功すると、次のようなレスポンスボディが返されます。

{ “key” : “mybucket”, “owner” : “obQDn8P0GanGFQha4ngKKVWcxwyvFAGE”, “createDate” : 1401735235495, “permissions” : [{ “serviceId” : “obQDn8P0GanGFQha4ngKKVWcxwyvFAGE”, “access” : “full” } ], “policyKey” : “transient” }

ステップ 4: ファイルのアップロード

次のステップでは、表示をおこなえるようにするために、バケットにファイルをアップロードします。アップロード後には、ファイルはビューイングサービスで登録されます。現在、約 60 種類のファイル形式がサポートされています。

Autodesk DWG™
Autodesk Inventor®
Fusion 360™
SIM 360™
Autodesk Navisworks®
Autodesk Revit®
Autodesk 3Ds Max®
Solidworks®
CATIA®
Siemens Parasolid™
Siemens NX™
Siemens OpenJT™
WaveFront Technologies OBJ

サポートされるファイル形式の一覧を取得するためには、GET /viewingservice/{version}/supported API (Supported API) を利用します。

curl -k –header “Authorization: Bearer lEaixuJ5wXby7Trk6Tb77g6Mi8IL” https://developer.api.autodesk.com/viewingservice/v1/supported

This returns a response that includes an array of supported extensions for translation:

“extensions” : [“ipt”, “neu”, “stla”, “stl”, “xlsx”, “jt”, “jpg”, “skp”, “prt”, “dwf”, “xls”, “png”, “sldasm”, “step”, “dwg”, “zip”, “nwc”, “model”, “sim”, “stp”, “ste”, “f3d”, “pdf”, “iges”, “dwt”, “catproduct”, “csv”, “igs”, “sldprt”, “cgr”, “lll”, “3dm”, “sab”, “obj”, “pptx”, “cam360”, “jpeg”, “bmp”, “exp”, “ppt”, “doc”, “wire”, “ige”, “rcp”, “txt”, “dae”, “x_b”, “3ds”, “rtf”, “rvt”, “g”, “sim360”, “iam”, “asm”, “dlv3”, “x_t”, “pps”, “session”, “xas”, “xpr”, “docx”, “catpart”, “stlb”, “tiff”, “nwd”, “sat”, “fbx”, “smb”, “smt”, “dwfx”, “tif”],

“Viewing-*” のチャネル名を持つ拡張子は、ビューイングでサポートされるものです。

PUT リクエストでファイルがアップロードされます。: PUT /oss/{version}/buckets/{bucketname}/objects/{filename} API(OSS Upload API v1.0):

curl –header “Authorization: Bearer K16B98iaYNElzVheldlUAUqOoMRC” –header “Content-Length: 308331” -H “Content-Type:application/octet-stream” –header “Expect:” –upload-file “skyscpr1.3ds” -X PUT https://developer.api.autodesk.com/oss/v1/buckets/mybucket/objects/skyscpr1.3ds -k

コンテント長（Content-Length）、コンテントタイプと、Expect ヘッダーを空に設定することが重要です。この API は、大きなファイルのアップロード用に Expect ヘッダーをサポートします。詳細は、Autodesk Web Services API ポータルのドキュメントを参照してください。For more information, see the documentation.

アップロードが成功すると、次のようなレスポンスが返ります。

{ “bucket-key”: “mybucket”, “objects”: [ { “location”: “https://developer.api.autodesk.com/oss/v1/buckets/mybucket/objects/skyscpr1.3ds”, “size”: 308331, “key”: “skyscpr1.3ds”, “id”: “urn:adsk.objects:os.object:mybucket/skyscpr1.3ds”, “sha-1”: “e84021849a9f5d1842bf792bbcbc6445c280e15b”, “content-type”: “application/octet-stream” } ] }

この情報でのキーは、次のステップで必要となる id です。

もし、Inventor アセンブリ（IAM ファイル）と参照される複数パーツファイル（IPT ファイル群）のように、アップロードしたファイルが複数から構成される場合には、同じバケットにそれらのファイルをアップロードして、それぞれの ID を保持してください。

ステップ 5: 複数ファイル間の参照設定

複数のファイルから構成されるファイルをアップロードする場合のみ、このステップを実行する必要があります。Data and Viewing サービスでファイル群を登録する前には、References API を使って、それらファイル間の関係を指示する必要があります。

この API は、マスタードキュメントとなる URN と、1 つ、または、それ以上の依存関係を持つファイルの URN を指定するボディとして、JSON ドキュメントを利用します。 POST /references/{version}/setreference API (References Service REST API Specification).

次のようなかたちで、モデルの依存関係情報を持つ JSON ファイルを作成します。

{ “master” : “urn:adsk.objects:os.object:alexbicalhobucket2/A1.iam”, “dependencies” : [ { “file” : “urn:adsk.objects:os.object:alexbicalhobucket2/A1A1.iam”, “metadata” : { “childPath” : “A1A1.iam”, “parentPath” : “A1.iam” } }, { “file” : “urn:adsk.objects:os.object:alexbicalhobucket2/A1P1.ipt”, “metadata” : { “childPath” : “A1P1.ipt”, “parentPath” : “A1.iam” } }, { “file” : “urn:adsk.objects:os.object:alexbicalhobucket2/A1P2.ipt”, “metadata” : { “childPath” : “A1P2.ipt”, “parentPath” : “A1.iam” } } ] }

ステップ4からマスターと依存関係の URN での URN を置き換えて、“childPath” と “parentPath” パラメータで親子関係を関連付けます。必要なら、追加の依存関係も追加してください。この例では、 A1P1.ipt パーツと A1P2.ipt パーツ、A1A1.iam アセンブリが、マスターファイルである A1A.iam アセンブリの子となっています。

curl -k -H “Content-Type: application/json” -H “Authorization:Bearer GX6OONHlQ9qoVaCSmBqJvqPFUT5i” -i -d @references.json https://developer.api.autodesk.com/references/v1/setreference

ステップ 6: ビューイングサービスでデータを登録する

ファイルがアップロードされたら、ビューイングサービスに登録される必要があります。 POST /viewingservice/{version}/register API (Post Data) でデータを表示を準備するプロセスを起動します。

curl -k -H “Content-Type: application/json” -H “Authorization:Bearer GX6OONHlQ9qoVaCSmBqJvqPFUT5i” -i -d “{“urn”:”dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bXlidWNrZXQvc2t5c2NwcjEuM2Rz”}” https://developer.api.autodesk.com/viewingservice/v1/register

この API は、アップロードしたファイルの URN を、JSON ボディに 1 つのパラメータとして用います。ただし、ここで指定している URN は、base64 でエンコードされているため、同じようには見えません。ここと次のステップでは、URN の base64 エンコードバージョンを利用します。ユーティリティや http://www.base64encode.org/ のようなオンラインツールを使って、URN を変換することが出来ます。

注意： base64 に変換する際には、URN にキャレッジリターンや改行を入れないようにしてください。API は、改行コードを正しく扱うことが出来ません。

ここで、URN を渡して、GET /viewingservice/{version}/{urn}/status (Get Viewable) で登録の状況をチェックすることが可能です。

curl -k -i -H “Authorization: Bearer GX6OONHlQ9qoVaCSmBqJvqPFUT5i” -X GET https://developer.api.autodesk.com/viewingservice/v1/dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bXlidWNrZXQvc2t5c2NwcjEuM2Rz/status

これによって、コンポーネントパーツと同様に、ドキュメントについての情報を表示する JSON を返します。いくつかのパーツだけが “complete” ステータスを持つ場合でも、登録されたデータをビューアで表示することができることに注意してください。

登録後には、API は GET /viewingservice/{version}/thumbnails/{urn} API (Get Thumbnails) で、サムネイルイメージの取得が出来ます。

curl -k -H “Authorization: Bearer GX6OONHlQ9qoVaCSmBqJvqPFUT5i” -X GET https://developer.api.autodesk.com/viewingservice/v1/thumbnails/dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bXlidWNrZXQvc2t5c2NwcjEuM2Rz > C:UsersPublicthumb.png

ステップ 7: JavaScript ビューワーでの URN のロード

以前のステップは、 Autodesk View and Data API（ここでは curl で説明）の REST API を使用しました。ここからは、ビューワーのクライアント JavaScript API に切り替えて説明をしていきます。

はじめに、<head> と <body> 要素で、新しく、空の HTML ドキュメントを作成します。必要なスタイルとビューワーへの JavaScript を参照するために、<head> セクションに次のリンクを追加します。

次に、<script> 要素を作成して、ビューワーをセットアップするために初期化関数を追加します。

function initialize() {
    var options = {
        'document': 'urn:dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bXlidWNrZXQvc2t5c2NwcjEuM2Rz',
        'getAccessToken': getToken,
        'refreshToken': getToken,
    };
    var viewerElement = document.getElementById('viewer');
    var viewer = new Autodesk.Viewing.Viewer3D(viewerElement, {});
    Autodesk.Viewing.Initializer(options, function () {
        viewer.initialize();
        loadDocument(viewer, options.document);
    });
}

// This method returns a valid access token  For the Quick Start we are just returning the access token
// we obtained in step 2.  In the real world, you would never do this.
function getToken() {
    return "GX6OONHlQ9qoVaCSmBqJvqPFUT5i";
}

ここでの options.document パラメータは、先に作成した登録済の表示可能オブジェクト用の base64 URN となります。URN は、ドキュメントによって当然異なることになります。

getToken() 関数は、単純にアクセストークの文字列を返しています。もちろん、実運用で、このような処理をするべきではありません。loadDocument() に渡す関数には、正当な認証トークンを提供する実装を持つことが出来ます。例えば、認証 API を呼び出す Web サービスエンドポイントを呼び出すことも出来ます。クライアントの JavaScript 側で、直接、Client ID と Client Secret を公開するように、認証 API を呼び出すべきではありません。

getToken() 関数の実際の実装は、このようになるはずです。

function getToken() {
    // This method should fetch a token from a service you create to provide authentication.
    // See the ADN Samples for examples of how to create such a service.  For example, see
    // https://github.com/Developer-Autodesk/workflow-aspnet-webform-view.and.data.api/blob/master/ViewAndShare/ViewAndShare/GetAccessToken.ashx.cs
    // This method might look something like:
    var xmlHttp = null;
    xmlHttp = new XMLHttpRequest();
    xmlHttp.open("GET", "https://myservice.com/token", false);
    xmlHttp.send(null);
    var newToken = xmlHttp.responseText;
    return newToken;
}

ロード処理と、ドキュメントがロードされた際のエラーコールバックを持つ関数を追加します。

function loadDocument(viewer, documentId) {
    // Find the first 3d geometry and load that.
    Autodesk.Viewing.Document.load(documentId, function (doc) {// onLoadCallback
        var geometryItems = [];
        geometryItems = Autodesk.Viewing.Document.getSubItemsWithProperties(doc.getRootItem(), {
            'type': 'geometry',
            'role': '3d'
        }, true);
        if (geometryItems.length > 0) {
            viewer.load(doc.getViewablePath(geometryItems[0]));
        }
    }, function (errorMsg) {// onErrorCallback
        alert("Load Error: " + errorMsg);
    });
}

最後に、<body> タグへ、次のような追記をします。

WebGL をサポートする Web ブラウザで作成した HTML ファイルを開いて、URL にアクセストークンを次のように記入します（ローカルで実行している場合）。

http://localhost:8080/quickstart_3d.html?accessToken=GX6OONHlQ9qoVaCSmBqJvqPFUT5i

または、シンプルにファイルを開きます。

file://c:/path_to_file/quickstart_3d.html?accessToken=GX6OONHlQ9qoVaCSmBqJvqPFUT5i

Autodesk View and Data API サービスで、オブジェクトを表示できるはずです !!

By Toshiaki Isezaki

A360 View and Data サービス API 利用の手引き

ステップ 1: アプリケーションの登録と作成

ステップ 2: アクセス トークンの取得

ステップ 3: バケットの作成

ステップ 4: ファイルのアップロード

ステップ 5: 複数ファイル間の参照設定

ステップ 6: ビューイング サービスでデータを登録する

ステップ 7: JavaScript ビューワーでの URN のロード

Share this:

Like this:

ステップ 2: アクセストークンの取得

ステップ 6: ビューイングサービスでデータを登録する