Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

Amazon Tools for PowerShell 版本 5（V5）已经发布！

要开始使用新版本的工具，请参阅《Amazon Tools for PowerShell 用户指南（V5）》，特别是关于迁移到 V5 的主题。

从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 为您调用 适用于 .NET 的 Amazon SDK 服务 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 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 * 返回由软件开发工具包 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      :

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

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 中删除。

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

如果底层服务 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 使用 UTF-8 编码将所有字符串转换为 byte[]。

按属性名称扩展管道

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

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

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

静态通用参数

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

在 Amazon Tools for PowerShell 的早期版本中，一些通用参数（例如 AccessKey、SecretKey、ProfileName 或 Region）均为动态，而其他参数为静态。这可能会产生问题，因为 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 中删除：