# ページ分割の仕組み

リストエンドポイントと検索エンドポイントの結果をページ分割する方法をご紹介します。

ビデオチュートリアルを使用したページ分割については、[このプレイリスト](https://www.youtube.com/playlist?list=PLy1nL-pvL2M7AvG4xrF6gmbSUW2FBUl9p)を参照してください。

Stripe API には、Customer の一覧表示や PaymentIntents の検索など、複数のオブジェクトを返すことができるリストエンドポイントと検索エンドポイントがあります。パフォーマンスへの悪影響を考慮し、これらのエンドポイントは一度にすべての結果を返しません。代わりに、Stripe は API コールが実行されるごとに結果を記したページを返します。各ページには、デフォルトで最大 10 件の結果が記されます。[limit](https://docs.stripe.com/api/pagination.md#pagination-limit) パラメーターを使用して、ページあたりの結果数を変更できます。

たとえば、これは Customer を一覧表示する API リクエストで、次の 3 つの `limit` があります。

```curl
curl -G https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d limit=3
```

Stripe からのレスポンスには、次の 3 つの結果を記したページが含まれます。

```json
{
  "data": [
    {
      "id": "cus_005",
      "object": "customer",
      "name": "John Doe",
    },
    {
      "id": "cus_004",
      "object": "customer",
      "name": "Jane Doe",
    },
    {
      "id": "cus_003",
      "object": "customer",
      "name": "Jenny Rosen",
    },
  ],
  "has_more": true,
  /* ... */
}
```

これらのエンドポイントを使用する際は、次の点に注意してください。

- オブジェクトは `data` プロパティ内にあります。
- オブジェクトは時系列の逆順で、最後に作成されたオブジェクトが最初のオブジェクトになります。
- `has_more` プロパティは、この要求で返されなかった追加のオブジェクトがあるかどうかを示します。

`data` 配列をループしてオブジェクトを通過する代わりに、結果をページ分割する必要があります。これにより、[has_more](https://docs.stripe.com/api/pagination.md#pagination-has_more) パラメーターが `true` のときに一部のオブジェクトが失われるのを防ぐことができます。

## 自動ページ分割

すべてのオブジェクトを取得するには、自動ページ分割機能を使用します。これにより、`has_more` が `false` になるまで複数の API コールが自動で実行されます。

#### Ruby

```ruby
customers = Stripe::Customer.list()

customers.auto_paging_each do |customer|
    # Do something with customer
end
```

> リストエンドポイントで自動ページ分割を使用した後、[ending_before](https://docs.stripe.com/api/pagination.md#pagination-ending_before) を設定すると、結果が時系列順になり、最後に作成された顧客が最後に表示されるようになります。

## 手動ページ分割

次の手順に従って、結果を手動でページ分割します。このプロセスは、リストエンドポイントまたは検索エンドポイントを呼び出す場合と異なります。

#### List

1. API コールを実行して、検索対象のオブジェクトを一覧表示します。

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:"
```

1. レスポンスで、[has_more](https://docs.stripe.com/api/pagination.md#pagination-has_more) の値を確認します。

- 値が `false` の場合は、すべてのオブジェクトが取得されています。
- 値が `true` の場合は、最後に返されたオブジェクトの ID を取得し、[starting_after](https://docs.stripe.com/api/pagination.md#pagination-starting_after) パラメーターを設定して新しい API コールを実行します。

検索対象のオブジェクトをすべて取得するまで、この手順を繰り返します。

```curl
curl -G https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d starting_after={{LAST_CUSTOMER_ID}}
```

#### 検索

1. API コールを実行して、検索対象のオブジェクトを一覧表示します。

```curl
curl -G https://api.stripe.com/v1/customers/search \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "query=metadata['foo']:'bar'"
```

1. レスポンスで、[has_more](https://docs.stripe.com/api/pagination/search.md#search_pagination-has_more) の値を確認します。

- 値が `false` の場合は、すべてのオブジェクトが取得されています。
- 値が `true` の場合は、レスポンスから `next_page` プロパティを取得し、[page](https://docs.stripe.com/api/pagination/search.md#search_pagination-page) パラメーターを設定して新しい API コールを実行します。

検索対象のオブジェクトをすべて取得するまで、この手順を繰り返します。

```curl
curl -G https://api.stripe.com/v1/customers/search \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "query=metadata['foo']:'bar'" \
  -d page={{NEXT_PAGE_ID}}
```