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/)。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 從 3.3 AWS Tools for PowerShell 版遷移至 第 4 版 AWS Tools for PowerShell 第 4 版是 3.3 AWS Tools for PowerShell 版的回溯相容更新。此版本新增了大幅改善的項目，同時保持現有的 Cmdlet 行為。 在升級至新版本後，現有指令碼應該能繼續運作，但建議您在升級生產環境前先進行徹底的測試。 本節說明這些變更並解說這些變更可能會對指令碼有何影響。 ## 新全面模組化 `AWS.Tools` 版本 AWSPowerShell.NetCore 和 AWSPowerShell 套件為「整合式」。這表示在相同的模組中支援所有 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 都會使用 適用於 .NET 的 AWS SDK呼叫 AWS 服務 API。然後， 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 只會將開發套件回應的 `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` 已移除此行為。 在 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 ``` 並非所有 AWS 服務`-MaxItems`都以相同的方式支援，因此這會移除該不一致的情況，以及有時發生的非預期結果。此外結合新 [`-Select`](#migrate-select) 參數的 `-MaxItems` 有時可能會導致令人混淆的結果。 ## 更易於使用的串流參數 `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 參數為必要時，如果您尚未指定該參數，PowerShell 則會提示您對應的 Cmdlet 參數。這僅適用於 `AWS.Tools`。為確保回溯相容性，這不適用於 AWSPowerShell.NetCore 或 AWSPowerShell。 ## 所有參數皆可為 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`。 + 移除 `Import-EC2Instance` 和 `Import-EC2Volume` Cmdlet。