オフセットベースのページ割り

ガイドAPI呼び出しページ割りオフセットベースのページ割り

オフセットベースのページ割り

オフセットベースのページングを使用するAPIは、offsetおよびlimitクエリパラメータを使用してコレクション内の項目のページ割りを行います。

オフセットベースのページ割りは、項目のリストがあらかじめ決められた固定長の場合によく使用されます。

ページング

コレクション内のエントリの最初のページを取得するには、APIをoffsetパラメータを指定せずに呼び出すか、offset0に設定して呼び出す必要があります。limitフィールドは省略可能です。

curl https://api.box.com/2.0/folders/0/items?offset=0&limit=100 \
  -H "authorization: Bearer ACCESS_TOKEN"

エントリの次のページを取得するには、以前のoffset値と以前の結果で返された制限の合計(previous_offset + previous_limit)と等しいoffsetパラメータを指定して、APIを呼び出す必要があります。

curl https://api.box.com/2.0/folders/0/items?offset=100&limit=100 \
  -H "authorization: Bearer ACCESS_TOKEN"

offsetは、応答配列内のエントリのサイズではなく、以前のlimit分だけ加算されますので注意してください。これは制限を下回る可能性があるためです。一般的には、応答オブジェクトのlimitの値を使用してoffset値を加算することをお勧めします。

次のoffset値が応答オブジェクト内のtotal_count値を超えている場合、項目の最終ページはリクエスト済みです。この時点では、これ以上取得する項目がありません。

オフセットと制限

以下のクエリパラメータは、コレクションのページ割りに使用されます。

クエリパラメータデフォルト
offsetInteger0コレクション内の最初に返される項目の(ゼロベースの)オフセット
limitIntegerAPIによって異なる返される最大エントリ数。値が最大値を超える場合は、最大値が使用されます。

オフセットベースのページ割りの最大offset300000です。さらに大きいオフセットが必要な場合はマーカーベースのページ割りをお勧めします。

コレクション

コレクションのページ割りを行うと、APIによって、結果のセットを配列として含むオブジェクトのほか、結果の現在のページに関する情報が返されます。

フィールド
entriesArrayこのページの項目を含むページ。結果がない場合は空の配列になります。
offsetInteger結果の現在のページに使用されるオフセット
limitInteger結果の現在のページに使用される制限。この制限は、このAPIエンドポイントに許可されている最大値を超えない限り、limitクエリパラメータと同じになります。
total_countIntegerコレクション全体の最後の項目のオフセットに1を加算した値。コレクション内の項目の合計数は、total_countよりも少ない場合があります。

エンドポイントの例

以下は、オフセットベースのページ割りをサポートするエンドポイントの例です。