Design Automation API for Inventor - Postman Sample での動作確認

前回の記事では、Design Automation API for Inventorのチュートリアルを行うためのPostmanサンプルのセットアップを行いました。

今回はセットアップしたPostmanコレクションを使い、以下の手順に従ってDesign Automation APIの動作を確認してみたいと思います。

なお、以下手順での（）内の記載は、対応するPostmanコレクションのタスク名となります。

アクセストークンの取得（Task 1 - Obtain an Access Token）
ニックネームの作成（Task 2 - Create a Nickname）
AppBndleをDesign Automationにアップロード(Task 3 - Upload an AppBundle)
Activityの公開(Task 4 - Publish an Activity)
クラウドストレージの準備(Task 5 - Prepare cloud storage)
WorkItemの作成(Task 6 - Submit a WorkItem)
結果のダウンロード(Task 7 - Download the Result)

１．アクセストークンの取得（Task 1 - Obtain an Access Token）

１-１．Forge Appの作成と、Client ID と Client Secretの取得

前回の記事のPostman Sampleのセットアップでも記載しましたが、Design Automation API を実行するためには、Forge Appを作成する必要があります。また、作成したForge Appにアクセスするためには、Client ID と Client Secret が必要となります。

今回のサンプルを実行するために、以下の過去のブログ記事を参考に、"Design Automation API V3" および "Data Management API"の設定と、取得をお願いいたします。

Forge API を利用するアプリの登録とキーの取得

１-２．Client ID と Client SecretをPostmanの環境変数に設定

前回の記事でPostmanに設定したDA4Inventor環境には、 "client_id" と "client_secret"という環境変数があります。この環境変数に値を設定することで、Forge APIを実行する際に必要となる、これらの値を個別に指定する必要がなくなります。

1-2-1．Postman アプリケーションの右上にある"Environment quick look"アイコンをクリック

1-2-2．”client_id"行の”CURRENT VALUE"カラムをクリックすると、編集アイコンが表示されます。

1-2-3．編集アイコンをクリックして、利用するForge AppのClient IDを入力します。

1-2-4．同様に"client_secret"行の、編集アイコンをクリックして、利用するForge AppのClient Secret を入力します。

1-2-5．"Environment quick look"アイコンをクリックして、環境設定を終了します。

１-3．アクセストークンの取得

アクセストークンを取得するためには、Forgeに対して認証リクエストを送信する必要があります。それでは、Postmanコレクションを使用して、認証リクエストを送信してみましょう。

1-3-1．Postmanのサイドバーで、「Task 1 - Obtain an Access Token」-「POST Get an Access Token」を選択します。

1-3-2．ボディタブを選択

1-3-3．マウスカーソルを、"client_id"のValueカラムに合わせて、1-2で設定した値が設定されていることを確認します。同様に"client_secret"についても値を確認します。

1-3-4．「Send」ボタンをクリックし、リクエストをForgeに送信します。リクエストに成功した場合は、以下のスクリーンショットにあるような期限付きのアクセストークンを含むレスポンスが表示されます。

ここで取得したアクセストークンは、Postmanの環境変数”dasApiToken”に保存されます。サンプルのPostmanコレクションは、Task2以降のリクエストを送信する際に、この変数の値をアクセストークンとして使用するよう作られているため、以降のTaskの実行時に手作業で指定する必要はありません。

言うまでもありませんが、同様の処理をプログラムから行う場合には、Postmanコレクションが行っているのと同様の処理を作成し、各HTTPリクエストでアクセストークンを指定する必要があることにご注意ください。

２．ニックネームの作成（Task 2 - Create a Nickname）

Forgeでは、Client IDをアプリケーションを一意に識別するIDとしてClient IDを使用します。ただし、Client IDは人間にとっては、わかりにくい、意味を持たない文字列のため、Forge アプリケーションのデータを参照する際にストレスを感じてしまいまし。この点を解消するために、Forgeでは、Client IDを人間にとってわかりやすい意味を持った文字にマッピングする、ニックネームという仕組を用意しています。

本チュートリアルでは、Postmanの"dasNickName"環境変数にニックネームを保存して、以降のリクエストで使用します。

２-１．ニックネームを変数に設定

2-1-1．Postman アプリケーションの右上にある"Environment quick look"アイコンをクリック

2-1-2．”dasNickName"行の”CURRENT VALUE"カラムに、アプリケーションの任意のニックネームを入力します。

2-1-3．"Environment quick look"アイコンをクリックして、環境設定を終了します。

２-２．ニックネームリクエストを送信

2-2-1．Postmanのサイドバーで、「Task 2 - Create a Nickname」-「PATCH Create Nickname」を選択します。

2-2-2．「Send」ボタンをクリックし、リクエストをForgeに送信します。リクエストに成功した場合は、以下のスクリーンショットにあるようなレスポンスが表示されます。レスポンスはヘッダーのみで、ボディはありません。

注意事項

データをForge アプリケーションに追加した場合は、ニックネームを設定することは出来ません。この場合に、アプリケーションにニックネームを設定する唯一の方法は、 [DELETE] /forgeapps/me エンドポイントを使用して、ニックネームを含むすべてのデータをアプリケーションから削除することになります。Postmanコレクションの「Extras」-「Delete Forge App Data in Design Automation」を用いて、[DELETE] /forgeapps/meエンドポイントを呼び出すことができます。

もし本チュートリアルの途中で躓いてしまい進めることができない場合、本リクエストを使用して、アプリケーションからすべてのデータクリアしてTask 1からやり直しをしてみてください。
ニックネームはグローバルに一意である必要があります。このため、もし指定したニックネームが既に使用されている場合、Forgeは409 Conflict errorを返します。

３．AppBndleをDesign Automationにアップロード(Task 3 - Upload an AppBundle)

AppBundleはパッケージ化された、カスタムコマンドを実行するバイナリファイルとサポートファイルです。本チュートリアルでは、サンプルのAppbundle（samplePlugin.bundle）を使用します。このサンプルのAppBundleには、パートまたはアセンブリファイルを読み込み、指定されたサイズに変更後にビットマップファイルを生成するInventorのプラグインファイルが含まれています。

３-１．AppBundleをダウンロード

SamplePlugin.bundleファイルをダウンロード

３-２．AppBundleの登録

3-2-1．Postmanのサイドバーで、「Task 3 - Upload AppBundle」-「POST Register the AppBundle」を選択します。

3-2-2．ボディタブを選択して、idの値が”ChangeParamApp”で、engineの値が”Autodesk.Inventor+24” (Inventor 2020)であることを確認します。

3-2-3．「Send」ボタンをクリックして、リクエストを送信します。リクエストが成功すると以下のスクリーンショットのようなレスポンスが表示されます。

レスポンスのuploadParametersには、AppBundleをForgeにアップロードするための情報が含まれています。この情報は、Postmanの環境変数に保存され、以降の手順で使用されます。

３-３．AppBundleをアップロード

3-3-1．Postmanのサイドバーから「Task 3 - Upload AppBundle」－「POST Upload the AppBundle」を選択します。

3-3-2．ボディタブを選択して、スクロールを下に移動して"file"行を表示します。

3-3-3．Value列の”Select Files”をクリックしてダウンロードをしたsamplePlugin.bundle.zipを選択します。

3-3-4．「Send」をクリックして、リクエストを送信します。リクエストが成功すると、以下のスクリーンショットにあるようなレスポンスが返ります。レスポンスはヘッダーのみでボディはありません。

３-４．AppBundleのエイリアスを登録

先のステップで、AppBundleの登録した際に、バージョン１のAppBudleが登録されています。このステップでは、バージョン１のAppBundleに、 ”my_working_version”という名前のエイリアスを作成します。

3-4-1．Postmanのサイドバーで、「Task 3 - Upload AppBundle」－「POST Create an Alias for the AppBundle」を選択します。

3-4-2．ボディタブを選択して、idの値が"my_working_version"であることを確認します。

3-4-3．「Send」ボタンをクリックして、リクエストを送信します。成功した場合、以下のスクリーンショットのようなレスポンスが返ります。

４．Activityの公開(Task 4 - Publish an Activity)

本ステップでは、Design Automationで実行するアクションとなる Activityを作成します。

４-１．新規Activityの作成

4-1-1．Postmanのサイドバーから、「Task 4 - Publish an Activity」－「POST Create a New Activity」を選択します。

4-1-2．ボディタブを選択してActivityのパラメータを確認します。

Activityのパラメータについて

idは作成するActivityの名前となります。この値は、Postmanの環境変数"dasActivityName"に保存されます。
commandLineは、Activityを実行する際のコマンドラインとなります。コマンドラインには、変数を指定することができ、Activity実行時に実際の値と置き換えられます。
- $(engine.path)\\InventorCoreConsole.exe - Inventorエンジンのフルパス。リクエストボディに利用するInventorのバージョンを、 “engine”: “Autodesk.Inventor+24" (Inventor+24はInventor 2020)の形で指定します。
- $(args[InventorDoc].path) - InventorDocパラメータで指定されるドキュメントがダウンロードされるフォルダのフルパス。
- $(appbundles[ChangeParamApp].path) - Appbundleパラメータで指定した、AppBundleがUnzipされるフルパス。
- $(args[InventorParams].path) - 高さと幅のパラメータ（プラグインに指定する値）を記述したJSONファイルへのフルパス。
parametersには、Activityの実行時に必要な入力と出力を定義します。入力パラメータには"verb":"get"を出力パラメータには"verb":"put"を指定します。
engineには、Activity実行時に使用するDesign Automation エンジン（この場合はInventor 2020）を指定します。
appbundlesは、commandLineから参照され、Activityで使用するAppBundleのIDを指定します。このパラメータは配列形式で指定しますが、Design Automation for Inventorでは、Activityに対して一つのAppBundleのみが指定可能です(Design Automation for AutoCAD では、複数のAppBundleを指定可能)。
settingsには、Activityで実行するコマンドスクリプトを指定します。チュートリアルではスクリプトは実行しないため空となります。

4-1-3．「Send」をクリックしてリクエストを送信します。リクエストが成功すると、以下のスクリーンショットのようなレスポンスが返されます。ChangeParamActivityに、どのように名前（id）設定されたかを確認してください。

４-２．ActivityのAliasを作成

先のステップでActivityを作成した際、バージョン１のActivityが作成されました。Activityには、新しいバージョンを作ることができるため、Activityのidのみでは、どのバージョンのActivityを使用するのかを指定することができません。特定のバージョンのActivityに対応するAliasを作成して使用することで、特定のバージョンのActivityを指定することができます。Aliasに対応するバージョンは後から変更することも可能です。

以下の手順で、version 1のChangeParam Activityに"my_current_version"というAliasを作成します。

4-2-1．Postmanのサイドバーから「Task 4 - Create an Activity」－「POST Create an Alias to the Activity」を選択します。

4-2-2．ボディタブを選択し、Aliasの idに”my_current_version”が設定されていることを確認します。

4-2-3．「Send」をクリックしてリクエストを送信します。リクエストが成功すると以下のスクリーンショットのようなレスポンスが戻されます。

５．クラウドストレージの準備(Task 5 - Prepare cloud storage)

チュートリアルで作成したChangeParamActivityは、Inventorのパートまたはアセンブリの高さと幅を、JSONオブジェクトで指定した値に変更します。また、同時にパートまたはアセンブリの画像ファイルを作成します。

Step５では、入力となるInventorファイルおよび、出力されるInventorファイルと画像ファイルを保存するクラウドストレージの設定を行います。ForgeのDesign Automationでは様々なクラウドストレージを利用することができますが本チュートリアルでは、Forge Data Management APIを使って、Object Storage Service (OSS)を使用することにします。

このタスクを実行にあたって以下の５つのPostmanの環境変数を指定する必要があります。

ossBucketKey - 入力となるファイルが格納されたBucketのBucketキー
ossInputFileObjectKey - Inventorパートファイルのオブジェクトキー
ossOutputIptFileObjectKey - Activityで生成される、リサイズ後のパートファイルを格納するプレースフォルダーのオブジェクトキー
ossOutputIamFileObjectKey - Activityで生成される、リサイズ後のアセンブリファイルを格納するプレースフォルダーのオブジェクトキー
ossOutputBmpFileObjectKey - Activityで生成される、画像ファイルを格納するプレースフォルダーのオブジェクトキー

５-１．Bucketの作成

5-1-1．Postman アプリケーションの右上にある"Environment quick look"アイコンをクリック

5-1-2．"ossBucketKey"行の、CURRENT VALUEカラムに、入力となるInventorファイルを格納するBucket名指定します。

Bucket名は、OSSサービス内で一意である必要があります。もし指定したBucketが既に存在する場合、以下の手順5-1-5で、409 conflict errorが返されます。その場合は、値を変更して再度実行をしてください。
Bucket名には、アルファベット小文字、0-9の数字、アンダースコアが使用できます。

5-1-3．"Environment quick look"アイコンをクリックして変数のリストを閉じます。

5-1-4．Postmanサイドバーから「Task 5 - Prepare Cloud Storage」－「POST Create a Bucket」を選択します。

5-1-5．「Send」をクリックしてリクエストを送信します。リクエストが成功すると以下のスクリーンショットのようなレスポンスが返されます。

５-2．入力ファイルをOSSにアップロード

5-2-1．入力となるInventorパートファイルをダウンロードします。

Box.iptをダウンロード。

5-2-2．Postman アプリケーションの右上にある"Environment quick look"アイコンをクリック

5-2-3．"ossInputFileObjectKey"行の、CURRENT VALUEカラムに、入力となるInventorファイルのObject Key(入力ファイルをOSSにアップロード後に一意に特定するための名前)を指定します。

5-2-4．"Environment quick look"アイコンをクリックして変数のリストを閉じます。

5-2-5．Postmanのサイドーバーから、「Task 5 - Prepare Cloud Storage」ー「PUT Upload Input File」を選択します。

5-2-6．ボディタブをクリックします。

5-2-7．「Select File」をクリックし、ダウンロードしたbox.iptを指定します。

5-2-8．「Send」をクリックしリクエストを送信します。リクエストが成功すると以下のスクリーンショットのようなレスポンスが戻されます。

5-3．一時ダウンロードURLの取得

Design Automationでは、入力ファイルをダウンロードして処理を実施します。このステップでは、Design Automationで利用可能な、入力ファイルをダウンロードするためのテンポラリーのサイン済みURLを取得します。このURLの有効期限は1時間です。

5-3-1．Postmanのサイドバーから「Task 5 - Prepare Cloud Storage」－「POST Get Temporary Download URL」を選択。

5-3-2．「Send」をクリックしリクエストを送信します。リクエストが成功すると以下のスクリーンショットのようなレスポンスが返され、テンポラリーのURLが取得できます。URLはTestタブのスクリプトでURLをPostmanの環境変数”ossInputFileSignedUrl”に保存されます。

5-4．出力iptファイルのアップロード用一時URLを取得

Design Automationでは、Activityが出力するサイズ変更後のiptファイルをUploadするためのサイン済みURLを使用します。本ステップでは、Design Automationが利用できるテンポラリのサイン済みURLを取得します。このURLの有効期限は1時間です。

5-4-1．Postman アプリケーションの右上にある"Environment quick look"アイコンをクリック。

5-4-2．"ossOutputIptFileObjectKey "行の、CURRENT VALUEカラムに、出力されるInventorファイルのObject Key(出力ファイルをOSSにアップロード後に一意に特定するための名前)を指定します。

5-4-3．"Environment quick look"アイコンをクリックして変数のリストを閉じます。

5-4-4．Postmanのサイドーバーから、「Task 5 - Prepare Cloud Storage」－「POST Get Temporary Upload URL for Output IPT File」を選択します。

5-4-5．「Send」をクリックして、リクエストを送信します。リクエストが成功すると以下のスクリーンショットのようなレスポンスが返さ、テンポラリーのURLが取得できます。URLはTestタブのスクリプトでPostmanの環境変数”ossOutputIptFileSignedUrl”に保存されます。

5-5．出力BMPファイルのアップロード用一時URLを取得

Design Automationでは、Activityが出力する画像ファイルをUploadするためのサイン済みURLを使用します。本ステップでは、Design Automationが利用できるテンポラリのサイン済みURLを取得します。このURLの有効期限は1時間です。

5-5-1．Postman アプリケーションの右上にある"Environment quick look"アイコンをクリック。

5-5-2．"ossOutputBmpFileObjectKey "行の、CURRENT VALUEカラムに、出力される画像ファイルのObject Key(出力ファイルをOSSにアップロード後に一意に特定するための名前)を指定します。

5-5-3．"Environment quick look"アイコンをクリックして変数のリストを閉じます。

5-5-4．Postmanのサイドーバーから、「Task 5 - Prepare Cloud Storage」－「POST Get Temporary Upload URL for Output BMP File」を選択します。

5-5-5．「Send」をクリックして、リクエストを送信します。リクエストが成功すると以下のスクリーンショットのようなレスポンスが返さ、テンポラリーのURLが取得できます。URLはTestタブのスクリプトでPostmanの環境変数”ossOutputBmpFileSignedUrl”に保存されます。

６．WorkItemの作成(Task 6 - Submit a WorkItem)

Design AutomationにWorkItemの実行を指示することにより、Design AutomationはWorkItem内で指定されたActivityを実行します。

ActivityとWorkItemの関係は、ちょうどプログラミングにおける”関数”と”関数の呼び出し”ととらえることができます。Activityの名前付きパラメータには、対応するWorkItemの名前付き引数をが存在します。関数呼び出しでのオプショナルパラメータと同様に、Activityのオプショナルパラメータは、WorkItemで指定せずにスキップをすることが可能です。

本チュートリアルでは、”ChangeParamActivity” Activityを実行するWorkItemを作成します。このWorkItemは、先のステップでアップロードしたiptファイルを入力ファイルとして使用します。

このリクエストを実行すると、ossInputFileSignedUrl変数のサイン済みURLからiptファイルをダウンロードして使用します。

6-1．WorkItemの作成

6-1-1．Postmanのサイドーバーから、「Task 6 - Submit a WorkItem」－「Create a WorkItem」を選択します。

6-1-2．ボディタブを選択して、Activity ID、入力ファイル、出力ファイルの指定を確認します。

6-1-3．「Send」をクリックしてリクエストを送信します。リクエストが成功すると以下のスクリーンショットのようなレスポンスが戻されます。

以下は、JSONペイロードの主なアトリビュートとなります。

activityId - 実行するActivityを指定します。
arguments - Activityに指定する必要のあるすべてのパラメータを含みます。このパラメータは、Activityの作成時に指定したパラメータと一致する必要があります。
InventorDoc - Activity実行時に使用するInventorのパートファイルを指定します。この値はPostmanの"ossInputFileSignedUrl"変数に保持されています。

参考

IPTファイルの代わりにZipファイルをアップロードした場合、ZIPファイル内のパスを指定するpathInZipに、ZIPファイル内のパスを指定する必要があります。

InventorParams - JSONオブジェクトを用いて、新しいパートファイルでの、高さと幅を指定します。
OutputIpt - サイズを変更したパートファイルを格納するクラウドストレージのサイン済みURLを指定します。この値は、Postmanの"ossOutputIptFileSignedUrl"変数に保持されています。
OutputBmp - 出力した画像ファイルを格納するクラウドストレージのサイン済みURLを指定します。この値は、Postmanの"ossOutputBmpFileSignedUrl"変数に保持されています。

6-2．WorkItemのステータスを確認

Design AutomationのWorkItemは実行キューに入れられて、順次実行されます。実行完了後に、成功・失敗を確認する必要があります。このため、 WorkItemのステータスを確認する必要があります。

6-2-1．Postmanのサイドーバーから、「Task 6 - Submit a WorkItem」ー「Check Status of a WorkItem」を選択します。

6-2-2．「Send」をクリックしてリクエストを送信します。リクエストが成功すると以下のスクリーンショットのようなレスポンスが戻されます。

注意

本チュートリアルでは、WorkItemの実行状態をリクエストを送信して確認をしています。Design Automation APIを用いて、実際のアプリケーションを作成する場合、WorkItemの作成時に”onComplete”引数を指定してWorkItemの実行が完了した際に呼び出されるコールバックURLを指定する方法を推奨いたします。詳細については、Forgeポータルのドキュメントからコールバックをご参照ください。

７．結果のダウンロード(Task 7 - Download the Result)

WorkItemがActivityの実行を完了したらDesign Automationは結果ファイルをOSSにアップロードします。Forge Data Management APIを使用してローカル環境に結果ファイルをダウンロードすることができます。

7-1．IPTファイルをダウンロードする

7-1-1．Postmanのサイドーバーから、「Task 7 - Download the Results」ー「GET Download Resized IPT file from OSS」を選択します。

7-1-2．「Send」をクリックしてリクエストを送信します。リクエストが成功すると以下のスクリーンショットのようなレスポンスが戻されます。