Long pollingイベント

Boxアカウントでアクティビティのリアルタイム通知を取得するために、OPTIONS /events APIのLong polling機能を使用できます。

curl -i -X OPTIONS "https://api.box.com/2.0/events" \
     -H "authorization: Bearer <ACCESS_TOKEN>"

events = client.events().generate_events_with_long_polling()
for event in events:
    print(f'Got {event.event_type} event')

client.events.getEventStream(function(err, stream) {
  if (err) {
    // handle error
  }
  stream.on('data', function(event) {
    // handle the event
  });
});

Long polling

Long pollingでは、HTTPリクエストを開き、サーバーがレスポンスを送信するまでそのリクエストを開いたままにして、そのプロセスを何度も繰り返して更新されたレスポンスを受信します。

Long polling URL

Long pollingを使用するには、まず、リクエストをOPTIONS /events APIに送信し、Long polling URLを取得します。

curl -X OPTIONS https://api.box.com/2.0/events \
    -H "authorization: Bearer ACCESS_TOKEN"

{
  "chunk_size": 1,
  "entries": [
    {
      "type": "realtime_server",
      "url": "http://2.realtime.services.box.net/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all",
      "ttl": 10,
      "max_retries": 10,
      "retry_timeout": 610
    }
  ]
}

リアルタイムサーバー

次に、指定されたURLにGETリクエストを実行してイベントのリッスンを開始します。監視対象のアカウントでイベントが発生すると、new_changeという値を持つレスポンスが送信されます。レスポンスにはその他の詳細は含まれていません。

この単一のレスポンスは、最新の既知のstream_positionを使用してGET /eventsエンドポイントにリクエストを送信するなど、後続の処理を促すことを目的としています。

切断と再接続

サーバーは、このレスポンスを送信した後に接続を閉じます。この時点でアプリケーションがイベントのリッスンを再開するには、Long pollingのプロセスを繰り返す必要があります。

アプリケーションがリアルタイムサーバーに接続してもその後しばらくイベントが発生しないと、接続が閉じられ、reconnectという値が返されます。この状況になると、アプリケーションはプロセスを再開するためにOPTIONS /eventsに対する新しい呼び出しを実行する必要があります。

タイムアウトと再試行

retry_timeoutで指定した秒数以内にアプリケーションがイベントを受け取らなければ、アプリケーションはリアルタイムサーバーに再接続できます。これは、ネットワークエラーが発生すると必要になる場合があります。

アプリケーションがリアルタイムサーバーに対してGETリクエストを送信したときにmax_retriesエラーが返された場合は、/events APIに対してOPTIONS呼び出しを実行してプロセスを再開する必要があります。