本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
从Amazon Tools for PowerShell版本 3.3 迁移到版本 4
Amazon Tools for PowerShell版本 4 是对Amazon Tools for PowerShell版本 3.3 的向后兼容更新。它在维护现有 cmdlet 行为的同时添加了大量的改进功能。
升级到新版本后,您的现有脚本应继续正常工作,但我们建议您在升级生产环境之前实施全面测试。
本节介绍了相关更改,并说明了这些更改可能会对脚本造成的影响。
全新的完全模块化 AWS.Tools
版本
的 AWSPowerShell。 NetCore 而且 AWSPowerShell 包裹是 “整体的”。这意味着所有 Amazon 服务都在同一个模块中得到支持,这使得该模块非常庞大,并随着添加各个新的 Amazon 服务和功能变得越来越大。新 AWS.Tools
软件包被拆分成较小的模块,使您可以灵活地仅下载和安装所使用的 Amazon 服务需要的模块。该软件包包括所有其他模块所需的共享 AWS.Tools.Common
模块,以及可简化安装、更新和删除(如有必要)模块过程的 AWS.Tools.Installer
模块。
这还会在首次调用时启用自动导入 cmdlet,而无需先调用 Import-module
。但是,要在调用 cmdlet 之前与关联的.NET 对象进行交互,您仍必须致电Import-Module
以 PowerShell 了解相关的.NET 类型。
例如,以下命令具有对 Amazon.EC2.Model.Filter
的引用。这种类型的引用无法触发自动导入,因此您必须先调用 Import-Module
,否则命令将失败。
PS >
$filter = [Amazon.EC2.Model.Filter]@{Name="vpc-id";Values="vpc-1234abcd"}
InvalidOperation: Unable to find type [Amazon.EC2.Model.Filter].
PS >
Import-Module AWS.Tools.EC2
PS >
$filter = [Amazon.EC2.Model.Filter]@{Name="vpc-id";Values="vpc-1234abcd"}
PS >
Get-EC2Instance -Filter $filter -Select Reservations.Instances.InstanceId
i-0123456789abcdefg i-0123456789hijklmn
新 Get-AWSService
cmdlet
为了帮助您发现 AWS.Tools
模块集合中各个 Amazon 服务的模块名称,您可以使用 Get-AWSService
cmdlet。
PS >
Get-AWSService
Service : ACMPCA CmdletNounPrefix : PCA ModuleName : AWS.Tools.ACMPCA SDKAssemblyVersion : 3.3.101.56 ServiceName : Certificate Manager Private Certificate Authority Service : AlexaForBusiness CmdletNounPrefix : ALXB ModuleName : AWS.Tools.AlexaForBusiness SDKAssemblyVersion : 3.3.106.26 ServiceName : Alexa For Business ...
用于控制 Cmdlet 返回的对象的新 -Select
参数
版本 4 中的大多数 cmdlet 支持新 -Select
参数。每个 cmdlet 使用 Amazon SDK for .NET 为您调用 Amazon 服务 API。然后,Amazon Tools for PowerShell客户端将响应转换为可以在 PowerShell 脚本中使用的对象,并通过管道传输到其他命令。有时,最终 PowerShell 对象在原始响应中包含的字段或属性比您需要的要多,而其他时候,您可能希望该对象包含默认情况下不存在的响应字段或属性。通过 -Select
参数,您可以指定 cmdlet 返回的 .NET 对象中包含的内容。
例如,Get-S3Object cmdlet 调用 Amazon S3 软件开发工具包操作。ListObjects该操作返回一个ListObjectsResponse对象。但是,默认情况下,Get-S3Object
cmdlet 仅向用户返回 SDK 响应S3Objects
中的元素。 PowerShell 在下面的示例中,该对象是包含两个元素的数组。
PS >
Get-S3Object -BucketName
mybucket
ETag : "01234567890123456789012345678901111" BucketName : mybucket Key : file1.txt LastModified : 9/30/2019 1:31:40 PM Owner : Amazon.S3.Model.Owner Size : 568 StorageClass : STANDARD ETag : "01234567890123456789012345678902222" BucketName : mybucket Key : file2.txt LastModified : 7/15/2019 9:36:54 AM Owner : Amazon.S3.Model.Owner Size : 392 StorageClass : STANDARD
在Amazon Tools for PowerShell版本 4 中,您可以指定 -Select *
返回由软件开发工具包 API 调用返回的完整 .NET 响应对象。
PS >
Get-S3Object -BucketName
mybucket
-Select *IsTruncated : False NextMarker : S3Objects : {file1.txt, file2.txt} Name : mybucket Prefix : MaxKeys : 1000 CommonPrefixes : {} Delimiter :
您还可以指定所需特定嵌套属性的路径。以下示例仅返回 S3Objects
数组中每个元素的 Key
属性。
PS >
Get-S3Object -BucketName
mybucket
-Select S3Objects.Keyfile1.txt file2.txt
在某些情况下,返回 cmdlet 参数可能非常有用。您可通过 -Select ^ParameterName
实现此目的。此功能取代 -PassThru
参数,该参数仍然可用,但已弃用。
PS >
Get-S3Object -BucketName mybucket -Select S3Objects.Key |
>>
Write-S3ObjectTagSet -Select ^Key -BucketName mybucket -Tagging_TagSet @{ Key='key'; Value='value'}
file1.txt file2.txt
每个 cmdlet 的参考主题确定它是否支持 -Select
参数。
更一致地限制输出中的项目数
早期版本的Amazon Tools for PowerShell允许您使用 -MaxItems
参数指定最终输出中返回对象的最大数量。
此行为已从 AWS.Tools
中删除。
中 AWSPowerShell已弃用此行为。 NetCore 和 AWSPowerShell,将在 future 版本中从这些版本中删除。
如果底层服务 API 支持 MaxItems
参数,则该参数仍可按照 API 指定正常使用。但它不再具有限制 cmdlet 输出中返回的项目数的添加行为。
要限制最终输出中返回的项目数,请将输出通过管道传递给 Select-Object
cmdlet 并指定 -First
参数,其中 n
n
是要包含在最终输出中的最大项目数。
PS >
Get-S3ObjectV2 -BucketName
BUCKET_NAME
-Select S3Objects.Key | select -first 2file1.txt file2.txt
并非所有 Amazon 服务都以相同的方式支持 -MaxItems
,所以这消除了不一致性和有时出现的意外结果。此外,-MaxItems
与新的 -Select 参数结合,有时会导致混淆的结果。
更易于使用的流参数
Stream
或 byte[]
类型的参数现在可以接受 string
、string[]
或 FileInfo
值。
例如,您可以使用以下任何示例。
PS >
Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream '{
>>
"some": "json"
>>
}'
PS >
Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream (ls .\some.json)
PS >
Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream @('{', '"some": "json"', '}')
Amazon Tools for PowerShell 使用 UTF-8 编码将所有字符串转换为 byte[]
。
按属性名称扩展管道
为了使用户体验更加一致,现在您可以通过为任意 参数指定属性名来传递管道输入。
在以下示例中,我们创建一个自定义对象,其属性具有与目标 cmdlet 的参数名称相匹配的名称。当 cmdlet 运行时,它会自动使用这些属性作为其参数。
PS >
[pscustomobject] @{ BucketName='myBucket'; Key='file1.txt'; PartNumber=1 } | Get-S3ObjectMetadata
注意
Amazon Tools for PowerShell早期版本中的部分属性支持此功能。版本 4 通过为所有 参数启用该功能,实现了更好的一致性。
静态通用参数
为了提高Amazon Tools for PowerShell版本 4.0 中的一致性,所有参数都是静态的。
在 Amazon Tools for PowerShell 的早期版本中,一些通用参数(例如 AccessKey
、SecretKey
、ProfileName
或 Region
)均为动态
PS >
Get-EC2Region -Region us-west-2
的早期版本将值 PowerShell 绑定us-west-2
到-RegionName
静态参数而不是-Region
动态参数。这可能会使用户感到困惑。
AWS.Tools
声明和强制执行强制性参数
现在,AWS.Tools.*
模块声明并强制执行强制性的 cmdlet 参数。当Amazon服务声明需要某个 API 的参数时,如果您没有指定相应的 cmdlet 参数,则 PowerShell 会提示您输入相应的 cmdlet 参数。这仅适用于 AWS.Tools
。为确保向后兼容,这不适用于 AWSPowerShell。 NetCore 或 AWSPowerShell。
所有参数均可为 null
您现在可以将 $null
分配给值类型参数(数字和日期)。此更改不应影响现有脚本。这使您能够绕过输入强制性参数的提示。强制性参数仅在 AWS.Tools
中强制执行。
如果您使用版本 4 运行以下示例,它会有效地绕过客户端验证,因为您为每个强制性参数提供一个“值”。但是,Amazon EC2 API 服务调用失败,因为Amazon服务仍需要该信息。
PS >
Get-EC2InstanceAttribute -InstanceId $null -Attribute $null
WARNING: You are passing $null as a value for parameter Attribute which is marked as required. In case you believe this parameter was incorrectly marked as required, report this by opening an issue at https://github.com/aws/aws-tools-for-powershell/issues. WARNING: You are passing $null as a value for parameter InstanceId which is marked as required. In case you believe this parameter was incorrectly marked as required, report this by opening an issue at https://github.com/aws/aws-tools-for-powershell/issues. Get-EC2InstanceAttribute : The request must contain the parameter instanceId
删除以前弃用的功能
下列功能在Amazon Tools for PowerShell的以前版本中已弃用,并已在版本 4 中删除:
-
从
Stop-EC2Instance
cmdlet 删除了-Terminate
参数。请改用Remove-EC2Instance
。 -
已从 Clear-AWSCredential cmdlet 中删除该
-ProfileName
参数。请改用Remove-AWSCredentialProfile
。 -
删除了 cmdlet
Import-EC2Instance
和Import-EC2Volume
。