メインコンテンツへスキップ
バージョン: 最新版

ページネーション

Omise APIのページネーションで大規模な結果セットを効率的にナビゲートします。limitとoffsetパラメータを使用して、管理可能なチャンクでデータを取得する方法を学びます。

概要​

多くのOmise APIエンドポイントはリソースのリスト（課金、顧客、振込など）を返します。レスポンスを高速で管理しやすくするために、これらのエンドポイントはページネーションされた結果を返します。リクエストごとに取得するアイテム数とどのページを取得するかを制御できます。

クイックスタート
  • limitを使用してページあたりのアイテム数を制御（デフォルト: 20、最大: 100）
  • offsetを使用してアイテムをスキップしてページをナビゲート
  • totalで存在するアイテムの総数を確認
  • すべてのリストレスポンスは同じ構造

ページネーションパラメータ​

limit​

タイプ: 整数 デフォルト: 20 範囲: 1-100 目的: リクエストごとに返すアイテム数

# リクエストごとに50件の課金を取得
curl https://api.omise.co/charges?limit=50 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

offset​

タイプ: 整数 デフォルト: 0 目的: 結果を返す前にスキップするアイテム数

# 最初の20件の課金をスキップして次の20件を返す
curl https://api.omise.co/charges?offset=20&limit=20 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

from​

タイプ: ISO 8601 日時 デフォルト: 1970-01-01T00:00:00Z 目的: 返されるレコードの開始を制限するUTC日時

# 2025年1月1日以降に作成された課金を取得
curl "https://api.omise.co/charges?from=2025-01-01T00:00:00Z" \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

to​

タイプ: ISO 8601 日時 デフォルト: 現在のUTC時刻 目的: 返されるレコードの終了を制限するUTC日時

# 2025年2月1日以前に作成された課金を取得
curl "https://api.omise.co/charges?to=2025-02-01T00:00:00Z" \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

order​

タイプ: 文字列 デフォルト: reverse_chronological オプション: chronological, reverse_chronological 目的: 返されるレコードのソート順

# 時系列順（古い順）で課金を取得
curl "https://api.omise.co/charges?order=chronological" \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

# 逆時系列順（新しい順、デフォルト）で課金を取得
curl "https://api.omise.co/charges?order=reverse_chronological" \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

組み合わせの例​

# アイテム41-60を取得（1ページ20件で3ページ目）
curl https://api.omise.co/charges?offset=40&limit=20 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

すべてのパラメータを使用した完全な例​

# 2025年1月の課金を古い順で、2ページ目を取得
curl "https://api.omise.co/charges?from=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&order=chronological&limit=20&offset=20" \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

リストレスポンス形式​

すべてのページネーションエンドポイントは一貫したリスト構造を返します:

{
  "object": "list",
  "data": [
    {
      "object": "charge",
      "id": "chrg_test_5xuy4w91xqz7d1w9u0t",
      "amount": 100000,
      ...
    },
    {
      "object": "charge",
      "id": "chrg_test_5xuy4w91xqz7d1w9u0a",
      "amount": 50000,
      ...
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 142,
  "from": "2025-01-01T00:00:00Z",
  "to": "2025-02-07T23:59:59Z",
  "order": "chronological",
  "location": "/charges"
}

リストオブジェクトのフィールド​

フィールドタイプ説明
objectstringページネーションレスポンスでは常に"list"
dataarrayリソースオブジェクト（課金、顧客など）の配列
limitintegerページあたりのアイテム数（リクエストから）
offsetintegerスキップされたアイテム数（リクエストから）
totalintegerすべてのページにわたるアイテムの総数
fromstring (ISO 8601)クエリ期間の開始日（オプション）
tostring (ISO 8601)クエリ期間の終了日（オプション）
orderstringソート順: "chronological"または"reverse_chronological"
locationstringAPIエンドポイントパス

ページネーション対応エンドポイント​

以下のエンドポイントはページネーションをサポートします:

コアリソース​

エンドポイントデフォルト順序説明
GET /charges逆時系列すべての課金を一覧表示
GET /customers逆時系列すべての顧客を一覧表示
GET /transfers逆時系列すべての振込を一覧表示
GET /refunds逆時系列すべての返金を一覧表示
GET /transactions逆時系列すべての取引を一覧表示
GET /disputes逆時系列すべての異議申し立てを一覧表示
GET /recipients逆時系列すべての受取人を一覧表示
GET /events逆時系列すべてのイベントを一覧表示
GET /schedules逆時系列すべてのスケジュールを一覧表示
GET /links逆時系列すべての決済リンクを一覧表示

ネストされたリソース​

エンドポイント説明
GET /customers/:id/cards顧客のカードを一覧表示
GET /charges/:id/refunds課金の返金を一覧表示
GET /customers/:id/charges顧客の課金を一覧表示

基本的なページネーション例​

デフォルトのページネーション​

最初の20件のアイテムを取得（デフォルトの動作）:

curl https://api.omise.co/charges \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

レスポンス:

{
  "object": "list",
  "data": [...],
  "limit": 20,
  "offset": 0,
  "total": 142
}

カスタムページサイズ​

1ページあたり50件のアイテムを取得:

curl https://api.omise.co/charges?limit=50 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

2ページ目にナビゲート​

最初の20件をスキップして次の20件を取得:

curl https://api.omise.co/charges?offset=20&limit=20 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

最大アイテム数を取得​

100件のアイテムを取得（許可される最大）:

curl https://api.omise.co/charges?limit=100 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

ベストプラクティス​

1. 適切なページサイズを使用​

// ✅ 良い例 - ユースケースに基づいてサイズを選択

// UI表示用（ユーザーを圧倒しない）
const charges = await omise.charges.list({ limit: 20 });

// 一括処理用（効率を最大化）
const chargesForExport = await omise.charges.list({ limit: 100 });

// リアルタイム更新用（レイテンシを最小化）
const recentCharges = await omise.charges.list({ limit: 10 });

2. ページネーションエラーを処理​

# ✅ 良い例 - ページネーションエラーを処理
import omise

def safe_list_charges(offset=0, limit=20, max_retries=3):
    for attempt in range(max_retries):
        try:
            return omise.Charge.list(offset=offset, limit=limit)

        except omise.errors.BaseError as e:
            if attempt == max_retries - 1:
                raise

            if e.http_status >= 500:
                # サーバーエラー - リトライ
                time.sleep(2 ** attempt)
                continue
            else:
                # クライアントエラー - リトライしない
                raise

charges = safe_list_charges(offset=0, limit=50)

3. ページ番号を正しく計算​

// ✅ 良い例 - 正確なページ計算

function calculatePageInfo(offset, limit, total) {
  const currentPage = Math.floor(offset / limit) + 1;
  const totalPages = Math.ceil(total / limit);
  const itemsOnPage = Math.min(limit, total - offset);

  return {
    currentPage,
    totalPages,
    itemsOnPage,
    firstItemNum: offset + 1,
    lastItemNum: offset + itemsOnPage,
    hasNextPage: offset + limit < total,
    hasPrevPage: offset > 0
  };
}

// 例
const info = calculatePageInfo(40, 20, 142);
console.log(info);
// {
//   currentPage: 3,
//   totalPages: 8,
//   itemsOnPage: 20,
//   firstItemNum: 41,
//   lastItemNum: 60,
//   hasNextPage: true,
//   hasPrevPage: true
// }

クイックリファレンス​

ページネーションパラメータ​

パラメータタイプデフォルト範囲説明
limit整数201-100ページあたりのアイテム数
offset整数00-∞スキップするアイテム数

リストレスポンスフィールド​

{
  "object": "list",
  "data": [...],       // アイテムの配列
  "limit": 20,         // ページあたりのアイテム数
  "offset": 0,         // スキップされたアイテム数
  "total": 142,        // 総アイテム数
  "from": "...",       // 開始日（オプション）
  "to": "...",         // 終了日（オプション）
  "order": "...",      // ソート順
  "location": "..."    // エンドポイントパス
}

ページを計算​

// 現在のページ番号
const currentPage = Math.floor(offset / limit) + 1;

// 総ページ数
const totalPages = Math.ceil(total / limit);

// 次のページがあるか
const hasNextPage = offset + limit < total;

// 前のページがあるか
const hasPrevPage = offset > 0;

// 次のページのoffset
const nextOffset = offset + limit;

// 前のページのoffset
const prevOffset = Math.max(0, offset - limit);

関連リソース​

次へ: べき等性で操作を重複させることなく安全にリクエストを再試行する方法を学びましょう。

FAQ​

1回のリクエストで取得できるアイテムの最大数はいくつですか？

最大limitは1リクエストあたり100件です。より多くのアイテムが必要な場合は、offsetパラメータを調整して複数のリクエストでページネーションを使用してください。

リクエスト間で総数は変わりますか？

はい、totalカウントはデータの現在の状態を反映します。リクエスト間で新しいアイテムが作成または削除された場合、総数は変わります。正確なページネーションのために、各レスポンスで常にtotalを確認してください。

結果を昇順（古い順）で並べ替えることはできますか？

はい、orderパラメータを使用できます。order=chronologicalを設定すると古いものから新しいものへ、order=reverse_chronological（デフォルト）を設定すると新しいものから古いものへ結果を取得できます。

すべてのデータを効率的にエクスポートするにはどうすればよいですか？

最大limitの100を使用し、ページを反復処理してください。レート制限を尊重するため、リクエスト間に小さな遅延を追加してください。非常に大きなデータセットの場合は、すべてをメモリに読み込むのではなく、結果をファイルにストリーミングすることを検討してください。

オフセットの代わりに特定のID以降の結果を取得する方法はありますか？

Omiseはオフセットベースのページネーションを使用しています。カーソルベースまたはIDベースのページネーションはありません。結果をナビゲートするにはoffsetとlimitを使用してください。

総数より大きいオフセットをリクエストするとどうなりますか？

APIは正しいtotalカウントとともに空のdata配列を返します。これはエラーではなく、単にそのオフセットには取得するアイテムがないことを示しています。