boxのアップロード/ダウンロードイベント発生時にWebhookを飛ばす

box, webhook

クラウドストレージサービスのboxを触ってみました。

SaaSの良いところは自分でAPIを使って拡張できるところだと思いますが、
例えばboxもWebhookを使ってイベント発生時に通知を行うことができます。

Webhook V1とV2がありそれぞれ以下のような違いがあります。
なんとなくV2を使用した方が良い気がするので今回はV2で試しました。

アプリケーションの構成ページで作成された V1 Webhook は、ユーザーのアカウントに含まれるすべてのオブジェクトを監視します。
Webhook V2 API を使用して作成された V2 Webhook は、Webhook の作成時に指定された個々のファイルおよびフォルダを監視します。
Webhook V2 では、Webhook を作成して管理する別の方法が提供されます。 アプリケーションの構成ページでは、V2 Webhook を作成できません。
代わりに作成と管理のために、Webhook V2 API を使用する必要があります。
Webhook V2 の詳細については、『Webhook V2 の使い方』を参照してください。

フォルダのイベントにWebhookを登録するにはBOXアプリケーションを作成する必要があります。
BOXアプリケーションには以下の2種類があり役割が違います。

  • BOX統合
    • boxの認証を使用してユーザが自分の権限でファイルを操作したりするアプリケーションを作成する。
    • 原則、OAuthを利用したWeb画面の認証を用いる(アプリ開発者向けにトークンの発行も可能)
  • BOX PLATFORM
    • OAuthと別にアプリ用のユーザを作成してJWT認証も可能
    • アプリのユーザがboxと連携するのでユーザにboxのアカウントを意識させない(ことも可能)

ちょっと分かりづらいかもしれませんが「BOX統合」はBOXの機能を拡張するアプリケーションで、
「BOX PLATFORM」はBOXをバックエンドとしたアプリケーションというイメージです。

今回は認証をアプリ用のユーザで行いたかったので「BOX PLATFORM」でアプリを構築します。

boxにサインアップ

まず自分のメールアドレスで「開発者」アカウントを作成します。
(*通常のサインアップと入り口が違うので注意!)

アプリケーションの作成

  1. 開発者コンソールからアプリを作成
  • https://app.box.com/developers/console
    「MyApps」 -> 「アプリの新規作成」 -> 「カスタムアプリ」で「次へ」
    「JWTを使用したOAuth2.0」認証を選択。アプリの名前を適当に入力します。
    以下のコマンドが出てくるので試してみます。自分が見れるフォルダの一覧が出てきたら動作検証OKです。

作成したアプリケーションの登録

  1. 2段階認証の設定
    アプリケーションからの認証に必要な「公開キー」を登録するには2段階認証の設定が必須です。
    ユーザの設定から2段階認証の設定をします。

  2. 公開キーの作成
    以下のコマンドで生成します。パスワードも設定しましょう。

  3. DeveloperConsoleで公開キーの設定
    https://app.box.com/developers/console/app//configuration
    DeveloperConsoleに生成した公開キー(上のコマンドではpublic_key.pemで生成された方)を登録します。
    アプリケーションの設定「公開キーの追加と管理」の「公開キーを追加」から中身をコピペで追加します。
    公開キーを追加するとIDが自動で振られます。あとで使うのでとっておいてください。

  4. 管理コンソールでアプリケーションを承認
    https://app.box.com/master/settings/openbox
    「管理コンソール」 > 「Business設定」 > 「アプリ」 > 「新しいアプリケーションを承認」を選択
    「APIキー」を入力するように言われるのでわかりづらいですが「クライアントID」を入れればOKです。

AppUserの作成

ここからはコードを書きます。PythonのSDKに不具合があり使えなかったのでnode.jsでやります。
box-node-sdkを使用します。

まず、SDKに認証情報を渡して初期化します。

続いてAppUserを作成します。
「エンタープライズID」は「管理コンソール > Business設定」から確認できます。

実行結果はこちら。これでAppUserの作成は完了です。

AppUserをフォルダに招待する

AppUserは通常のユーザと同様にコラボレーションに参加できるのでメールアドレスで招待を送れます。
Webhookを送信したいフォルダへのアクセスを許可するために通常ユーザからAppUserに対してフォルダへの
招待を送ったら「承諾」というフローが必要なのですがAppUserはログインできないのでこれまたAPIから
「承諾」を実施する必要があります。以下は雑ですが「招待」されたフォルダを全て「承諾」するコードです。

Webhookの登録

  1. requestbinで送信先のエンドポイントを作成します
    requestbinの説明は割愛します。便利なサービスです。
    ここで注意なのが生成されるURLはhttpなのですがWebhookへはhttpsのURLしか登録できません。
    requestbinはhttpsにも対応していますので画面に表示されたURLをhttpsに変更して使用します。

  2. Webhookを登録します
    SDKの初期化までは先ほどと同じ手順です。
    ここではクライアントにAppUserを使用しますので先ほど作成したAppUserのIDを設定します。
    フォルダIDは画面から確認もできますしクライアントからフォルダの一覧を取得することもできます。
    画面から確認する場合は「https://app.box.com/files/0/f/{フォルダID}/{フォルダ名}」
    のようになってますので、Webhookを登録したいフォルダにアクセスできる場合は画面から取得します。

  3. ファイルをアップロードしてrequestbinを確認
    Webhookを登録したフォルダにファイルをアップロードすると、
    requestbinにWebhookが届いているのが確認できます。

まとめ

box APIをBOX PLATFORMから使い始めるまでは少し手順が多くて面倒ですが、
一度環境ができてしまえばファイルに触り放題なので楽しいです。

Webhook V2はフォルダ毎に違う呼び先に飛ばせるのが特徴なので、
次はフォルダ毎に別々のAWS Lambdaを呼び出すみたいなのも作ってみようと思います。

box, webhook