AWS Tools for PowerShell V4 已进入维护模式。 我们建议您迁移到 [AWS Tools for PowerShell V5](https://docs.aws.amazon.com/powershell/v5/userguide/)。有关如何迁移的更多详细信息和信息，请参阅我们的[维护模式公告](https://aws.amazon.com/blogs/developer/aws-tools-for-powershell-v4-maintenance-mode-announcement/)。 本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 从 AWS Tools for PowerShell 版本 3.3 迁移到版本 4 AWS Tools for PowerShell 版本 4 是 3.3 版本的向后兼容更新。 AWS Tools for PowerShell 它在维护现有 cmdlet 行为的同时添加了大量的改进功能。 升级到新版本后，您的现有脚本应继续正常工作，但我们建议您在升级生产环境之前实施全面测试。 本节介绍了相关更改，并说明了这些更改可能会对脚本造成的影响。 ## 全新的完全模块化 `AWS.Tools` 版本 AWSPower壳牌。 NetCore 而且 AWSPower Shell 软件包是 “整体的”。这意味着所有 AWS 服务都支持在同一个模块中，这使得它变得非常大，并且随着每项新 AWS 服务和功能的添加而变得越来越大。新`AWS.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.Tools`集合中每项 AWS 服务的模块名称，可以使用 `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 为您调用 AWS 服务。 适用于 .NET 的 AWS SDK然后， AWS Tools for PowerShell 客户端将响应转换为可以在 PowerShell 脚本中使用的对象，并通过管道传输到其他命令。有时，最终 PowerShell 对象在原始响应中包含的字段或属性比您需要的要多，而其他时候，您可能希望该对象包含默认情况下不存在的响应字段或属性。通过 `-Select` 参数，您可以指定 cmdlet 返回的 .NET 对象中包含的内容。 例如，[Get-S3Object](https://docs.aws.amazon.com/powershell/v4/reference/items/Get-S3Object.html)cmdlet 调用 Amazon S3 软件开发工具包操作。[ListObjects](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html?page=S3/MS3ListObjectsListObjectsRequest.html)该操作返回一个[ListObjectsResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html?page=S3/MS3ListObjectsListObjectsRequest.h)对象。但是，默认情况下，`Get-S3Object`cmdlet 仅向用户返回 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 ``` 在 AWS 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 的[参考主题](https://docs.aws.amazon.com/powershell/v4/reference/)确定它是否支持 `-Select` 参数。 ## 更一致地限制输出中的项目数 的早期版本 AWS 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 ``` 并非所有 AWS 服务都以相同`-MaxItems`的方式支持，因此这消除了这种不一致性以及有时会出现的意外结果。此外，`-MaxItems` 与新的 [`-Select`](#migrate-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"', '}') ``` AWS Tools for PowerShell 将所有字符串转换为`byte[]`使用 UTF-8 编码。 ## 按属性名称扩展管道 为了使用户体验更加一致，现在您可以通过为*任意* 参数指定属性名来传递管道输入。 在以下示例中，我们创建一个自定义对象，其属性具有与目标 cmdlet 的参数名称相匹配的名称。当 cmdlet 运行时，它会自动使用这些属性作为其参数。 ``` PS > [pscustomobject] @{ BucketName='amzn-s3-demo-bucket'; Key='file1.txt'; PartNumber=1 } | Get-S3ObjectMetadata ``` **注意** 某些属性在的早期版本中支持此功能 AWS Tools for PowerShell。版本 4 通过为*所有* 参数启用该功能，实现了更好的一致性。 ## 静态通用参数 为了提高版本 4.0 的一致性 AWS Tools for PowerShell，所有参数都是静态的。 在的早期版本中 AWS Tools for PowerShell，一些常用参数（例如`AccessKey`、`SecretKey``ProfileName``Region`、或）是[动态](https://docs.microsoft.com/dotnet/api/system.management.automation.idynamicparameters)的，而所有其他参数都是静态的。这可能会造成问题，因为在动态参数之前 PowerShell 绑定静态参数。例如，假设您运行了以下命令。 ``` PS > Get-EC2Region -Region us-west-2 ``` 的早期版本将值 PowerShell 绑定`us-west-2`到`-RegionName`静态参数而不是`-Region`动态参数。这可能会使用户感到困惑。 ## `AWS.Tools` 声明和强制执行强制性参数 现在，`AWS.Tools.*` 模块声明并强制执行强制性的 cmdlet 参数。当 AWS 服务声明需要某个 API 的参数时，如果您没有指定相应的 cmdlet 参数，则 PowerShell 会提示您输入相应的 cmdlet 参数。这仅适用于 `AWS.Tools`。为确保向后兼容，这不适用于 AWSPower Shell。 NetCore 或者 AWSPower壳牌。 ## 所有参数均可为 null 您现在可以将 `$null` 分配给值类型参数（数字和日期）。此更改不应影响现有脚本。这使您能够绕过输入强制性参数的提示。强制性参数仅在 `AWS.Tools` 中强制执行。 如果您使用版本 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](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](https://github.com/aws/aws-tools-for-powershell/issues). Get-EC2InstanceAttribute : The request must contain the parameter instanceId ``` ## 删除以前弃用的功能 以下功能在以前的版本中已被弃用， AWS Tools for PowerShell 在版本 4 中已删除： + 从 `Stop-EC2Instance` cmdlet 删除了 `-Terminate` 参数。请改用 `Remove-EC2Instance`。 + 已从 Clear-AWSCredential cmdlet 中删除该`-ProfileName`参数。请改用 `Remove-AWSCredentialProfile`。 + 删除了 cmdlet `Import-EC2Instance` 和 `Import-EC2Volume`。