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

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

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

コレクション内のエントリの最初のページを取得するには、APIをoffsetパラメータを指定せずに呼び出すか、offsetを0に設定して呼び出す必要があります。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値を超えている場合、項目の最終ページはリクエスト済みです。この時点では、これ以上取得する項目がありません。

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

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

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

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

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

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

ページング