前回のブログ記事では、Design Automation API for Revit について、Postman サンプルで動作を確認するためのテスト環境のセットアップ手順をご紹介しました。
今回は、実際に Postman サンプルで動作を確認してみましょう。
Postman サンプルには、以下の３つのサンプルが同梱されていますが、今回は、SketchIt サンプルを使用します。
CountIt サンプル
Revit プロジェクトと Revit リンクに配置されている壁、床、ドア、窓カテゴリの数量を集計し、その結果をテキストファイルで出力します。
どのカテゴリを集計するかをプロパティで指定することができます。
SketchIt サンプル
新規の Revit プロジェクト上に壁と床を作成するサンプルです。結果は、Revit プロジェクトファイルとして出力します。
プロパティで作成する壁や床の座標を指定します。
DeleteWalls サンプル
既存の Revit プロジェクト上に配置されている壁を全て削除して、別の Revit プロジェクトとして出力します。
1. 環境変数の確認と Revit アドインのバンドルパッケージの準備
前回の手順で、環境変数を設定いただきましたが、もう一度、環境変数が設定されているか確認しましょう。
Forge アプリの Client ID と Client Secret、そして Nickname をそれぞれ設定します。
※ニックネームはグローバルで一意でなければなりません。他のユーザーに既に使用されている場合は、そのニックネームを使用することはできません。
同様に、Revit アドインのバンドルパッケージをローカルにダウンロードしておきます。
※右側のリンクからダウンロードした場合、システムの都合上、ファイル名が全て小文字になってしまいます。お手数をおかけしますが、それぞれ左のファイル名に名前を変更してご利用ください。
- SketchItApp.zip（リンクが切れている場合は こちら からダウンロードできます。）
2. Authentication API によるアクセス トークンの取得
まず、Design Automation API を利用するために、Authentication API の 2-legged 認証によって、Access Token（アクセス トークン） を取得します。
エンドポイントは、https://developer.api.autodesk.com/authentication/v1/authenticate、メソッドは POST となります。
2-legged 認証のワークフローについては、こちらのブログ記事（Forge での OAuth 認証シナリオ）をご参照ください。
Postman コレクションの[Authentication]フォルダ配下にある [New token]リクエストを選択します。
すると、[New token]リクエストの画面がメイン画面に表示されます。
Headers タブをアクティブにすると、Content-Type パラメータに "application/x-www-form-urlencoded" という値が予め設定されております。
Body タブをアクティブにすると、client_id、client_secret、grant_type、scope の各パラメータが確認できます。
この API のエンドポイントに POST リクエストを送信する際、Client ID と Client Secret は、Postman の環境変数に設定されている値が自動的に入力されるよう参照が設定されております。
そして、grant_type と scope というパラメータにも予め値が設定されています。
- grant_type は、サーバー間の認証の場合、client_credentials を指定します。
- scope は、Design Automation API の場合、コードの生成と実行の権限に相当する、code:all を指定します。
Access Token と Scope に関する解説は、こちらのブログ記事（Access Token について）をご参照ください。
Send ボタンをクリックすると、リクエストが送信され、レスポンスには、アクセス トークンとその有効期限が返却されます。
取得されたアクセス トークンは、環境変数に新たに dasApiToken パラメータとして追加されます。以降の Design Automaion API のリクエストには、この環境変数のパラメータを通じて、アクセス トークンが設定されます。
3. Nickname の作成
Postman コレクションの [Nickname]フォルダ配下にある[Create nickname]リクエストを選択します。
エンドポイントは、https://developer.api.autodesk.com/da/us-east/v3/forgeapps/me、メソッドは PATCH となります。
Headers タブをアクティブにすると、Content-Type パラメータに "application/json" という値が予め設定されております。また、Authorization パラメータには、"Bearer {{dasApiToken}}" として環境変数 "dasApiToken"を参照するよう設定されています。マウスカーソルを変数の上に移動すると、設定される実際の値がツールチップで表示されます。
Body タブをアクティブにすると、nickname パラメータの値に、環境変数"dasNickName"を参照するように設定されているのが確認できます。
レスポンスには、Status 200 OK が返却されます。
Nickname が作成できたら、環境変数"dasNickName"の CurrentValue にも同じ値をセットします。
4. AppBundle の登録
Postman コレクションの [SketchItApi]->[App]->[Create]フォルダ配下にある[Create app]リクエストを選択します。
エンドポイントは、https://developer.api.autodesk.com/da/us-east/v3/appbundles、メソッドは POST となります。
Body タブでは、リクエストパラメータに、AppBundle の id、使用する engine、description を設定します。
それぞれの値は予め設定されています。
エンジンは、Revit アドインを実行する際に使用する Revit のバージョンを指定します。
現状の Design Automation API for Revit では、Revit 2018 と Revit 2019 に対応しています。
レスポンスには、リクエストで送信したパラメータに加えて、AppBundle のバージョンと、Revit アドインのバンドルパッケージをアップロードするためのクラウドストレージの URL とそれに必要なパラメータが返却されます。
初めて AppBundle を作成した場合、初回はバージョン 1 が自動的に付与されます。
5. Revit アドインのバンドルパッケージのアップロード
Postman コレクションの [SketchItApi]->[App]->[Create]フォルダ配下にある[Upload app to Design Automation]リクエストを選択します。
エンドポイントは、AppBundle 登録時に返されたアップロード URLで、メソッドは POST となります。
Body タブでは、リクエストパラメータに、AppBundle 登録時のレスポンスで取得したパラメータがそれぞれ設定されています。
file パラメータの値フィールドにある Select Files ボタンをクリックして、アップロードする Revit アドインのバンドルパッケージを選択します。
レスポンスには、Status 200 OK が返却されます。
6. AppBundle の Alias の登録
Postman コレクションの [SketchItApi]->[App]->[Create]フォルダ配下にある[Create a new app alias]リクエストを選択します。
エンドポイントは、https://developer.api.autodesk.com/da/us-east/v3/appbundles/SketchItApp/aliases、メソッドは POST となります。
Body タブでは、AppBundle のバージョンを指定して、そのバージョンに対するエイリアスを設定します。ここでは、"test"という Alias を登録します。
レスポンスには、Status 200 OK で設定した値が返却されます。
7. Activity の登録
エンドポイントは、https://developer.api.autodesk.com/da/us-east/v3/activities、メソッドは POST となります。
Body タブでは、JSON 形式で、Activity の定義を送信します。
"id": Activity を識別するための ID
"commandLine": 実行するエンジンのパスと引数
"parameters": 入出力のファイルに関する詳細な定義
"engine": アプリケーションのエンジンとバージョン（Autodesk.ApplicationName+Version）
"appbundles": AppBundle の指定（Nickname.AppBundleId.AliasId）
"description": 説明
"parameters"の"sketchItInput"プロパティは、入力ファイルの定義です。
Design Automation API 側からみたときに、処理を実行するために取得する必要があることから、"verb"の値は、"get"を指定します。
SketchIt サンプルは、新規に Revit プロジェクト上に壁と床を作成するため、予め入力として Revit プロジェクトは必要ありません。
ただし、作成する壁や床の座標データを送る必要があります。
この座標データは、JSON 形式の文字列で WorkItem のリクエストパラメータで送信します。そして、送信された座標データは、JSON ファイルとして作業領域（ワーキングディレクトリ）に一時的に保存され、Revit アドインのプログラムから JSON ファイルを開いてデータにアクセスすることができます。
Revit プロジェクトを入力として送信した場合も同様に、作業領域（ワーキングディレクトリ）に一時的に保存され、WorkItem の処理が終了したら、自動的に作業領域は削除されます。
"parameters"の"result"プロパティは、出力ファイルの定義です。
出力結果を任意のクラウドストレージにアップロードすることから、"verb"の値は、"put"を指定します。
レスポンスには、Status 200 OK で設定した値が返却されます。
8. Activity の Alias の登録
AppBundle の Alias の登録と同様に、Activity にも Alias を登録します。ここでは、AppBundle の Alias と同じ "test" が設定されていますが、別の名称でも問題ありません。
レスポンスには、Status 200 OK で設定した値が返却されます。
これで、Design Automation API の Nickname、AppBundle と Activity の登録ができました。
次回は、WorkItem の作成、処理結果を出力するためのクラウドストレージの URL の取得、WorkItem の進捗確認と処理結果のダウンロードまでの動作を確認します。
By Ryuji Ogasawara
Leave a Reply