從 AWS Tools for PowerShell 3.3 版遷移至第 4 版

AWS Tools for PowerShell 第 4 版是與 AWS Tools for PowerShell 3.3 版回溯相容的更新。此版本新增了大幅改善的項目，同時保持現有的 Cmdlet 行為。

在升級至新版本後，現有指令碼應該能繼續運作，但建議您在升級生產環境前先進行徹底的測試。

本節說明這些變更並解說這些變更可能會對指令碼有何影響。

新全面模組化 AWS.Tools 版本

的 AWSPowerShell. NetCore 和 AWSPowerShell 軟件包是「整體」。這表示所有 AWS 服務都是由同一個模組提供支援，模組會變得很大，而且會隨著新增每項 AWS 服務和功能而變得更大。全新 AWS.Tools 套件會分為多個較小的模組，能讓您彈性選擇下載及安裝您使用之 AWS 服務所需的項目。此套件包含一個所有其他模組需要的共用 AWS.Tools.Common 模組，以及一個可視需要簡化模組安裝、更新及移除作業的 AWS.Tools.Installer 模組。

這也會在第一次呼叫時啟用 Cmdlet 的自動匯入功能，而不必先呼叫 Import-module。不過，若要在呼叫指令程式之前與相關聯的 .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

您可以使用 Get-AWSService Cmdlet，協助您探索 AWS.Tools 模組集合中每項 AWS 服務的模組名稱。

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 都會使用 AWS SDK for .NET 呼叫 AWS 服務 API。然後AWS Tools for PowerShell客戶端將響應轉換為一個對象，您可以在 PowerShell 腳本中使用該對象，並將其管道轉換為其他命令。有時，final PowerShell 對像在原始響應中具有比您需要的更多字段或屬性，而其他時候您可能希望對象包含默認情況下不存在的響應的字段或屬性。-Select 參數可讓您指定 Cmdlet 所傳回之 .NET 物件中要包含的項目。

例如，Get-S3Object 指令程式會叫用 Amazon S3 開發套件作業。ListObjects該操作返回一個ListObjectsResponse對象。不過，根據預設，指Get-S3Object令程式只會傳回 SDK 回應的S3Objects元素給 PowerShell 使用者。在以下範例中，該物件是具有兩個元素的陣列。

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

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

您也可以指定您想要的特定巢狀屬性的路徑。以下範例只會傳回 S3Objects 陣列中每個元素的 Key 屬性。

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 參數。

以更一致的方式限制輸出的項目數

舊版 AWS Tools for PowerShell 可讓您使用 -MaxItems 參數指定最終輸出中傳回的項目數上限。

AWS.Tools 已移除此行為。

此行為已在中取代 AWSPowerShell。 NetCore 和 AWSPowerShell，並將在 future 的發行版本中從這些版本中移除。

如果基礎服務 API 支援 MaxItems 參數，則仍可依 API 指定取得及運作，但不會再有限制 Cmdlet 輸出中傳回之項目數的新增行為。

若要限制最終輸出中傳回的項目數，請將輸出輸送至 Select-Object Cmdlet 並指定 -First n 參數，其中 n 是要在最終輸出中包含的項目數上限。

PS > Get-S3ObjectV2 -BucketName BUCKET_NAME -Select S3Objects.Key | select -first 2
file1.txt
file2.txt

以往並非所有 AWS 服務皆以同樣的方式支援 -MaxItems，因此這移除了該不一致的情況，以及有時會發生的非預期結果。此外結合新 -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 會使用 UTF-8 編碼將所有字串轉換為 byte[]。

依屬性名稱擴充管道

為了提升使用者體驗的一致性，您現在可以指定「任何」參數的屬性名稱，藉此傳遞管道輸入。

在以下範例中，我們建立了一個自訂物件，其屬性具有符合目標 Cmdlet 參數名稱的名稱。當 Cmdlet 執行時，它會自動使用這些屬性做為其參數。

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

注意

在舊版 AWS Tools for PowerShell 中，有些屬性可支援此體驗。第 4 版可讓您指定「所有」參數，讓此體驗更加一致。

靜態常見參數

為提升 AWS Tools for PowerShell 4.0 版的一致性，所有參數皆為靜態。

在舊版 AWS Tools for PowerShell 中，某些常見參數 (例如 AccessKey、SecretKey、ProfileName 或 Region) 為動態，而所有其他參數則為靜態。這可能會產生問題，因為在動態參數之前 PowerShell 綁定靜態參數。例如，假設您執行以下命令。

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

早期版本的us-west-2將值 PowerShell 繫結至-RegionName靜態參數，而不是動-Region態參數。這可能會讓使用者產生混淆。

AWS.Tools 會宣告並強制執行必要參數

AWS.Tools.* 模組現在會宣告並強制執行必要的 Cmdlet 參數。當AWS服務宣告需要 API 的參數時，如果您未指定對應的 cmdlet 參數，則 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.
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

移除先前取代的功能

舊版 AWS Tools for PowerShell 已取代以下功能，而第 4 版也取代了這些功能：

• 移除 Stop-EC2Instance Cmdlet 中的 -Terminate 參數。請改用 Remove-EC2Instance。

• 已從清除AWSCredential 指令程式中移除-ProfileName參數。請改用 Remove-AWSCredentialProfile。

• 移除 Import-EC2Instance 和 Import-EC2Volume Cmdlet。