前回のブログ記事で、Design Automation API for Revit パブリックベータ版公開のアナウンスを致しました。
今回は、Developer's Guide の Step-by-Step チュートリアルをベースに開発手順の流れを解説いたします。
ステップ 1 – Revit アドインの変換（もしくは新規作成）とバンドルパッケージの準備
まず、Design Automation for Revit で実行する Revit アドインを用意します。
既に Revit アドインのソースコードをお持ちの場合は、ソースコードの一部を修正して Design Automation 用に変換することができます。
パブリックベータ版では、Revit 2018 と Revit 2019 のアドインをサポートしております。
Revit アドインの開発方法については、下記のページをご参照ください。
従来の Revit アドイン開発と同様に、Microsoft Visual Studio を利用し、Revit のバージョンに対応する .NET Framework のバージョンを設定します。
- Revit 2018 -> .NET Framework 4.6
- Revit 2019 -> .NET Framework 4.7
次に参照ライブラリ（ DesignAutomationBridge.dll ）をダウンロードして、プロジェクトの参照設定に追加します。同時に、RevitAPIUI.dll を参照設定している場合は、その参照を削除します。
Revit アドインは、通常は外部アプリケーションや外部コマンドのためのインターフェースを実装しますが、Design Automation の場合は、外部DBアプリケーションインターフェースを実装します。
DesignAutomationBridge.DesignAutomationReadyEvent イベントのイベントハンドラに、実際のカスタム処理を追加します。
ローカルの Revit 環境でテストして、バグがないことを確認します。
DesignAutomationBridge.DesignAutomationReadyEvent イベントを一時的に ApplicationInitialized イベントに置き換えることで、Revit アプリケーションの初期化時にカスタム処理を実行することができます。
デバッグして問題がなければ、アセンブリファイルを指定のディレクトリ形式で ZIP 圧縮して、バンドルパッケージを作成します。
これで、Revit アドインの準備は完了です。
ステップ 2 – Forge アプリの作成
Design Automation API を利用するためには、Forge アプリを作成する必要があります。
まずは作成するアプリケーションの情報を登録して、Client ID と Client Secret を取得します。
Forge アプリは、Web 開発が主体となるため、開発環境は自由です。
サーバーには Node.js や ASP.NET などをお勧めしております。
Design Automation API を利用するために、Authentication API の 2-legged 認証によって、Access Token（アクセス トークン） を取得します。
2-legged 認証については、下記のブログ記事で解説しております。
Forge アプリでアクセストークンを取得できれば、以降は Design Automation API の呼び出しになります。
ステップ 3 – Forge アプリのニックネームの作成
Design Automation は、Forge アプリを識別するために Client ID を使用しますが、これは人間には覚えづらい文字列（例えば、YnhayiOjhgnsd&jsafh890ryehQW）となっています。
Forge アプリから Design Automation に処理を依頼するときにも、この Client ID が必要となりますが、より覚えやすいニックネームで名前を付けてマッピングを行うことができます。
ステップ 4 – Appbundle のパブリッシュ
ステップ 1 で作成した Revit アドインを Design Automation で実行するために、バンドルパッケージを Appbundle として Design Automation に登録します。
Appbundle を作成する際、任意の名前で ID を指定し、Revit アドインを実行する Revit のバージョン（2018 もしくは 2019）を指定します。
Appbundle の作成が成功すると、レスポンスの JSON データに、バンドルパッケージをアップロードするエンドポイント URL が返されます。このエンドポイント URL に対して、バンドルパッケージをアップロードします。
実はこれだけでは Appbundle の作成は完了しておりません。
作成した Appbundle は、開発中に何度もバンドルパッケージを再アップロードしたり、更新が発生します。
そのような状況に対応するために、Appbundle には、バージョンとエイリアスを指定する仕組みが備わっております。エイリアスは、Appbundle のバージョンに対して開発者が任意の名称でつけるラベルです。
たとえば、はじめて Appbundle を作成した場合、バージョンは自動的に 1 に指定されます。
このバージョンをテスト版として利用する場合は、エイリアスに test や development といった名前をつけます。
このように Appbundle のバージョン 1 に対して、test とエイリアス名をつけた場合、ステップ 3 で作成したニックネームと合わせて、Appbundle は下記のように識別することができます。
- 形式: YourNickname.SomeAppBundleId+SomeAliasName
- 例: MyFirstForgeApp.DeleteWallApp.test
ステップ 5 – Activity のパブリッシュ
ステップ 4 で登録した Appbundle では、実際にどういったデータをインプットして、どういったデータをアウトプットするのか定義しませんでした。
そのため、次は Activity を登録して、Design Automation で実行されるアクションを定義します。
たとえば、Revit モデルとテキストファイルをインプットとして Revit アドインに渡して、アドインの処理の結果として、Revit モデルを返却するといったように、入出力のパラメータを定義します。
そして、このアクション定義と Appbundle を紐づけるために、先ほどの Appbundle の識別コードを指定します。
Activity でも、バージョンとエイリアスの仕組みがありますので、任意の名前をつけます。
Activity も同様に下記のような形式で識別することができるようになります。
- 形式: YourNickname.SomeActivityId+SomeAliasName
- 例: MyFirstForgeApp.DeleteWallActivity.test
バージョンとエイリアスは、Design Automation API V3 で新規に追加された仕組みです。開発時に、リリース用、テスト用、ステージング用など、それぞれラベリングしてバージョン指定することで、開発効率が向上します。
ステップ 6 – Workitem のポスト
Appbundle と Activity の登録ができれば、最後は Design Automation にジョブを依頼します。
このジョブを Workitem と呼びます。Workitem が Activity を呼び出し、Activity は Appbundle を呼び出します。
Workitem では、Revit アドインに渡す Revit モデルやテキストファイルの実際の URL、出力結果のアップロード先のクラウドストレージの URL と、実行する Activity を指定します。
レスポンスには Workitem の ID が返却されますので、この ID を利用して、処理の進捗状況を確認することができます。
このように、WorkItem と Activity、Appbundle は相互に関連付けられて、最終的に Revit アドインが実行される仕組みになっております。
今回は、Design Automation API を利用して Forge アプリを開発する手順をご紹介しました。より詳細な解説は、先日の BIM & Forge セミナーのレコーディングとスライドでご覧いただけます。
次回は、Postman を使って実際に API を利用する方法をご紹介いたします。
By Ryuji Ogasawara
Subscribe
コメント