AWS Tools for PowerShell 中的管道、输出和迭代 - AWS Tools for PowerShell （第 4 版）
管道Cmdlet 输出通过分页数据进行迭代

的版本 5 (V5) AWS Tools for PowerShell 已经发布！

要开始使用新版本的工具，请参阅《AWS Tools for PowerShell 用户指南（V5）》，特别是关于迁移到 V5 的主题。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

AWS Tools for PowerShell 中的管道、输出和迭代

管道

PowerShell 鼓励用户将 cmdlet 连接到管道中，将一个 cmdlet 的输出定向到下一个 cmdlet 的输入。以下示例展示了在使用 AWS Tools for PowerShell 时的这种行为。该命令获取并停止当前默认区域中的所有 Amazon EC2 实例。

PS > Get-EC2Instance | Stop-EC2Instance

Cmdlet 输出

为了更好地支持管道，适用于 .NET 的 AWS SDK 响应中的一些数据可能默认被丢弃。来自 AWS Tools for PowerShell cmdlet 的输出不会进行改造以包括服务响应和结果实例，与已发出集合对象上的 Note 属性不同。相反，对于发出单个集合作为输出的调用，现在将调用列举到 PowerShell 管道。这意味着开发工具包响应和结果数据不能存在于管道中，因为其中不包含可以将其附加到的集合对象。

虽然大部分用户可能不需要此数据，不过它对于诊断用途可能非常有用，因为您可以准确地查看 cmdlet 在基础 AWS 服务调用中发送和接收的内容。从 AWS Tools for PowerShell V4 开始，cmdlet 可以使用 -Select * 参数和参数来返回整个服务响应。

注意

在 AWS Tools for PowerShell V4 之前的版本中，引入了一个名为 $AWSHistory 的会话变量，该变量维护了 AWS cmdlet 调用以及每个调用接收到的服务响应的记录。在 Tools for PowerShell 的 V4 中，这个会话变量已被弃用，转而使用 -Select * 参数和参数，该参数可用于返回整个服务响应。此参数在本主题中描述。

注意

这是适用于预览版中特征的预发行文档。本文档随时可能更改。

$AWSHistory 变量将在 AWS Tools for PowerShell 的 V5 版本中被移除。有关更多信息，请参阅博客文章 Notice of upcoming major version 5 of AWS Tools for PowerShell。

为了说明如何返回响应中的所有数据，请考虑以下示例。

第一个示例简单地返回一个 Amazon S3 存储桶列表。这是默认行为。

PS > Get-S3Bucket

CreationDate           BucketName
------------           ----------
9/22/2023 10:54:35 PM  amzn-s3-demo-bucket1
9/22/2023 11:04:37 AM  amzn-s3-demo-bucket2
9/22/2023 12:54:34 PM  amzn-s3-demo-bucket3

第二个示例返回一个 适用于 .NET 的 AWS SDK 响应对象。因为指定了 -Select *，输出包括整个 API 响应，其中包含 Buckets 属性中的存储桶集合。在此示例中，Format-List cmdlet 并非严格必需，但存在以确保显示所有属性。

PS > Get-S3Bucket -Select * | Format-List

LoggedAt          : 10/1/2023 9:45:52 AM
Buckets           : {amzn-s3-demo-bucket1, amzn-s3-demo-bucket2,
                    amzn-s3-demo-bucket3}
Owner             : Amazon.S3.Model.Owner
ContinuationToken :
ResponseMetadata  : Amazon.Runtime.ResponseMetadata
ContentLength     : 0
HttpStatusCode    : OK

通过分页数据进行迭代

以下部分描述了可能的各种迭代类型。

自动迭代

对于施加默认最大返回对象数量的服务 API 或支持可分页结果集的服务 API，大多数 cmdlet 实现自动迭代，这使得默认行为“翻页至完成”成为可能。在此场景中，cmdlet 代表您进行尽可能多的调用，以将完整数据集返回到管道。

在以下使用 Get-S3Object cmdlet 的示例中，$result 变量包含名为 amzn-s3-demo-bucket1 的存储桶中每个键的 S3Object 实例，这可能是一个非常大的数据集。

PS > $result = Get-S3Object -BucketName amzn-s3-demo-bucket1

以下示例在自动迭代期间将每页的结果数量从默认值 1000 减少到 500。该示例执行两倍的自动迭代调用，因为每次调用返回的结果数量减半。

PS > $result = Get-S3Object -BucketName amzn-s3-demo-bucket1 -MaxKey 500
注意

在 AWS Tools for PowerShell V4 中，一些用于分页操作的 cmdlet 未实现自动迭代。如果一个 cmdlet 没有 -NoAutoIteration 参数（该参数在下一节讨论），那么它未实现自动迭代。

禁用自动迭代

如果您希望 Tools for PowerShell 仅返回第一页数据，您可以添加 -NoAutoIteration 参数以防止返回其他页的数据。

以下示例使用 -NoAutoIteration 和 -MaxKey 参数将返回的 S3Object 实例数量限制为在存储桶中找到的前 500 个。

PS > $result = Get-S3Object -BucketName amzn-s3-demo-bucket1 -MaxKey 500 -NoAutoIteration

要确定是否有更多可用数据但未返回，请使用 -Select * 参数和参数并检查 next token 属性中是否有值。

如果存储桶中的对象超过 500 个，以下示例返回 $true，否则返回 $false。

PS > $result = Get-S3Object -BucketName amzn-s3-demo-bucket1 -MaxKey 500 -NoAutoIteration -Select *
PS > $null -eq $result.NextMarker
注意

next token 响应属性的名称和 cmdlet 参数因 cmdlet 而异。有关详细信息，请参阅每个 cmdlet 的帮助文档。

手动迭代

以下示例使用 do 循环从存储桶返回所有 S3 对象，该循环在每次迭代后评估条件。do 循环执行迭代，直到 Get-S3Object 将 $result.NextMarker 设置为 $null，指示没有更多分页数据剩余。循环的输出被赋值给 $s3Objects 变量。

$s3Objects = do
{
    $splatParams = @{
        BucketName = 'amzn-s3-demo-bucket1'
        MaxKey = 500 
        Marker = $result.NextMarker 
        NoAutoIteration = $true
        Select = '*'
    }
    $result = Get-S3Object @splatParams
    
    $result.S3Objects
}
while ($null -ne $result.NextMarker)

此示例使用 PowerShell splatting 以避免因内联声明参数和参数而导致代码行过长。