WebHooks API：VS Code から ACC 監視を登録

APS の WebHooks API を利用すると、オートデスクのクラウドサービスで発生したイベントを検出、APS アプリに通知してくれます。この手法で Autodesk Construction Cloud（ACC）上の挙動を把握することが出来ます。

APS の WebHooks API は様々なイベントをサポートしていますが、この内、ACC 上の監視で取得することが出来るイベントは Data Management Events に記載のあるとおりです。

WebHooks API は、VS Code APS エクステンションで簡単に登録することが出来るので、実際のアプリ実装前に動作の評価・検証が可能です。ここでは、ACC 上のフォルダ追加を例に、テストの手順をご紹介しておきたいと思います。

事前把握が必要な情報

ACC プロジェクトにフォルダが追加された通知を得るためには、POST systems/:system/events/:event/hooks エンドポイントで dm.folder.added イベントと一緒に通知を得るためのコールバック URL を登録する必要があります。

この時必要になるのが、監視対象のプロジェクトの Project Id と、監視対象のフォルダーの Folder Id（URN）です。言い換えれば、Postman などを使って、事前に Project Id と Folder Id（URN）を把握しておいてください。

ここでは、次の Project Id と Folder Id の値を想定して、イベント通知をテストしてみます。

WebHook の登録（作成）

ここでは、コールバック URL に Webhook.site という WebHook のテストに便利なサイトを無償枠で使用します。Web ブラウザで https://webhook.site/ を表示すると、Your unique URL にコールバック URL に使用出来る URL が表示されますので、クリップボードにコピーしておきます。
VS Code を起動して、APS エクステンションサイドバーの WebHooks パネルから Folder Added を見つけて、マウスの右クリックボタンで [Create Webhook] を選択します。
VS Code 上に [Create Webhook] タブが表示されるので、あらかじめ設定されている System 項と Event 項を除いた項目に値を指定します。Scope 項には、監視対象の Folder Id（urn:adsk.wipprod:fs.folder:co.FtKfsRS2Re6g0keqduq8tw）を、Callback URL 項には Webhook.site からコピーした URL（https://webhook.site/080759ea-11f8-4df1-a50b-297d60044e65）を、また、Attribute 項には Project Id を示す JSON 値（{"projectId":"b.2bff3069-8411-49ae-ab1b-7d6d5747dfd7"}）を指定します。すべの値が指定出来たら、タブ画面下部の [Create] ボタンをクリックします。
WebHook の登録が完了すると、WebHooks パネルから Folder Added 下に作成した WebHook が表示されます。

補足・注意事項

dm.folder.added イベントの通知を得るためには、Autodesk Construction Cloud にアクセスする必要があることを意味します。つまり、同イベントの WebHook を登録する APS アプリの Client ID は、事前に「カスタム統合」が必要になります。「カスタム統合」の具体的な手順は、次の記事でご案内しています。
- ACC：新しいカスタム統合 UI
- Autodesk Construction Cloud と APS 統合で必要なカスタム統合
WebHooks の登録には、2-legged、または、3-legged 認証フロー共に利用することが出来ます。VS Code APS エクステンションでは、複数の Client ID の切り替えをサポートしています。VS Code APS エクステンションの Client ID 切り替えの内容を確認してみてください。APS エクステンションでも利用することが出来ます。
dm.folder.added イベントを含む Data Management イベントの監視に必要なエンドポイントの呼び出し手順、および、リクエストボディ等の詳細は、Creating a Webhook (Data Management) で紹介されています。