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

从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

为了帮助您发现 Amazon 模块集合中各个 AWS.Tools 服务的模块名称,您可以使用 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 为您调用 Amazon SDK for .NET 服务 API。然后,Amazon Tools for PowerShell 客户端将响应转换为可在 PowerShell 脚本中使用的对象,并通过管道传递到其他命令。有时候,最终 PowerShell 对象在原始响应中提供的字段或属性数量超过了您的需要,而在其他情况下,您可能希望对象包含默认情况下不存在的响应字段或属性。通过 -Select 参数,您可以指定 cmdlet 返回的 .NET 对象中包含的内容。

例如,Get-S3Object cmdlet 调用 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

在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 :

您还可以指定所需特定嵌套属性的路径。以下示例仅返回 Key 数组中每个元素的 S3Objects 属性。

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 参数。

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

早期版本的Amazon Tools for PowerShell允许您使用 -MaxItems 参数指定最终输出中返回对象的最大数量。

此行为已从 AWS.Tools 中删除。

此行为已在 AWSPowerShell.NetCore 和 AWSPowerShell 中弃用,并将在以后的版本中删除。

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

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

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

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

更易于使用的流参数

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

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 的早期版本中,一些通用参数(例如 AccessKeySecretKeyProfileNameRegion)均为动态,而其他参数为静态。这可能会产生问题,因为 PowerShell 在动态参数之前绑定静态参数。例如,假设您运行了以下命令。

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

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

AWS.Tools 声明和强制执行强制性参数

现在,AWS.Tools.* 模块声明并强制执行强制性的 cmdlet 参数。当 Amazon 服务声明需要 API 的参数时,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 中删除:

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

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

  • 删除了 cmdlet Import-EC2InstanceImport-EC2Volume