从适用于 PowerShell 的 AWS 工具版本 3.3 迁移到版本 4 - 适用于 PowerShell 的 AWS 工具
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

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

从适用于 PowerShell 的 AWS 工具版本 3.3 迁移到版本 4

适用于 PowerShell 的 AWS 工具版本 4 是对适用于 PowerShell 的 AWS 工具的向后兼容更新。它在维护现有 cmdlet 行为的同时添加了大量的改进功能。

升级到新版本后,您的现有脚本应继续正常工作,但我们建议您在升级生产环境之前实施全面测试。

本节介绍了相关更改,并说明了这些更改可能会对脚本造成的影响。

新的完全模块化 AWS.Tools 版本

AWS PowerShell 软件包和 AWS PowerShell 软件包是 “整体式” 的软件包。这意味着所有 AWS 服务都在同一个模块中得到支持,这使得该模块非常庞大,并随着添加各个新的 AWS 服务和功能变得越来越大。新的 AWS S.Tools 软件包被拆分成较小的模块,这使您可以灵活地仅下载和安装所使用的 AWS 服务需要的模块。该软件包包括所有其他模块所需的共享 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 中各个 AWS 服务的模块名称。Tools 模块集合中,您可以使用Get-AWSServicecmdlet。

PS > Get-AWSService Service : ACMPCA CmdletNounPrefix : PCA ModuleName : AWS.Tools.ACMPCA SDKAssemblyVersion : 3.3.101.56 ServiceName : AWS 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 使用适用于 .NET 的 AWS 开发工具包为您调用 AWS 服务 API。然后,适用于 PowerShell 的 AWS Tools 客户端将响应转换为可在 PowerShell 脚本中使用的对象,并通过管道传递到其他命令。有时候,最终 PowerShell 对象在原始响应中提供的字段或属性数量超过了您的需要,而在其他情况下,您可能希望对象包含默认情况下不存在的响应字段或属性。通过 -Select 参数,您可以指定 cmdlet 返回的 .NET 对象中包含的内容。

例如,获取 S3 对象命令调用 Amazon S3 软件开发工具包操作ListObjects。该操作返回一个 ListObjectsResponse 对象。但是,默认情况下,Get-S3Object cmdlet 仅向 PowerShell 用户返回软件开发工具包响应的 S3Objects 元素。在下面的示例中,该对象是包含两个元素的数组。

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

在适用于 PowerShell 的 AWS 工具版本 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.Key file1.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 参数。

更一致地限制输出中的项目数

早期版本的适用于 PowerShell 的 AWS 工具使您能够使用-MaxItems参数指定最终输出中返回对象的最大数量。

此行为已从 AWS 中删除。

此行为已在 AWS PowerShell 中弃用,并将在以后的版本中删除。

如果底层服务 API 支持 MaxItems 参数,则该参数仍可按照 API 指定正常使用。但它不再具有限制 cmdlet 输出中返回的项目数的添加行为。

要限制最终输出中返回的项目数,请通过管道传递到Select-Items命令并指定-First n参数,其中 n 是要包含在最终输出中的项目的最大数量。

PS > Get-S3Object -BucketName mybucket -Select S3Objects.Key | select -first 1* file1.txt

并非所有 AWS 服务都支持-MaxItems,所以这消除了不一致性和有时出现的意外结果。此外,-MaxItems 与新的 -Select 参数结合,有时会导致混淆的结果。

更易于使用的流参数

类型的参数Stream或者byte[]现在可以接受stringstring[],或者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"', '}')

适用于 PowerShell 的 AWS 工具可将所有字符串转换为byte[]使用 UTF-8 编码。

按属性名称扩展管道

为了使用户体验更加一致,现在您可以通过为任意 参数指定属性名来传递管道输入。

在以下示例中,我们创建一个自定义对象,其属性具有与目标 cmdlet 的参数名称相匹配的名称。当 cmdlet 运行时,它会自动使用这些属性作为其参数。

PS > [pscustomobject] @{ BucketName='myBucket'; Key='file1.txt'; PartNumber=1 } | Get-S3ObjectMetadata
注意

适用于 PowerShell 的 AWS 工具早期版本中的部分属性支持此功能。版本 4 通过为所有 参数启用该功能,实现了更好的一致性。

静态通用参数

为了提高适用于 PowerShell 的 AWS 工具版本 4.0 中的一致性,所有参数都是静态的。

在适用于 PowerShell 的 AWS 工具的早期版本中,一些常见参数,例如AccessKeySecretKeyProfileName,或者Region, 是动态,而所有其他参数都是静态的。这可能会产生问题,因为 PowerShell 在动态参数之前绑定静态参数。例如,假设您运行了以下命令。

PS > Get-EC2Region -Region us-west-2

早期版本的 PowerShell 将值 us-west-2 绑定到 -RegionName 静态参数而不是 -Region 动态参数。这可能会使用户感到困惑。

AWS Tools 声明并强制执行强制性参数

AWS Sools.* 模块现在声明并强制执行强制性的 cmdlet 参数。当 AWS 服务声明需要 API 的参数时,PowerShell 会提示您输入相应的 cmdlet 参数(如果您未指定该参数)。这适用于 AWS。Tools。为确保向后兼容性,这不适用于 AWS PowerShell。

所有参数均可为 null

您现在可以将 $null 分配给值类型参数(数字和日期)。此更改不应影响现有脚本。这使您能够绕过输入强制性参数的提示。强制性参数仅在 AWS 中强制执行。

如果您使用版本 4 运行以下示例,它会有效地绕过客户端验证,因为您为每个强制性参数提供一个“值”。但是,Amazon EC2 API 服务调用失败,因为 AWS 服务仍需要该信息。

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

删除以前弃用的功能

下列功能在适用于 PowerShell 的 AWS 工具的以前版本中已弃用,并已在版本 4 中删除:

  • Stop-EC2Instance cmdlet 删除了 -Terminate 参数。请改用 Remove-EC2Instance

  • 从 Clear-AWSCredential cmdlet 删除了 -ProfileName 参数。请改用 Remove-AWSCredentialProfile

  • 删除了 cmdlet Import-EC2InstanceImport-EC2Volume