AWS Tools for PowerShell V4 已进入维护模式。
我们建议您迁移到 [AWS Tools for PowerShell V5](https://docs.aws.amazon.com/powershell/v5/userguide/)。有关如何迁移的更多详细信息和信息，请参阅我们的[维护模式公告](https://aws.amazon.com/blogs/developer/aws-tools-for-powershell-v4-maintenance-mode-announcement/)。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AWS Tools for PowerShell 中的管道、输出和迭代
## 管道
PowerShell 鼓励用户将 cmdlet 连接到[管道](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_pipelines)中，将一个 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](https://aws.amazon.com/blogs/developer/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](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_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](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_splatting) 以避免因内联声明参数和参数而导致代码行过长。