今日は、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）。
サーバーからのレスポンスは、JSON ボディで 200 ステータス値を持ちます。
このレスポンスは、アクセス トークンと有効期間（秒単位）が含まれています。アプリケーションは、この情報を保持して、古いアクセス トークンの期間終了後に新しいトークンを取得します。
ステップ 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 を参照）。
注意： この例では、Windows を利用しているので、JSON ペイロードがエスケープされています。他の OS では、これをおこなう必要はありません。
この例では、“Authorization: Bearer” ヘッダー パラメータがステップ 2 からのアクセス トークンを含んでいます。
バケットが作成されると、すぐに、Get Bucket Details API を使って、その存在を確認します。
成功すると、次のようなレスポンス ボディが返されます。
ステップ 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) を利用します。
This returns a response that includes an array of supported extensions for translation:
“Viewing-*” のチャネル名を持つ拡張子は、ビューイングでサポートされるものです。
PUT リクエストでファイルがアップロードされます。: PUT /oss/{version}/buckets/{bucketname}/objects/{filename} API(OSS Upload API v1.0):
コンテント長（Content-Length）、コンテント タイプと、Expect ヘッダーを空に設定することが重要です。この API は、大きなファイルのアップロード用に Expect ヘッダーをサポートします。詳細は、Autodesk Web Services API ポータル のドキュメントを参照してください。For more information, see the documentation.
アップロードが成功すると、次のようなレスポンスが返ります。
この情報でのキーは、次のステップで必要となる 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 ファイルを作成します。
ステップ4からマスターと依存関係の URN での URN を置き換えて、“childPath” と “parentPath” パラメータで親子関係を関連付けます。必要なら、追加の依存関係も追加してください。この例では、 A1P1.ipt パーツと A1P2.ipt パーツ、A1A1.iam アセンブリが、マスターファイルである A1A.iam アセンブリの子となっています。
ステップ 6: ビューイング サービスでデータを登録する
ファイルがアップロードされたら、ビューイング サービスに登録される必要があります。 POST /viewingservice/{version}/register API (Post Data) でデータを表示を準備するプロセスを起動します。
この API は、アップロードしたファイルの URN を、JSON ボディに 1 つのパラメータとして用います。ただし、ここで指定している URN は、base64 でエンコードされているため、同じようには見えません。ここと次のステップでは、URN の base64 エンコード バージョンを利用します。ユーティリティや http://www.base64encode.org/ のようなオンライン ツールを使って、URN を変換することが出来ます。
注意： base64 に変換する際には、URN にキャレッジ リターンや改行を入れないようにしてください。API は、改行コードを正しく扱うことが出来ません。
ここで、URN を渡して、GET /viewingservice/{version}/{urn}/status (Get Viewable) で登録の状況をチェックすることが可能です。
これによって、コンポーネント パーツと同様に、ドキュメントについての情報を表示する JSON を返します。いくつかのパーツだけが "complete" ステータスを持つ場合でも、登録されたデータをビューアで表示することができることに注意してください。
登録後には、API は GET /viewingservice/{version}/thumbnails/{urn} API (Get Thumbnails) で、サムネイル イメージの取得が出来ます。
この例のサムネイルは、次のようなになります。
ステップ 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 にアクセス トークンを次のように記入します（ローカルで実行している場合）。
または、シンプルにファイルを開きます。
Autodesk View and Data API サービスで、オブジェクトを表示できるはずです !!
By Toshiaki Isezaki
Subscribe
コメント