前回に引き続きBox APIを叩いていきます。
今回はBox Content APIのイベント通知機能について説明していきます。
Box Content APIではファイルのアップロードや削除等の各イベントの発生に対して
任意の処理を実行することが出来ます。
イベント発生の都度、任意のエンドポイントに通知するWebhookの方法と
イベントのストリームをロングポーリングして取得する方法の2つを利用することが出来ます。
Webhookによるイベント検知
イベントが発生したら、Boxが任意のエンドポイントに対して直接データを送信するPush型のアーキテクチャになります。
参考URL：https://box-content.readme.io/docs/webhooks
まず、Boxのアプリケーションの設定画面を開き、「新規Webhookの作成」ボタンをクリックします。
Webhookの設定画面が開きます。名前と説明は適当に設定。
イベントのトリガーで、どのイベントの種類をWebhookの対象とするのかを設定します。
Webhook先のエンドポイントを設定します。
ペイロードはREST、XML、SOAPのいずれかを設定できます。
ただし、XMLやSOAPはContent-Typeがapplication/x-www-form-urlencodedになる上に
ペイロード自体もXMLだと
=<?xml version="1.0" encoding="UTF-8"?>
<a>...</a>
SOAPだと
=<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Body>
</soap:Body>
</soap:Envelope>
といったように、XMLペイロードの前に=が付く仕様？なので注意が必要です。
ということで、現状は違和感のないREST方式がオススメです。
REST方式の場合は以下のようにコールバックパラメータを指定します。
GETはURLパラメータに付与されるパラメータで
POSTはリクエストBodyにapplication/x-www-form-urlencoded形式で付与されるパラメータです。
パラメータ値にはファイルの属性以外に固定値も入れることができます。
今のところWebhookには機能として認証の設定が無さそうなんですが
コールバックパラメータにAPIキー的なモノを入れることで認証処理は実現できそうです。
設定が終わったら「Webhookの保存」をクリックします。
Webhookのアプリケーション設定はユーザ毎に設定することができ
ユーザ毎のアプリケーション設定をしない限りはWebhookが飛ぶことはありません。
ということで、ユーザ毎のアプリケーションの設定をしていきます。
まず、右上のメニューからアプリケーションをクリックします。
マイアプリケーションをクリック
そうすると、作成したアプリケーションが表示されるので
アプリケーションの詳細画面に遷移して、「追加」をクリックします。
これで、当ユーザに対してWebhookが有効になります。
ロングポーリングによるイベント検知
WebhookはPush型のイベント通知だったのに対し、ロングポーリングはPull型になります。こちらはアプリケーションの設定は前回のOAuth2.0だけで対応可能になります。
参考URL：https://box-content.readme.io/docs/webhooks
まず、現時点でのストリームの位置を取得します。
$ curl https://api.box.com/2.0/events?stream_position=now \
> -H "Authorization: Bearer {ACCESS_TOKEN}"
レスポンスはこんな感じで返って来ます。
{
"chunk_size": 0,
"next_stream_position": 1437914258497,
"entries": []
}
このnext_stream_positionの値をメモっておきます。
次に、ロングポーリング用のURLを以下のリクエストで取得します。
$ curl https://api.box.com/2.0/events \
> -H "Authorization: Bearer {ACCESS_TOKEN}" \
> -X OPTIONS
レスポンスはこんな感じ。
{
"chunk_size": 1,
"entries": [
{
"type": "realtime_server",
"url": "2.realtime.services.box.net/subscribe?channel=822949d273c5f5e4da36&stream_type=all",
"ttl": "10",
"max_retries": "10",
"retry_timeout": 610
}
]
}
レスポンス内のentries[0].urlのURLパラメータに
stream_position={最初に取得した現時点のストリーム位置} を追加したURLが
ロングポーリング用のURLになります。
このURLに対してGETリクエストをして、待機します。
$curl -i -X GET \
> -H "Authorization:Bearer {ACCESS_TOKEN}" \
> 'https://2.realtime.services.box.net/subscribe?channel=822949d273c5f5e4da36&stream_type=all&stream_position=1437914258497'
イベントが発生するとレスポンスが返却されます。
{
"message": "new_change"
}
イベントストリームにアクセスしてデータを取得します。
$ curl https://api.box.com/2.0/events?stream_position=1437914258497 \
> -H "Authorization: Bearer {ACCESS_TOKEN}"
レスポンスこんな感じ
{
"entries": [
{
"type": "event",
"event_id": "131e55a64fcf707986ab79a235486ff05b30a298",
"created_by": {
"type": "user",
"id": "232537713",
"name": "hoge",
"login": "fuga@example.com"
},
"created_at": "2015-07-26T05:39:57-07:00",
"recorded_at": "2015-07-26T05:40:27-07:00",
"event_type": "ITEM_UPLOAD",
"session_id": "xxxxxx",
"source": {
"type": "file",
"id": "33876270127",
"file_version": {
"type": "file_version",
"id": "33122771667",
"sha1": "066c9d6634ce44e7cdf1e3b2942ac34f4152879b"
},
"sequence_id": "44",
"etag": "44",
...
"next_stream_position":1437914679485
}
next_stream_positionは次に使用すべきstream_positionになり、
再度ロングポーリングを行う→イベント検出→イベント抽出
というフローを繰り返してイベントを取得し続けることになります。
