# 在 AWS CLI 中使用分页选项
本主题介绍分页 AWS Command Line Interface（AWS CLI）的输出的不同方式。
主要有两种方法可以从 控制分页AWS CLI
+ [使用服务器端分页参数。](#cli-usage-pagination-serverside)
+ [使用默认输出客户端分页程序](#cli-usage-pagination-clientside)。
服务器端分页参数会先进行处理，然后系统会将所有输出发送到客户端分页程序进行处理。
## 服务器端分页
对于返回大型项目列表的大多数命令，AWS CLI 提供了多个服务器端选项，当 AWS CLI 调用服务 API 以填充此列表时，您可以使用这些选项控制输出中包括的项目数。AWS CLI 中的服务器端分页由 AWS 服务 API 启用，因此，这些选项只有在服务 API 启用它们时才生效。
**Topics**
+ [--no-paginate](#cli-usage-pagination-nopaginate)
+ [--page-size](#cli-usage-pagination-pagesize)
+ [--max-items](#cli-usage-pagination-maxitems)
+ [--starting-token](#cli-usage-pagination-startingtoken)
默认情况下，AWS CLI 使用由单个服务确定的页面大小并检索所有可用项目。例如，Amazon S3 的原定设置页面大小为 1000。如果您在包含 3500 个对象的 Amazon S3 存储桶上运行 `aws s3api list-objects`，则 AWS CLI 将自动对 Amazon S3 发出四次调用，以在后台处理服务特定分页逻辑并在最终输出中返回所有 3500 个对象。
有关特定命令是否具有服务器端分页的信息，请参阅[《AWS CLI 版本 2 参考指南》](https://docs.aws.amazon.com/cli/latest/reference/index.html)。
### 如何使用 --no-paginate 参数
`--no-paginate` 选项在客户端禁用以下分页标记。使用命令时，默认情况下 AWS CLI 会自动执行多次调用，返回所有可能的结果来创建分页。每页显示一次调用的结果。禁用分页时，AWS CLI 只执行一次调用，显示命令结果的第一页。
例如，如果您在包含 3500 个对象的 Amazon S3 存储桶上运行 `aws s3api list-objects`，则 AWS CLI 只会执行对 Amazon S3 的第一个调用，并在最终输出中仅返回前 1000 个对象。
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--no-paginate
{
"Contents": [
...
```
### 如何使用 --page-size 参数
如果您在对大量资源运行列表命令时发现问题，则表明原定设置页面大小可能过大。这可能会导致对 AWS 服务的调用超过允许的最大时间并生成“超时”错误。您可以使用 `--page-size` 选项来指定 AWS CLI 从对 AWS 服务的每个调用请求数量较少的项目。AWS CLI 仍将检索完整列表，但会在后台执行大量服务 API 调用，并减少每次调用时检索的项目数。这样，各个调用成功的可能性会更高且不会发生超时。更改页面大小不会影响输出；它只影响生成输出所需进行的 API 调用数。
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--page-size 100
{
"Contents": [
...
```
### 如何使用 --max-items 参数
要在 AWS CLI 输出中一次包括更少的项目，请使用 `--max-items` 选项。AWS CLI 仍会按之前所述使用该服务处理分页，但只打印您指定的一次检索的项目数。
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--max-items 100
{
"NextToken": "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==",
"Contents": [
...
```
### 如何使用 --starting-token 参数
如果项目输出的数量（`--max-items`）少于基础 API 调用所返回的项目总数，则输出将包含您可传递到后续命令的 `NextToken` 以检索下一组项目。以下示例显示如何使用上一示例返回的 `NextToken` 值，并使您能够检索接下来的 100 个项目。
**注意**
参数 `--starting-token` 不能为空。如果上一个命令未返回 `NextToken` 值，则没有更多项目可返回，您不需要再次调用该命令。
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--max-items 100 \
--starting-token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==
{
"Contents": [
...
```
每次调用指定的 AWS 服务时返回项目的顺序可能不同。如果您为 `--page-size` 和 `--max-items` 指定不同的值，您可能会获得意外结果（项目缺失或重复）。为防止出现这种情况，请对 `--page-size` 和 `--max-items` 使用相同的数字，以同步 AWS CLI 的分页与基础服务的分页。您还可以检索整个列表并在本地执行任何必需的分页操作。
## 客户端分页程序
AWS CLI 版本 2 支持使用客户端分页程序对输出进行处理。默认情况下，此功能会通过操作系统的默认分页程序返回所有输出。
您可以按照优先级顺序，通过以下方式指定输出分页程序：
+ 使用 `default` 或所指定配置文件的 `config` 文件中的 `cli_pager` 设置。
+ 使用 `AWS_PAGER` 环境变量。
+ 使用 `PAGER` 环境变量。
您可以按照优先级顺序，通过以下方式完全禁止对外部分页程序的使用：
+ 使用 `--no-cli-pager` 命令行选项可禁止在单个命令中使用分页程序。
+ 将 `cli_pager` 设置或 `AWS_PAGER` 变量设置为空字符串。
**Topics**
+ [cli\$1pager](#cli-usage-pagination-clipager)
+ [AWS\$1PAGER](#cli-usage-pagination-awspager)
+ [--no-cli-pager](#cli-usage-pagination-noclipager)
+ [分页标志](#cli-usage-pagination-flags)
### 如何使用 cli\$1pager 设置
您可以将常用的配置设置和凭证保存在由 AWS CLI 维护的文件中。所指定配置文件中的设置优先于 `default` 配置文件中的设置。有关配置设置的更多信息，请参阅[AWS CLI 中的配置和凭证文件设置](cli-configure-files.md)。
以下示例将默认输出分页程序设置为 `less` 程序。
```
[default]
cli_pager=less
```
以下示例将默认值设置为禁用分页程序。
```
[default]
cli_pager=
```
### 如何设置 AWS\$1PAGER 环境变量
以下示例将默认输出分页程序设置为 `less` 程序。有关环境变量的更多信息，请参阅[为 AWS CLI 配置环境变量](cli-configure-envvars.md)。
------
#### [ Linux and macOS ]
```
$ export AWS_PAGER="less"
```
------
#### [ Windows ]
```
C:\> setx AWS_PAGER "less"
```
------
### 如何使用 --no-cli-pager 选项
要对单个命令禁止使用分页程序，请使用 `--no-cli-pager` 选项。有关命令行选项的更多信息，请参阅[AWS CLI 中的命令行选项](cli-configure-options.md)。
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--no-cli-pager
{
"Contents": [
...
```
### 如何使用分页程序标志
您可以指定要对分页程序自动使用的标志。标志取决于您使用的分页程序。以下示例适用于 `less` 和 `more` 的典型默认值。
------
#### [ Linux and macOS ]
如果不另行指定，则 AWS CLI 版本 2 在预设情况下使用的分页程序为 `less`。如果您没有设置 `LESS` 环境变量，则 AWS CLI 版本 2 使用 `FRX` 标志。您可以通过在设置 AWS CLI 分页程序时指定标志，来结合使用各个标志。
以下示例使用 `S` 标志。然后，此标志与默认 `FRX` 标志结合使用，创建最终 `FRXS` 标志。
```
$ export AWS_PAGER="less -S"
```
如果您不希望使用任何 `FRX` 标志，您可以对它们取否定值。以下示例对 `F` 标志取否定值，创建最终 `RX` 标志。
```
$ export AWS_PAGER="less -+F"
```
有关 `less` 标志的更多信息，请参阅 *manpages.org* 上的 [less](http://manpages.org/less/1#options)。
------
#### [ Windows ]
如果不另行指定，则 AWS CLI 版本 2 默认使用的分页程序为不带附加标志的 `more`。
以下示例使用 `/c` 参数。
```
C:\> setx AWS_PAGER "more /c"
```
有关 `more` 标志的更多信息，请参阅《Microsoft 文档》**中的 `[more](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/more)`。
------