Box Developerドキュメント

BoxWorks 2024でコンテンツとAIの可能性について紹介します。

詳細を表示

マーカーベースのページ割り

ガイド APIコール ページ割り マーカーベースのページ割り

マーカーベースのページ割り

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

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

ページング

コレクション内のエントリの最初のページを取得するには、APIをmarkerパラメータを指定せずに呼び出すか、marker0に設定して呼び出す必要があります。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値を長期にわたって保持しないでください。

マーカーと制限

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

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

コレクション

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

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

エンドポイントの例

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