Design Automation API for Revit - Postman Sample で動作確認 2

前回のブログ記事に引き続き、Postman で SketchIt サンプルの動作を確認する手順をご紹介します。
既に AppBundle と Activity の登録が完了している状態ですので、今回は、実際のジョブとなる WorkItem を作成して、処理結果を取得するところまでを解説いたします。

9. WorkItem の作成

Postman コレクションの [SketchItApi]->[WorkItem]フォルダ配下にある[Send Workitem]リクエストを選択します。

エンドポイントは、https://developer.api.autodesk.com/da/us-east/v3/workitems、メソッドは POST となります。

Body タブでは、JSON 形式で、WorkItem のパラメータを送信します。

"activityId": Activity ID の指定
"arguments": Activity で定義した入出力のパラメータに対応する実際の値

"sketchItInput"プロパティの"url"には、JSON 形式の座標データを、"result"プロパティの"url"には、処理結果を出力するクラウドストレージの URL を設定します。

ここでは、環境変数"sketchItResultUrl"を参照するように設定されていますが、これまでのステップでは、この URL はまだ取得しておりません。

そのため、WorkItem 作成のリクエストは、この段階では完了することはできません。

実は、WorkItem で設定するファイル（Revit プロジェクトやテキストファイル）のクラウドストレージの URLは、事前に取得しなければなりません。
そして、この URL のことを、署名付き URL （Signed URL）といいます。

Forge の Data Management API では、この署名付き URL（Signed URL）を取得する方法がサポートされています。

以降、Forge の Data Management API を利用して、署名付き URL（Signed URL）を取得する手順を説明いたします。

10. Authentiocan API によるアクセス トークンの取得

前回、Design Automation API を利用するために、2-legged 認証で、scope をコードの生成と実行の権限に相当する、"code:all" に指定してアクセス トークンを取得しました。

Data Management API を利用するためには、前回とは異なるリソースへのアクセス権限が必要になります。

"bucket:read bucket:update bucket:create bucket:delete data:write data:create data:read"

Postman コレクションの[DataAPI]->[Authentication]フォルダ配下にある [New token]リクエストを選択します。
すると、[New token]リクエストの画面がメイン画面に表示されます。

Body タブをアクティブにすると、scope パラメータに上記のスコープの値が設定されていることが確認できます。

Send ボタンをクリックすると、リクエストが送信され、レスポンスには、アクセス トークンとその有効期限が返却されます。
取得されたアクセス トークンは、環境変数に新たに dataApiToken パラメータとして追加されます。

以降の Data Management API のリクエストには、この環境変数のパラメータを通じて、アクセス トークンが設定されます。

11. Bucket の作成

Postman サンプルでは、処理結果の出力先に、OSS（ Object Storage Service） の Bucket を利用します。
Bucket に関する解説は、下記のブログ記事をご参照ください。

• Forge が使用するクラウド ストレージ
  
• Bucket に関してのサマリー
  
  

Postman コレクションの[DataAPI]->[Bucket]フォルダ配下にある [Create Bucket]リクエストを選択します。

エンドポイントは、https://developer.api.autodesk.com/oss/v2/buckets、メソッドは POST となります。

Body タブをアクティブにすると、bucketKey パラメータに環境変数"bucketKey"が設定されることがわかります。
policyKey パラメータには、24時間有効な "transient"が設定されています。

※環境変数"bucketKey"は、アクセストークン取得時のスクリプト処理（[Tests]タブに記載されているスクリプト）で、自動的に環境変数"dasNickName"を小文字変換した文字列が設定されます。別の名前で Bucket を作成したい場合は、この値を変更してください。

リクエストを送信すると、レスポンスには、200 OK と Bucket の情報が返却されます。

12. 処理結果を出力する Revit プロジェクトファイルの保存場所を確保する

Bucket が作成できたら、次はファイルを保存するための場所を確保する必要があります。

エンドポイントは、https://developer.api.autodesk.com/oss/v2/buckets/:bucketKey/objects/:objectName、メソッドは PUT となります。

このエンドポイントは、ファイルのデータを送信することで、直接ファイルをアップロードすることもできますが、この段階では、Revit ファイルはまだ作成されていないため、データは送信しません。

そのため、ここでは SketchIt.rvt というファイルの保存場所を確保します。

レスポンスには、200 OK と確保したファイルの保存場所の情報が返却されます。

13. 書き込みアクセス権のある署名付き URL （Signed URL）の取得

確保したファイルの保存場所から、書き込みアクセス権のある署名付きURLを取得します。

エンドポイントは、https://developer.api.autodesk.com/oss/v2/buckets/:bucketKey/objects/:objectKey/signed で、メソッドは POST です。

このエンドポイントは、指定された有効期限内にオブジェクトをダウンロード・アップロードするために使用できる署名付きURLを作成します。
署名付きURLが指すオブジェクトが削除されるか、または署名付きURLが期限切れになる前に期限切れになると、署名付きURLは無効になります。

URLが最初に１度だけ使用された後に期限切れになるようにURLを設定したり、URLへの読み取りまたは書き込みアクセス権を設定することもできます。

アクセス権は、URL クエリパラメータとして、以下 のいずれかを指定して設定できます。

• access=read
• access=write
• access=readwrite

したがって、今回は、確保したファイルの保存場所に Revit プロジェクトファイルを保存するため、access=write を設定します。

レスポンスには、200 OK と併せて、署名付き URL （Signed URL）が返却されます。

※AWS S3 でも類似の事前署名付き URL （Pre-signed URL）がサポートされております。詳細はこちらの記事（署名付き URL を使用したオブジェクトのアップロード）をご参照ください。

14. WorkItem の作成

ステップ 10 ～ 13 で、処理結果を出力するための署名付き URL （Signed URL）を取得することができました。
これでようやく、ステップ 9 WorkItem の作成に戻って、リクエストを送信することができます。

既に環境変数"sketchItResultUrl" には、事前署名付き URL （Pre-signed URL）が設定されています。

もう一度、Postman コレクションの [SketchItApi]->[WorkItem]フォルダ配下にある[Send Workitem]リクエストを選択し、Send ボタンをクリックして、リクエストを実行します。

レスポンスには、200 OK と合わせて、WorkItem の処理の進捗状況を表す status と、WorkItem の ID が返却されます。

15. WorkItem 進捗状況の確認

WorkItem ID を通じて、処理の進捗状況とログを確認することができます。

エンドポイントは、https://developer.api.autodesk.com/da/us-east/v3/workitems/:id で、メソッドは GET です。

status の値は、下記のいずれかが返されます。
処理に失敗した場合は failedInstructions、成功した場合は success となります。

• pendinginprogress
• cancelled
• failedDownload
• failedInstructions
• failedUpload
• failedLimitProcessingTime
• failedLimitDataSize
• success

reportUrl の値は、ログファイルの URL です。ブラウザからアクセスして、report.txt というファイルをダウンロードすることができます。

16. 処理結果のダウンロード

最後に Data Management API を利用して処理結果をダウンロードします。

エンドポイントは、https://developer.api.autodesk.com/oss/v2/buckets/:bucketKey/objects/:objectName、メソッドは GET です。

リクエストを送信後、レスポンスの右上にある Download ボタンをクリックすると、SketchIt.rvt を取得できます。
Revit 2018 で開いて確認してみましょう。

Postman サンプルでの動作確認は終わりです。
ご興味のある方は、他の2つのサンプルもお試しください。

次回は、Learn Autodesk Forge チュートリアルのサンプルを動作確認するためのセットアップ手順をご紹介します。

By Ryuji Ogasawara