本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
管道传输和 $AWSHistory
对于返回集合的 Amazon 服务调用,集合中的对象列举到管道。对于生成的对象,当其中包含集合之外附加字段以及不分页控制字段时,将这些字段作为调用的 Note 属性添加。这些 Note 属性记录在新的 $AWSHistory
会话变量中,您需要访问此数据。$AWSHistory
变量在下一节中介绍。
注意
在 Tools for 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
为了更好地支持管道传输,来自 Amazon cmdlet 的输出不会进行改造以包括服务响应和结果实例,与已发出集合对象上的 Note 属性不同。相反,对于发出单个集合作为输出的调用,现在将调用列举到 PowerShell 管道。这意味着Amazon开发工具包响应和结果数据不能存在于管道中,因为其中不包含可以将其附加到的集合对象。
虽然大部分用户可能不需要此数据,不过它对于诊断用途可能非常有用,因为您可以准确地查看 cmdlet 在基础Amazon服务调用中发送和接收的内容。
从版本 1.1 开始,现在此数据以及更多数据在名为 $AWSHistory
的新 shell 变量中提供。此变量维护 Amazon cmdlet 调用的记录以及为每次调用接收的服务响应。(可选)可以配置此历史记录以便同时记录每次 cmdlet 发出的服务请求。其他有用数据,例如 cmdlet 的整体执行时间也可以从各个条目中获取。出于安全原因,原定设置情况下不记录包含敏感数据的请求和响应。但是,如果需要,可以将历史记录配置为覆盖此行为。有关更多信息,请参阅下面所示的 Set-AWSHistoryConfiguration
cmdlet。
$AWSHistory.Commands
列表中的每个条目的类型为 AWSCmdletHistory
。此类型具有以下有用成员:
- CmdletName
-
cmdlet 的名称。
- CmdletStart
-
运行 cmdlet 的日期时间。
- CmdletEnd
-
cmdlet 完成所有处理的日期时间。
- 请求
-
如果启用了请求记录,则为上个服务请求的列表。
- 响应
-
收到的上个服务响应的列表。
- LastServiceResponse
-
返回最近服务响应的帮助程序。
- LastServiceRequest
-
返回最近服务请求(如果可用)的帮助程序。
请注意,在使用发出服务调用的 Amazon cmdlet 之前,不创建 $AWSHistory
变量。在该时间之前,它的计算结果为 $null。
注意
Tools for Windows PowerShell 的早期版本发出与服务响应相关的数据,以作为返回的对象的 Note
属性。这些内容现在可在为列表中每次调用记录的响应条目中找到。
Set-AWSHistoryConfiguration
一个 cmdlet 调用可以容纳零个或多个服务请求和响应条目。为了减少对内存的影响,默认情况下 $AWSHistory
列表仅保留最后五次 cmdlet 执行的记录,对于每次执行,保留最后五个服务响应(如果启用,包括最后五个服务请求)。您可以通过运行 Set-AWSHistoryConfiguration
cmdlet 来更改这些默认限制。它允许您控制列表的大小以及是否同时记录服务请求:
PS >
Set-AWSHistoryConfiguration -MaxCmdletHistory <value> -MaxServiceCallHistory <value> -RecordServiceRequests -IncludeSensitiveData
所有参数都是可选的。
MaxCmdletHistory
参数设置可以随时跟踪的 cmdlet 最大数量。值为 0 将禁止记录 Amazon cmdlet 活动。MaxServiceCallHistory
参数设置为每个 cmdlet 跟踪的服务响应(和/或请求)的最大数量。如果指定 RecordServiceRequests
参数,则为每个 cmdlet 启用服务请求跟踪。如果指定了 IncludeSensitiveData
参数,则对于包含每个 cmdlet 的敏感数据的服务响应和请求(如果已跟踪)启用跟踪。
如果未带参数运行,则单纯运行 Set-AWSHistoryConfiguration
将停用所有之前的请求记录,并保持当前列表大小不变。
要清除当前历史记录列表中的所有条目,请运行 Clear-AWSHistory
cmdlet。
$AWSHistory
示例
将保存在列表中的 Amazon cmdlet 的详细信息列举到管道。
$AWSHistory.Commands
PS >
访问上次运行的 Amazon cmdlet 的详细信息:
PS >
$AWSHistory.LastCommand
访问上次运行的 Amazon cmdlet 最后接收的服务响应的详细信息。如果 Amazon cmdlet 分页输出,则可以进行多次服务调用来获取所有数据或最大数量的数据(由 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 的 MaxKey
和 Marker
参数与最后记录的响应的 IsTruncated
/NextMarker
备注结合使用。在以下示例中,变量 $c
包含在存储桶中的指定键前缀标记之后,找到的接下来 500 个对象的最多 500 个 S3Object
实例。
PS >
$c = Get-S3Object -BucketName test -MaxKey 500 -Marker $AWSHistory.LastServiceResponse.NextMarker