コンテンツにスキップ
Docs
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

ページ送り

一覧の API で、件数を指定して結果を複数のページに分けて取得する方法。

一覧の API は結果を複数のページに分けて返します。1回の要求で返す件数は limit で指定し、次のページは前の応答の next_cursor を cursor に渡して取得します。

ページ送りに対応している API

現在、ページ送りに対応している API は次の1つです。

API 並び順 必要な権限
GET /products(商品の一覧) 作成日時の新しい順。同じ日時のときは ID の降順 products:read

パラメータ

クエリパラメータで指定します。

パラメータ 型 既定 範囲 説明
limit 整数 20 1〜100 1ページに返す件数です。
cursor 文字列 なし 1,024文字まで 前のページの応答の next_cursor です。最初のページでは指定しません。

ここに無いクエリパラメータを付けると、400 invalid_input が返ります。

応答の形

{
  "items": [
    { "id": "…", "name": "…" }
  ],
  "next_cursor": "…"
}
  • items: このページの結果です。商品の一覧では商品のオブジェクトが入ります。
  • next_cursor: 次のページを取得するための値です。最後のページでは null になります。結果が0件のときは、items が空の配列で、next_cursor は null です。

next_cursor は中身に意味を持たせていない文字列です。中身を解釈したり、自分で組み立てたりせず、受け取った値をそのまま次の要求に渡します。

全件を取得する手順

最初のページを取得する

cursor を付けずに呼びます。件数を変えたいときは limit を付けます。

next_cursor を確かめる

応答の next_cursor が null なら、最後のページです。ここで終わります。

次のページを取得する

next_cursor の値を cursor に入れて、同じ API を呼びます。next_cursor が null になるまで繰り返します。

例

1ページ目を10件ずつ取得します。

curl "https://api.cozeni.net/external/v1/products?limit=10" \
  -H "Authorization: Bearer $COZENI_API_KEY"

応答の next_cursor を cursor に入れて、2ページ目を取得します。

curl "https://api.cozeni.net/external/v1/products?limit=10&cursor=<前の応答の next_cursor>" \
  -H "Authorization: Bearer $COZENI_API_KEY"

サンドボックスではベース URL を https://api-sandbox.cozeni.net/external/v1 にし、サンドボックスの API キー(cozeni_sk_sandbox_ で始まる)を使います。

エラー

HTTP code 原因
400 invalid_input cursor の値が壊れているか、1,024文字を超えています。
400 invalid_input limit が1〜100の整数ではありません。
400 invalid_input 仕様に無いクエリパラメータを付けました。

ほかのエラーは エラー を参照してください。呼び出し回数の上限は レート制限 を参照してください。

このページは役に立ちましたか?