# ページの選択

アクションが処理対象とするページを指定する方法と、pages、page_order、groups の各フィールドが共有する範囲の構文について説明します。

多くのアクションは、ドキュメントのページの一部に対して処理を行います。この対象範囲は、`1..3,5` のように、1から始まるページ番号と範囲をカンマ区切りで並べたコンパクトな構文で指定します。同じ数値と範囲の表記はすべてのアクションに共通して現れますが、その意味は**集合**または**順序付きリスト**のいずれかとして解釈されます。このページは両方の唯一のリファレンスであり、ページフィールドを持つすべてのアクションからここにリンクされています。

## 2つの選択方法

- **集合**フィールド（`pages`）は、*どの*ページかを表します。順序と重複は無視され、選択されたページは常にドキュメントの順序で処理されます。
- **順序付き**フィールド（`page_order`、および `groups` 内の各グループ）は、*どの順序で*かを表します。順序と繰り返しには意味があり、ページは記述されたとおりに出力されます。

範囲を表す構文はどちらも同じです。違いは、結果がどのように解釈されるかだけです。

## 集合による選択：`pages` フィールド

`pages` フィールドは、1から始まるページ番号と範囲をカンマ区切りで並べたリストです。

- 単一のページ。例: `5`。
- 範囲。例: `2..6`（ページ2から6まで）。
- 終端のない範囲: `8..` はページ8から最後のページまで、`..5` は最初のページからページ5までを表します。
- 負のインデックスは末尾から数えます。`-1` は最後のページ、`-2` は最後から2番目のページです。範囲にも使用でき、`-3..-1` は最後の3ページを表します。

`pages` フィールドは**集合**として扱われます。順序と重複は無視され、ページは常にドキュメントの順序で処理されます。空のままにすると、すべてのページが選択されます。

| パターン | 選択されるページ |
| --- | --- |
| *(省略)* | すべてのページ |
| `1` | 最初のページのみ |
| `2..6` | ページ2から6まで |
| `1..3,5` | ページ1、2、3、5 |
| `8..` | ページ8から最後のページまで |
| `..5` | 最初のページからページ5まで |
| `..-2` | 最初のページから最後から2番目のページまで |
| `-1` | 最後のページ |
| `-3..-1` | 最後の3ページ |

集合は順序を持たないため、`5,1,2..3` と `1,2,3,5` はまったく同じページを選択し、どちらもドキュメントの順序で適用されます。一部のアクションには独自のルールが追加されます。たとえば[ページを削除する](/docs/api/remove-pages-from-pdf)では、少なくとも1ページを残す必要があるため、すべてのページを削除するような選択は拒否されます。

## 順序付き選択：`page_order` と `groups`

一部の入力は、集合ではなく**順序付き**リストです。上記と同じ数値と範囲を使用しますが、ここでは順序と重複が意味を持ちます。ページは記載されたとおりに出力され、2回指定されたページは2回出力され、記載されなかったページは除外されます。範囲は逆方向にもでき、`10..5` はページ10からページ5まで下る指定になります。

- [`page_order`](/docs/api/reorder-pages-of-pdf)（並べ替えで使用）は、単一の順序付きリストです。`3,1,2` はページ3を最初に、続けて1、2の順に配置します。省略されたページは除外され、繰り返しは保持されるため、並べ替えは抽出・複製・並べ替えを兼ねた処理になります。
- [`groups`](/docs/api/split-pdf-into-page-groups)（ページグループへの分割で使用）は、`;` で区切られた複数の順序付きリストです。各グループは1つの出力 PDF になり、グループ内では順序付きのルールが適用されます。`2..8,29;1` は2つのドキュメントを生成します。1つ目はページ2から8、続けて29、2つ目はページ1です。

## 各アクションが使用するフィールド

| フィールド | 意味 | アクション |
| --- | --- | --- |
| `pages` | 集合 | [テキスト透かしを追加](/docs/api/add-text-watermark-to-pdf)、[画像透かしを追加](/docs/api/add-image-watermark-to-pdf)、[ページを抽出](/docs/api/extract-pages-from-pdf)、[ページを削除](/docs/api/remove-pages-from-pdf)、[ページを回転](/docs/api/rotate-pages-in-pdf) |
| `page_order` | 順序付き | [ページを並べ替え](/docs/api/reorder-pages-of-pdf) |
| `groups` | 順序付き（グループごと） | [ページグループに分割](/docs/api/split-pdf-into-page-groups) |

<Tip>
  書く順序にかかわらず結果が同じになる場合は、集合フィールドを使用します。たとえば、ページ2、4、6に透かしを付与する場合です。順序そのものが結果となる場合は、順序付きフィールドを使用します。たとえば、ページを並べ替えたり繰り返したりする場合です。
</Tip>

## 共通のルール

- ページ番号は**1から始まります**。ページ `0` は存在しません。
- 負のインデックスと終端のない範囲は、集合フィールドと順序付きフィールドの両方で使用できます。
- 10ページのファイルにおける `12` のように、ドキュメントの範囲を超えるページを指定した選択は、`400` で拒否されます。詳細は[エラー](/docs/api/errors)を参照してください。