Forge Webhooks API ローカル開発環境について

Forge Webhooks API での通知の受け取りについて の記事で、Wibhooks API から通知を受けるコールバック URL の実装についてご紹介しました。Forge サーバーは、Webhooks API で登録（指定）されたコールバック URL を RESTful API の POST メソッドで呼び出すことになりますが、この時、コールバック URL を実装する Web サーバーが、Forge サーバーからアクセス可能なパブリックな場所にデプロイされている必要があります。

Forge アプリ（Web サーバー）をローカル PC で開発中の場合には、Forge サーバーがコールバック URL を見つけられないので（はずなので）、Webhook からの通知を得ることが出来ないことになります。例えば、ローカル環境でポート番号 1337 を使って Forge アプリを開発している場合、Web ブラウザの URL ボックスに http://localhost:1337 と入力することで、同 PC 内で Forge アプリの動作を確認することが可能なはずです。もし、この Forge アプリに /callback でコールバック URL をルーティング実装したと仮定すると、Webhooks API でコールバック URL を登録すると、次のようになるはずです。

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

        var data = JSON.stringify(credentials);
        var token = JSON.parse(data).access_token;

        // Create Webhooks
        uri = "https://developer.api.autodesk.com/webhooks/v1/systems/derivative/events/extraction.finished/hooks";
        var payLoad =
            {
                "callbackUrl": "http://localhost:1337/callback",
                "scope": {
                    "workflow": WEBHOOK_TENANT
                }
            };
        request.post({
            url: uri,
            headers: {
                'content-type': 'application/json',
                'authorization': 'Bearer ' + token,
            },
            body: JSON.stringify(payLoad)
        }, function (error, webhookres, body) {
                                                 <以下省略>

ただし、前述のとおり、このコールバック URL はパブリックでないため、Forge サーバーが通知を送ることが出来ません。こんな時に利用するのが、ローカルな環境を透過的にすることが出来る ngrok です。ngrok は、パブリックアドレスでトラフィックを受け取り、そのトラフィックをマシン上で実行されている ngrok プロセスに中継し、指定したローカルアドレスに中継します。別の言い方をするなら、ngrok がローカルな URL をパブリックにして通知を受け取り、ローカルな環境（先の例では http://localhost:1337）上の /callback へ通知の橋渡しをしてくれます。

ngrok を利用するには、https://ngrok.com/download からアーカイブされている ngrok.exe（Windows の場合 zip ファイル）をダウンロードして、コマンドプロンプト上で ngrok <プロトコル> <ポート番号> と入力して実行するだけです。

このコマンドを実行すると、ngrook の実行中のみ、ローカル ⇔ パブリックの橋渡し（トンネル化）効果を得ることが有効になります。

上記の例では、ngrook セッションの間（ngrook の実行中）、ローカルな http://localhost:1337 は http://7149283e.ngrok.io または https://7149283e.ngrok.io として参照可能な状態になります。このため、ローカル Web サーバーの実装内で、次のように Wenhooks API のコールバック URL を登録すると、Forge サーバーからの通知（呼び出し）を受けることが可能になるわけです。

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

        var data = JSON.stringify(credentials);
        var token = JSON.parse(data).access_token;

        // Create Webhooks
        uri = "https://developer.api.autodesk.com/webhooks/v1/systems/derivative/events/extraction.finished/hooks";
        var payLoad =
            {
                "callbackUrl": "http://7149283e.ngrok.io/callback",
                "scope": {
                    "workflow": WEBHOOK_TENANT
                }
            };
        request.post({
            url: uri,
            headers: {
                'content-type': 'application/json',
                'authorization': 'Bearer ' + token,
            },
            body: JSON.stringify(payLoad)
        }, function (error, webhookres, body) {
                                                  <以下省略>

ngrok のセッション毎（実行毎）に異なるパブリック URL が割り当てられることにご注意ください。このため、ngrok を使ったローカル環境での開発/デバッグでは、都度、Webhook API に登録するコールバック URL を書き換える必要があります。

By Toshiaki Isezaki