中的流水线、输出和迭代 Amazon Tools for PowerShell - Amazon Tools for PowerShell （第 4 版）
流水线Cmdlet 输出对分页数据进行迭代
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

中的流水线、输出和迭代 Amazon Tools for PowerShell

流水线

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

PS > Get-EC2Instance | Stop-EC2Instance

Cmdlet 输出

为了更好地支持流水线，默认情况下， 适用于 .NET 的 Amazon SDK 可能会丢弃来自响应的某些数据。 Amazon Tools for PowerShell cmdlet 的输出不会被重塑为将服务响应和结果实例作为发出的集合对象的Note属性包括在内。相反，对于那些将单个集合作为输出的调用，该集合现在被枚举到管道中。 PowerShell 这意味着 SDK 响应和结果数据不能存在于管道中，因为没有可以将其附加到的包含集合对象。

尽管大多数用户可能不需要这些数据，但它可用于诊断目的，因为您可以确切地看到 cmdlet 发出的底层 Amazon 服务调用发送和接收的内容。从 Amazon Tools for PowerShell V4 开始，cmdlet 可以使用-Select *参数和参数返回整个服务响应。

注意

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

注意

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

该$AWSHistory变量将在的 V5 中 Amazon Tools for PowerShell删除。有关更多信息，请参阅博客文章 T Amazon ools 5 即将推出的主要版本 5 的通知 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 的 Amazon SDK 响应对象。由于-Select *已指定，因此输出包含整个 API 响应，其中包含Buckets属性中的存储桶集合。在此示例中，Format-Listcmdlet 并不是严格必需的，而是为了确保显示所有属性而存在的。

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

对分页数据进行迭代

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

自动迭代

对于为给定调用规定默认最大返回对象数或支持可分页结果集的服务 APIs ，大多数 cmdlet 都实现自动迭代，从而启用 “” 的默认行为。page-to-completion在这种情况下，cmdlet 会代表您进行任意数量的调用，以将完整的数据集返回到管道。

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

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

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

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

在 Amazon Tools for PowerShell V4 中，一些用于分页操作的 cmdlet 不实现自动迭代。如果 cmdlet 没有-NoAutoIteration参数（将在下一节中讨论），则它不会实现自动迭代。

禁用自动迭代

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

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

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

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

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

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

下一个令牌响应属性的名称和 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 来避免因内联声明参数和参数而导致的长行代码。