View a markdown version of this page

从 Amazon Tools for PowerShell 版本 3.3 迁移到版本 4 - Amazon Tools for PowerShell （版本 4）
全新的完全模块化 AWS.Tools 版本新 Get-AWSService cmdlet用于控制 Cmdlet 返回的对象的新 -Select 参数更一致地限制输出中的项目数更易于使用的流参数按属性名称扩展管道静态通用参数AWS.Tools 声明和强制执行强制性参数所有参数均可为 null删除以前弃用的功能
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

Amazon Tools for PowerShell V4 的支持已到期。

我们建议您迁移到 Amazon Tools for PowerShell V5 。有关如何迁移的更多详细信息和信息，请参阅我们的终止支持公告。

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

从 Amazon Tools for PowerShell 版本 3.3 迁移到版本 4

Amazon Tools for PowerShell 版本 4 是 3.3 版本的向后兼容更新。 Amazon Tools for PowerShell 它在维护现有 cmdlet 行为的同时添加了大量的改进功能。

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

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

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

AWSPower壳牌。 NetCore 而且 AWSPower Shell 软件包是 “整体的”。这意味着所有 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 都使用来 APIs 为您调用 Amazon 服务。 适用于 .NET 的 Amazon SDK然后， Amazon Tools for PowerShell 客户端将响应转换为可以在 PowerShell 脚本中使用的对象，并通过管道传输到其他命令。有时，最终 PowerShell 对象在原始响应中包含的字段或属性比您需要的要多，而其他时候，您可能希望该对象包含默认情况下不存在的响应字段或属性。通过 -Select 参数，您可以指定 cmdlet 返回的 .NET 对象中包含的内容。

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

PS > Get-S3Object -BucketName amzn-s3-demo-bucket

ETag : "01234567890123456789012345678901111"
BucketName : amzn-s3-demo-bucket
Key : file1.txt
LastModified : 9/30/2019 1:31:40 PM
Owner : Amazon.S3.Model.Owner
Size : 568
StorageClass : STANDARD

ETag : "01234567890123456789012345678902222"
BucketName : amzn-s3-demo-bucket
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 *返回由 SDK API 调用返回的完整.NET 响应对象。

PS > Get-S3Object -BucketName amzn-s3-demo-bucket -Select *
  IsTruncated    : False
  NextMarker     :
  S3Objects      : {file1.txt, file2.txt}
  Name           : amzn-s3-demo-bucket
  Prefix         :
  MaxKeys        : 1000
  CommonPrefixes : {}
  Delimiter      :

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

PS > Get-S3Object -BucketName amzn-s3-demo-bucket -Select S3Objects.Key
file1.txt
file2.txt

在某些情况下，返回 cmdlet 参数可能非常有用。您可通过 -Select ^ParameterName 实现此目的。此功能取代 -PassThru 参数，该参数仍然可用，但已弃用。

PS > Get-S3Object -BucketName amzn-s3-demo-bucket -Select S3Objects.Key |
>> Write-S3ObjectTagSet -Select ^Key -BucketName amzn-s3-demo-bucket -Tagging_TagSet @{ Key='key'; Value='value'}
  file1.txt
  file2.txt

每个 cmdlet 的参考主题确定它是否支持 -Select 参数。

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

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

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

AWSPower命令行管理程序中已不推荐使用此行为。 NetCore 和 AWSPower Shell，并将在未来的版本中从这些版本中删除。

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

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

PS > Get-S3ObjectV2 -BucketName amzn-s3-demo-bucket -Select S3Objects.Key | select -first 2
file1.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 将所有字符串转换为byte[]使用 UTF-8 编码。

按属性名称扩展管道

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

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

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

某些属性在的早期版本中支持此功能 Amazon Tools for PowerShell。版本 4 通过为所有 参数启用该功能，实现了更好的一致性。

静态通用参数

为了提高版本 4.0 的一致性 Amazon Tools for PowerShell，所有参数都是静态的。

在的早期版本中 Amazon Tools for PowerShell，一些常用参数（例如AccessKey、SecretKeyProfileNameRegion、或）是动态的，而所有其他参数都是静态的。这可能会造成问题，因为在动态参数之前 PowerShell 绑定静态参数。例如，假设您运行了以下命令。

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。为确保向后兼容，这不适用于 AWSPower Shell。 NetCore 或者 AWSPower壳牌。

所有参数均可为 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。