使用 Amazon CLI 分页选项
本主题介绍分页 Amazon Command Line Interface (Amazon CLI) 的输出的不同方式。
主要有两种方法可以从 Amazon CLI 控制分页。
服务器端分页参数会先进行处理,然后系统会将所有输出发送到客户端分页程序进行处理。
服务器端分页
对于可返回项目大型列表的命令,Amazon Command Line Interface (Amazon CLI) 提供了多个选项。当 Amazon CLI 调用服务 API 以填充此列表时,您可以使用这些选项控制输出中包括的项目数。
-
--no-paginate
-
--page-size
-
--max-items
-
--starting-token
默认情况下,Amazon CLI 使用由单个服务确定的页面大小并检索所有可用项目。例如,Amazon S3 的原定设置页面大小为 1000。如果您在包含 3500 个对象的 Amazon S3 存储桶上运行 aws
s3api list-objects
,则 Amazon CLI 将自动对 Amazon S3 发出四次调用,以在后台处理服务特定分页逻辑并在最终输出中返回所有 3500 个对象。
如何使用 --no-paginate 参数
--no-paginate
选项在客户端禁用以下分页标记。使用命令时,默认情况下 Amazon CLI 会自动执行多次调用,返回所有可能的结果来创建分页。每页显示一次调用的结果。禁用分页时,Amazon CLI 只执行一次调用,显示命令结果的第一页。
例如,如果您在包含 3500 个对象的 Amazon S3 存储桶上运行 aws s3api list-objects
,则 Amazon CLI 只会执行对 Amazon S3 的第一个调用,并在最终输出中仅返回前 1000 个对象。
$
aws s3api list-objects \ --bucket my-bucket \
--no-paginate
{ "Contents": [ ...
如何使用 --page-size 参数
如果您在对大量资源运行列表命令时发现问题,则表明原定设置页面大小可能过大。这可能会导致对 Amazon 服务的调用超过允许的最大时间并生成“超时”错误。您可以使用 --page-size
选项来指定 Amazon CLI 从对 Amazon 服务的每个调用请求数量较少的项目。Amazon CLI 仍将检索完整列表,但会在后台执行大量服务 API 调用,并减少每次调用时检索的项目数。这样,各个调用成功的可能性会更高且不会发生超时。更改页面大小不会影响输出;它只影响生成输出所需进行的 API 调用数。
$
aws s3api list-objects \ --bucket my-bucket \
--page-size 100
{ "Contents": [ ...
如何使用 --max-items 参数
要在 Amazon CLI 输出中一次包括更少的项目,请使用 --max-items
选项。Amazon 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": [ ...
每次调用指定的 Amazon 服务时返回项目的顺序可能不同。如果您为 --page-size
和 --max-items
指定不同的值,您可能会获得意外结果(项目缺失或重复)。为防止出现这种情况,请对 --page-size
和 --max-items
使用相同的数字,以同步 Amazon CLI 的分页与基础服务的分页。您还可以检索整个列表并在本地执行任何必需的分页操作。
客户端分页程序
Amazon CLI 版本 2 支持使用客户端分页程序对输出进行处理。默认情况下,此功能会通过操作系统的默认分页程序返回所有输出。
您可以按照优先级顺序,通过以下方式指定输出分页程序:
-
使用
default
或所指定配置文件的config
文件中的cli_pager
设置。 -
使用
AWS_PAGER
环境变量。 -
使用
PAGER
环境变量。
您可以按照优先级顺序,通过以下方式完全禁止对外部分页程序的使用:
-
使用
--no-cli-pager
命令行选项可禁止在单个命令中使用分页程序。 -
将
cli_pager
设置或AWS_PAGER
变量设置为空字符串。
如何使用 cli_pager 设置
您可以将常用的配置设置和凭证保存在由 Amazon CLI 维护的文件中。所指定配置文件中的设置优先于 default
配置文件中的设置。有关配置设置的更多信息,请参阅配置和凭证文件设置。
以下示例将默认输出分页程序设置为 less
程序。
[default] cli_pager=less
以下示例将默认值设置为禁用分页程序。
[default] cli_pager=
如何使用 AWS_PAGER 环境变量
以下示例将默认输出分页程序设置为 less
程序。有关环境变量的更多信息,请参阅用于配置 Amazon CLI 的环境变量。
以下示例禁用分页程序。
如何使用 --no-cli-pager 选项
要对单个命令禁止使用分页程序,请使用 --no-cli-pager
选项。有关命令行选项的更多信息,请参阅命令行选项。
$
aws s3api list-objects \ --bucket my-bucket \
--no-cli-pager
{ "Contents": [ ...
如何使用分页程序标志
您可以指定要对分页程序自动使用的标志。标志取决于您使用的分页程序。以下示例适用于 less
和 more
的典型默认值。