使用 AWS CLI 分页选项 - AWS 命令行界面
服务器端分页客户端分页程序
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 AWS 服务入门。

AWS CLI 版本 1 将弃用 Python 2.7、3.4 和 3.5。有关更多信息，请参阅关于 AWS CLI 版本的 AWS CLI 版本 1 部分。

使用 AWS CLI 分页选项

本主题介绍分页 AWS 命令行界面 (AWS CLI) 的输出的不同方式。主要有两种方法可以从 AWS CLI 控制分页。

服务器端分页参数会先进行处理，然后系统会将所有输出发送到客户端分页程序进行处理。

服务器端分页

对于可返回项目大型列表的命令，AWS 命令行界面 (AWS CLI) 提供了多个选项。当 AWS CLI 调用服务 API 以填充此列表时，您可以使用这些选项控制输出中包括的项目数。

  • --no-paginate

  • --page-size

  • --max-items

  • --starting-token

默认情况下，AWS CLI 使用页面大小 1000 并检索所有可用项目。如果您在包含 3500 个对象的 Amazon S3 存储桶上运行 aws s3api list-objects，则 AWS CLI 将自动对 Amazon S3 发出四次调用，以在后台处理服务特定分页逻辑并在最终输出中返回所有 3500 个对象。

如何使用 --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 my-bucket \
    --no-paginate
{
    "Contents": [
...

如何使用 --page-size 参数

如果您在对大量资源运行列表命令时发现问题，则表明默认页面大小 1000 可能过高。这可能会导致对 AWS 服务的调用超过允许的最大时间并生成“超时”错误。您可以使用 --page-size 选项来指定 AWS CLI 从对 AWS 服务的每个调用请求数量较少的项目。CLI 仍将检索完整列表，但会在后台执行大量服务 API 调用，并减少每次调用时检索的项目数。这样，各个调用成功的可能性会更高且不会发生超时。更改页面大小不会影响输出；它只影响生成输出所需进行的 API 调用数。 

$ aws s3api list-objects \
    --bucket my-bucket \
    --page-size 100
{
    "Contents": [
...

如何使用 --max-items 参数

要在 AWS CLI 输出中一次包括更少的项目，请使用 --max-items 选项。AWS CLI 仍会按之前所述使用该服务处理分页，但只打印您指定的一次检索的项目数。 

$ aws s3api list-objects \
    --bucket my-bucket \
    --max-items 100
{
    "NextToken": "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==",
    "Contents": [
...

如何使用 --starting-token 参数

如果项目输出的数量 (--max-items) 少于基础 API 调用所返回的项目总数，则输出将包含您可传递到后续命令的 NextToken 以检索下一组项目。以下示例显示如何使用上一示例返回的 NextToken 值，并使您能够检索接下来的 100 个项目。

注意

参数 --starting-token 不能为空。如果上一个命令未返回 NextToken 值，则没有更多项目可返回，您不需要再次调用该命令。 

$ aws s3api list-objects \
    --bucket my-bucket \
    --max-items 100 \
    --starting-token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==
{
    "Contents": [
...

每次调用指定的 AWS 服务时返回项目的顺序可能不同。如果您为 --page-size 和 --max-items 指定不同的值，您可能会获得意外结果（项目缺失或重复）。为防止出现这种情况，请对 --page-size 和 --max-items 使用相同的数字，以同步 AWS CLI 的分页与基础服务的分页。您还可以检索整个列表并在本地执行任何必需的分页操作。

客户端分页程序

此功能只在 AWS CLI 版本 2 中提供。

仅当您使用 AWS CLI 版本 2 时，以下功能才可用。如果您运行 AWS CLI 版本 1，则此功能不可用。有关如何安装版本 2 的信息，请参阅安装、更新和卸载 AWS CLI 版本 2。

AWS CLI 版本 2 支持使用客户端分页程序对输出进行处理。默认情况下，此功能会通过操作系统的默认分页程序返回所有输出。

您可以按照优先级顺序，通过以下方式指定输出分页程序：

  • 使用所指定配置文件的 config 文件中的 cli_pager 设置。

  • 使用 AWS_PAGER 环境变量。

  • 使用 default 配置文件的 config 文件中的 cli_pager 设置。

  • 使用 PAGER 环境变量。

您可以按照优先级顺序，通过以下方式完全禁止对外部分页程序的使用：

  • 使用 --no-cli-pager 命令行选项可禁止在单个命令中使用分页程序。

  • 将 cli_pager 设置或 AWS_PAGER 变量设置为空字符串。

如何使用 cli_pager 设置

您可以将常用的配置设置和凭证保存在由 AWS CLI 维护的文件中。所指定配置文件中的设置优先于 default 配置文件中的设置。有关配置设置的更多信息，请参阅 配置和凭证文件设置。

以下示例将默认输出分页程序设置为 less 程序。 

[default]
cli_pager=less

以下示例将默认值设置为禁用分页程序。

[default]
cli_pager=

如何使用 AWS_PAGER 环境变量

以下示例将默认输出分页程序设置为 less 程序。有关环境变量的更多信息，请参阅 用于配置 AWS CLI 的环境变量。

Linux and macOS
$ export AWS_PAGER="less"
Windows
C:\> setx AWS_PAGER "less"

以下示例禁用分页程序。

Linux and macOS
$ export AWS_PAGER=""
Windows
C:\> setx AWS_PAGER ""

如何使用 --no-cli-pager 选项

要对单个命令禁止使用分页程序，请使用 --no-cli-pager 选项。有关命令行选项的更多信息，请参阅 命令行选项。 

$ aws s3api list-objects \
    --bucket my-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。

Windows

如果不另行指定，则 AWS CLI 版本 2 默认使用的分页程序为不带附加标志的 more。

以下示例使用 /c 参数。 

C:\> setx AWS_PAGER "more /c"

有关 more 标志的更多信息，请参阅 Microsoft 文档 上的 more。