Design Automation から BIM 360 Docs への出力

Design Automation API を使って生成した成果ファイルを、BIM 360 Docs など、オートデスク SaaS が使っているストレージに保存（Design Automation から見てアップロード）する際には、少し注意が必要です。

オートデスク SaaS ストレージへファイルをアップロードする方法は、オートデスク SaaS ストレージへのファイルアップロード のブログ記事でもご案内しているとおりです。

BIM 360 Docs ストレージへのアクセスには、BIM 360 Docs ユーザの認可を求める 3-legged OAuth を使った Access Token と、スーパーユーザとしてプロジェクト間の横断的なアクセスを可能とする 2-legged OAuth を使った Access Token を、用途や目的に合わせて使い分けることが出来ます。ここでは、アクセスにユーザ認可を得るのではなく。プロジェクトを横断的にアクセスする Forge アプリが Design Automation API を使って成果ファイルをアップロードするシナリオを考えていきます。

Design Automation API でアップロードする際、Activity を次のリクエストボディ（一部抜粋）のように登録したと仮定します。

    “parameters”: {
        "DWGInput": {
            "zip": false,
            "ondemand": false,
            "verb": "get",
            "description": "Source drawing",
            "required": true
        },
        "PDFOutput": {
            "zip": false,
            "ondemand": false,
            "verb": "put",
            "description": "Output PDF drawing",
            "required": true,
            "localName": "result.pdf"
        },
        "PDFOutputToBIM360": {
            "zip": false,
            "ondemand": false,
            "verb": "put",
            "description": "Upload PDF drawing to BIM 360 Docs",
            "required": false,
            "localName": "result.pdf"
        }

この Activity を使った WorkItem を次のように指定したとします。この際、name の変数で保持するのは、Avtivity で指定した localName である result.pdf ではなく、result.pdf を格納するために WorkItem タスクの実行直前に POST projects/:project_id/storage endpoint で登録した Storage 上の出力ファイル名になります（同 endpoint のレスポンスボディが返す Storage ID から抽出した Object Name です）。例）48f8dcde-ebb2-4944-b191-34b66990aa93.pdf

 {
    "activityId": DA4A_FQ_ID,
    "arguments": {
                                       :
        "DWGInput": {
                                       :
        },    	
        “PDFOutput": {
                                       :
        }
        "PDFOutputToBIM360": {
            "url": "https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects/" + name,
            "headers": {
                "Authorization": "Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "Content-Type": "application/octet-stream"
            },
            "verb": 'put'
        },

これで、WorkItem の実行時に BIM 360 Docs 上にファイルがアップロード（保存）されるようになります。ただし、まだ足りない部分があります。BIM 360 Docs をはじめとしたオートデスクの SaaS ストレージでは、アップロードされたファイルはバージョン管理されることになります。つまり、WorkItem によってアップロードされたファイルは、バージョン付けをしないと BIM 360 Docs のユーザインタフェースには表示されません。

BIM 360 Docs に Design Automation API の成果物であるファイルを表示するには、WorkItem 終了時に通知される onComplete コールバック URL を使用して、このバージョン付けの処理を実装します。onComplete コールバックで通知を得るためには、WorkItem の登録時に次ように指定します。黄色で反転した URL については後述します。

 {
    "activityId": DA4A_FQ_ID,
    "arguments": {
                                       :
        "DWGInput": {
                                       :
        },    	
        “PDFOutput": {
                                       :
        }
        "PDFOutputToBIM360": {
            "url": "https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects/" + name,
            "headers": {
                "Authorization": "Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "Content-Type": "application/octet-stream"
            },
            "verb": 'put'
        },
        "onComplete": {
            "verb": "post",
            "url": "http://4db4af1c.ngrok.io/onComplete"
        }

もちろん、同じ Web サーバー実装で onComplete コールバック URL のルーティング実装が必要です。次のコードは、Node.js を使って express パッケージ（ミドルウェア）の router インスタンスをしたコールバック URL の実装例です。 POST projects/:project_id/items endpoint を使って、アップロードした Item（ファイル）に最初のバージョン（Version 1）を登録しています。

// onComplete callback
router.post("/onComplete", function (req, res) {

    console.log("**** onComplete callback was invoked !!");

    oAuth2TwoLegged.authenticate().then(function (credentials) {

        var payload =
        {
            "jsonapi": {
                "version": "1.0"
            },
            "data": {
                "type": "items",
                "attributes": {
                    "displayName": RESULT_PDF,
                    "extension": {
                        "type": "items:autodesk.bim360:File",
                        "version": "1.0"
                    }
                },
                "relationships": {
                    "tip": {
                        "data": {
                            "type": "versions",
                            "id": "1"
                        }
                    },
                    "parent": {
                        "data": {
                            "type": "folders",
                            "id": FOLDER_ID
                        }
                    }
                }
            },
            "included": [
                {
                    "type": "versions",
                    "id": "1",
                    "attributes": {
                        "name": RESULT_PDF,
                        "extension": {
                            "type": "versions:autodesk.bim360:File",
                            "version": "1.0"
                        }
                    },
                    "relationships": {
                        "storage": {
                            "data": {
                                "type": "objects",
                                "id": STORAGE_ID
                            }
                        }
                    }
                }
            ]
        };

        uri = "https://developer.api.autodesk.com/data/v1/projects/" + PROJECT_ID + "/items";
        request.post({
            url: uri,
            headers: {
                'content-type': 'application/vnd.api+json',
                'authorization': 'Bearer ' + credentials.access_token
            },
            body: JSON.stringify(payload)
        }, function (error, versionres, body) {
            var data = JSON.stringify(versionres);
            if (JSON.parse(data).statusCode === 201) {
                console.log(" " + STORAGE_ID + "'s version 1 was created");
            } else {
                console.log("Error : " + JSON.stringify(JSON.parse(body).errors));
            }
        });

    }, defaultHandleError);

});

ここまでの実装で、Design Automation の WorkItem から BIM 360 Docs に成果物となるファイルをアップロードして、バージョン付けすることが出来ます。

ただ、上記の例では、PDF ファイルをアップロードしているので、実際には、PDF をパブリッシュする作業（シートの抽出）が必要です。残念ながら、この作業は、対応する endpoint がないので手動操作が必要となります。

さて、最後に WorkItem のリクエストボディの JSON で触れた、黄色で反転した onComplete コールバック URL についてご案内しておきます。通常、onComplete コールバック URL には、Forge アプリのデプロイ後の URL を明記することになりますが、ここではデプロイ前のローカル PC 内で通知を得ることを想定して、ローカルに通知を得るために疑似的に URL を生成する ngrok ユーティリティを使って、http://4db4af1c.ngrok.io/名の URL を設定、WorkItem に指定しています。