管道传输和 $AWSHistory - Amazon Tools for PowerShell
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

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

管道传输和 $AWSHistory

对于返回集合的 Amazon 服务调用,集合中的对象列举到管道。对于生成的对象,当其中包含集合之外附加字段以及不分页控制字段时,将这些字段作为调用的 Note 属性添加。这些 Note 属性记录在新的 $AWSHistory 会话变量中,您需要访问此数据。$AWSHistory 变量在下一节中介绍。

注意

在 Windows PowerShell 工具 1.1 版本之前的版本中,会发出集合对象本身,这需要使用 foreach {$_.getenumerator ()} 来继续管道传输。

示例

以下示例返回一组Amazon每个区域中的区域和 Amazon EC2 系统映像 (AMI)。

PS > Get-AWSRegion | % { Echo $_.Name; Get-EC2Image -Owner self -Region $_ }

以下示例停止当前默认区域中的所有 Amazon EC2 实例。

PS > Get-EC2Instance | Stop-EC2Instance

由于集合列举到管道,来自指定 cmdlet 的输出可能是 $null、单个对象或集合。如果是集合,则可以使用 .Count 属性来确定集合的大小。但是,在只发出单个对象时,.Count 属性不存在。如果您的脚本需要以一致的方式来确定发出了多少个对象,则可以检查 $AWSHistory 中最后一个命令值的 EmittedObjectsCount 属性。

$AWSHistory

为了更好地支持流水线,从Amazoncmdlet 不进行改造以包括服务响应和结果实例,与已发出集合对象上的 Note 属性不同。相反,对于发出单个集合作为输出的调用,现在将调用列举到 PowerShell 管道。这意味着AmazonSDK 响应和结果数据不能存在于管道中,因为其中不包含可以将其附加到的集合对象。

虽然大部分用户可能不需要此数据,但它对于诊断用途可能非常有用,因为您可以准确地查看基础Amazon由 cmdlet 进行的服务调用。

从版本 1.1 开始,现在此数据以及更多数据在名为 $AWSHistory 的新 shell 变量中提供。此变量维护Amazoncmdlet 调用以及为每次调用接收的服务响应。(可选)可以配置此历史记录以便同时记录每次 cmdlet 发出的服务请求。其他有用数据,例如 cmdlet 的整体执行时间也可以从各个条目中获取。

$AWSHistory.Commands 列表中的每个条目的类型为 AWSCmdletHistory。此类型具有以下有用成员:

CmdletName

cmdlet 的名称。

CmdletStart

运行 cmdlet 的日期时间。

CmdletEnd

cmdlet 完成所有处理的日期时间。

请求

如果启用了请求记录,则为上个服务请求的列表。

响应

收到的上个服务响应的列表。

LastServiceResponse

返回最近服务响应的帮助程序。

LastServiceRequest

返回最近服务请求(如果可用)的帮助程序。

请注意,$AWSHistory变量不会创建,直到Amazoncmdlet 进行服务调用。在该时间之前,它的计算结果为 $null。

注意

Windows PowerShell 工具的早期版本发出与服务响应相关的数据,Note属性。这些内容现在可在为列表中每次调用记录的响应条目中找到。

Set-AWSHistoryConfiguration

一个 cmdlet 调用可以容纳零个或多个服务请求和响应条目。为了减少对内存的影响,默认情况下 $AWSHistory 列表仅保留最后五次 cmdlet 执行的记录,对于每次执行,保留最后五个服务响应(如果启用,包括最后五个服务请求)。您可以通过运行 Set-AWSHistoryConfiguration cmdlet 来更改这些默认限制。它允许您控制列表的大小以及是否同时记录服务请求:

PS > Set-AWSHistoryConfiguration -MaxCmdletHistory <value> -MaxServiceCallHistory <value> -RecordServiceRequests

-MaxCmdletHistory 参数设置可以随时跟踪的 cmdlet 最大数量。值为 0 将禁止记录Amazoncmdlet 活动。-MaxServiceCallHistory 参数设置为每个 cmdlet 跟踪的服务响应(和/或请求)的最大数量。如果指定 -RecordServiceRequests 参数,则为每个 cmdlet 启用服务请求跟踪。所有参数都是可选的。

如果未带参数运行,则单纯运行 Set-AWSHistoryConfiguration 将停用所有之前的请求记录,并保持当前列表大小不变。

要清除当前历史记录列表中的所有条目,请运行 Clear-AWSHistory cmdlet。

$AWSHistory 示例

枚举Amazoncmdlet,保存在列表中。

PS > $AWSHistory.Commands

访问最后的详细信息Amazon已运行的命令:

PS > $AWSHistory.LastCommand

访问上次接收的服务响应的详细信息,Amazon已运行的命令。如果Amazoncmdlet 分页输出,则可以进行多次服务调用来获取所有数据或最大数量的数据(由 cmdlet 上的参数确定)。

PS > $AWSHistory.LastServiceResponse

访问最近发出的请求的详细信息 (再次强调,如果代表用户进行分页,则 cmdlet 可能发出多个请求)。除非启用了服务请求跟踪,否则将生成 $null。

PS > $AWSHistory.LastServiceRequest

对于返回多页的操作,自动从分页到完成

如果服务 API 对指定调用施加默认最大对象返回计数或支持可分页结果集,则所有 cmdlet 默认情况下“分页到完成”。根据需要,每个 cmdlet 代表您尽可能多地发出调用,以将完整的数据集返回到管道。

以下示例使用 Get-S3Object$c 变量包含 test 存储桶中的每个 键的 S3Object 实例,这可能会生成非常大的数据集。

PS > $c = Get-S3Object -BucketName test

如果您希望保持对返回数据量的控制,可以在单独的 cmdlet 上使用参数(例如,MaxKey 上的 Get-S3Object),或者自己明确地处理分页,将 cmdlet 上的分页参数与放在 $AWSHistory 变量中的数据结合使用来获取服务的下一个令牌数据。以下示例使用 MaxKeys 参数将返回的 S3Object 实例数量限制为不超过在存储桶中找到的前 500 个。

PS > $c = Get-S3Object -BucketName test -MaxKey 500

要了解是否有更多数据可用但未返回,请使用记录 cmdlet 所发出的服务调用的 $AWSHistory 会话变量条目。

如果以下表达式计算结果为 $true,则可以使用 $AWSHistory.LastServiceResponse.NextMarker 查找下一组结果的 next 标记:

$AWSHistory.LastServiceResponse -ne $null && $AWSHistory.LastServiceResponse.IsTruncated

要使用 Get-S3Object 手动控制分页,请将 cmdlet 的 MaxKeyMarker 参数与最后记录的响应的 IsTruncated/NextMarker 备注结合使用。在以下示例中,变量 $c 包含在存储桶中的指定键前缀标记之后,找到的接下来 500 个对象的最多 500 个 S3Object 实例。

PS > $c = Get-S3Object -BucketName test -MaxKey 500 -Marker $AWSHistory.LastServiceResponse.NextMarker