マーカーベースのページネーション

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

マーカーベースのページネーションがよく使用されるのは、項目の全セットの長さが頻繁に変更される場合や全体の長さが事前にわからない可能性がある場合です。

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

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

オフセットベースのページネーションとマーカーベースのページネーションの両方をサポートするAPIでは、マーカーベースのページネーションが使用されるようにusemarkerクエリパラメータをtrueに設定する必要があります。

エントリの次のページを取得するには、APIレスポンスで受け取ったnext_marker値の値に等しいmarkerパラメータを指定して、APIを呼び出す必要があります。

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

次のnext_marker値がレスポンスオブジェクト内でnullになっている場合、項目の最終ページはリクエスト済みです。この時点では、これ以上取得する項目がありません。

マーカーベースのページングを使用する場合、コレクション内のエントリの合計数を確認するには、エントリをすべて取得するしかありません。マーカーの内部実装は今後変更される可能性があるため、アプリケーションではnext_marker値を長期にわたって保持しないでください。

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

クエリパラメータ	型	デフォルト
`marker`	String		コレクション内で最初に結果を返す位置。これは前のリクエストで返された値です。
`limit`	Integer	APIによって異なる	返される最大エントリ数。値が最大値を超える場合は、最大値が使用されます。
`usemarker`	Boolean		ページネーションのタイプを選択するために、両タイプのページネーションをサポートするAPIエンドポイントで使用可能なクエリパラメータ (省略可)。`true`に設定すると、マーカーベースのページネーションが適用されます。

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

フィールド	型
`entries`	Array	このページの項目を含むページ。結果がない場合は空の配列になります。
`next_marker`	String	結果の次のページを取得するために`marker`値として使用できる値。この値が`null`または空の文字列の場合は、これ以上取得する結果がありません。
`limit`	Integer	結果の現在のページに使用される制限。この制限は、このAPIエンドポイントに許可されている最大値を超えない限り、`limit`クエリパラメータと同じになります。

以下は、マーカーベースのページネーションをサポートするエンドポイントの例です。

ページング