第 5 版 (V5) AWS Tools for PowerShell 已發行！ 如需有關中斷變更和遷移應用程式的資訊，請參閱[遷移主題](https://docs.aws.amazon.com/powershell/v5/userguide/migrating-v5.html)。 [https://docs.aws.amazon.com/powershell/v5/userguide/migrating-v5.html](https://docs.aws.amazon.com/powershell/v5/userguide/migrating-v5.html) 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 從 AWS Tools for PowerShell 第 4 版遷移到第 5 版 AWS Tools for PowerShell 第 5 版 (V5) 有重大變更，這可能會導致您現有的指令碼停止運作。本主題說明 V5 中的重大變更，以及您可能需要從 V4 遷移環境或程式碼的可能工作。 如需 中值得注意變更的其他資訊， AWS Tools for PowerShell 另請參閱下列資源： + 部落格文章 [AWS Tools for PowerShell V5 現在已全面推出](https://aws.amazon.com/blogs/developer/aws-tools-for-powershell-v5-now-generally-available/)。 + [GitHub 中的 V5 開發追蹤器問題](https://github.com/aws/aws-tools-for-powershell/issues/357)。除了重大變更清單之外，請務必查看每個預覽的詳細資訊。 + 部落格文章[預覽 1 of AWS Tools for PowerShell V5](https://aws.amazon.com/blogs/developer/preview-1-of-aws-tools-for-powershell-v5/) **注意** 由於 AWS Tools for PowerShell 依賴 適用於 .NET 的 AWS SDK，與開發套件 V4 相關的部分變更也可能影響適用於 PowerShell 的工具 V5。若要查看 的 V4 變更 適用於 .NET 的 AWS SDK，請參閱《 [適用於 .NET 的 AWS SDK 開發人員指南](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/)》中的[遷移資訊](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html)。 ## 最低 PowerShell 版本 對於 AWS Tools for PowerShell名為 *AWSPowerShell* 的舊版、Windows 特定、單一、大型模組版本，模組的最低支援 PowerShell 版本已更新為 5.1。這是為了符合 .NET Framework 4.7.2 適用於 .NET 的 AWS SDK 的新最低版本。 如需舊版 AWSPowerShell 模組的詳細資訊，請參閱 [在 Windows 上安裝](pstools-getting-set-up-windows.md)。 ## 安裝或更新 `AWS.Tools` V4 安裝或更新 AWS Tools for PowerShell稱為 的模組化版本時`AWS.Tools`， `AWS.Tools` `Install-AWSToolsModule`和 `Update-AWSToolsModule` cmdlet 預設會自然使用 第 5 版。如果您因為某些原因而需要安裝或更新 第 4 版`AWS.Tools`，您可以分別使用下列命令來執行此操作： ``` Install-AWSToolsModule -MaximumVersion '4.9.999' Update-AWSToolsModule -MaximumVersion '4.9.999' ``` 如需安裝和更新 Tools for PowerShell 的詳細資訊，請參閱 [開始使用](pstools-getting-set-up.md) ## 使用 CTRL\$1C 取消 cmdlet 執行 第 5 版 AWS Tools for PowerShell 可讓您使用鍵盤快速鍵，例如 CTRL\$1C 來取消 cmdlet 執行。 ## Nullable 值類型 採用自 的類型 適用於 .NET 的 AWS SDK 已更新為使用 SDK 新的 nullable 變更。例如， 類型的屬性`int`已變更為 `Nullable[int]`。此變更不會影響為 AWS cmdlet 指定輸入參數值的方式，因為這些值類型參數已建模為 nullable。不過，Cmdlet 輸出的 nullable 類型是一項重大變更，因為 Cmdlet 輸出中的屬性將包含 `$null`，而不是 類型的各種預設值。 下列範例示範 Tools for PowerShell V4 中的行為。在此範例中， `MissingMeta` 屬性設定為 0，因為這是類型 的預設值`int`。 ``` # In V4 PS > Get-S3ObjectMetadata -BucketName amzn-s3-demo-bucket -Key 'test' | >> Select LastModified, MissingMeta, ObjectLockRetainUntilDate, BucketKeyEnabled LastModified MissingMeta ObjectLockRetainUntilDate BucketKeyEnabled ------------ ----------- ------------------------- ---------------- 8/29/2023 10:20:44 PM 0 1/1/0001 12:00:00 AM ``` 下列範例示範 Tools for PowerShell 的 V5 中的行為。在此範例中， `MissingMeta` 屬性設定為 `$null`。 ``` # In V5 PS > Get-S3ObjectMetadata -BucketName amzn-s3-demo-bucket -Key 'test' | >> Select LastModified, MissingMeta, ObjectLockRetainUntilDate, BucketKeyEnabled LastModified MissingMeta ObjectLockRetainUntilDate BucketKeyEnabled ------------ ----------- ------------------------- ---------------- 8/29/2023 10:20:44 PM ``` 在大多數情況下，不需要變更程式碼，因為 PowerShell 具有從 Null 值類型隱含轉換為非 Null 值類型。不過，這是比較邏輯程式碼的重大變更，會明確檢查 nullable 值類型的預設值。必須修改檢查非 Null 類型的預設值的比較邏輯，以檢查 `$null`。 對於其中一些類型，下列範例示範如何更新為 V4 編寫的程式碼，以檢查是否未傳回任何內容： ``` #Type int: # In V4, if you were checking whether an int is 0... if($s3Metadata.MissingMeta -eq 0){} # In V5, check if the int is null instead: if($s3Metadata.MissingMeta -eq $null) {} # Type datetime: # In V4, if you were checking whether a datetime is '0001-01-01'... if($s3Metadata.ObjectLockRetainUntilDate -eq '0001-01-01'){} # In V5, check if the datetime is null instead: if($s3Metadata.ObjectLockRetainUntilDate -eq $null){} # Type boolean: # In V4, if you were checking whether a boolean is $false... if($s3Metadata.BucketKeyEnabled -eq $false){} # In V5, check if the boolean is null instead: if($s3Metadata.BucketKeyEnabled -eq $null) ``` 由於 AWS Tools for PowerShell 依賴 適用於 .NET 的 AWS SDK，因此檢查類似的變更對 SDK 第 4 版的影響可能很有用。若要尋找此資訊，請參閱《 [適用於 .NET 的 AWS SDK 開發人員指南](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/)》中的[值類型](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html#net-dg-v4-value-types)遷移內容。 ## 集合 某些 cmdlet 輸出已變更為傳回，`$null`而不是類型 `List`或 的空白集合`Dictionary`。如需詳細資訊，包括如何還原至舊版行為，請參閱《 [適用於 .NET 的 AWS SDK 開發人員指南](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/)》中的[集合](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html#net-dg-v4-collections)的遷移內容。 ## DateTime 與 UTC DateTime 有些 V4 cmdlet 會定義已淘汰的 DateTime 參數，以及替代的 UTC DateTime 參數。這些過時的 DateTime 參數已從 V5 cmdlet 中移除，而且 UTC DateTime 參數的名稱已變更為非 UTC DateTime 參數的原始名稱。 以下是已實作此變更的 cmdlet 範例。 + `Get-ASScheduledAction` ([V4 cmdlet](https://docs.aws.amazon.com/powershell/v4/reference/items/Get-ASScheduledAction.html) 和 [V5 cmdlet](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-ASScheduledAction.html))： + `StartTime` 參數已移除，且`UtcStartTime`參數的名稱已變更為「StartTime」。 + `EndTime` 參數已移除，且`UtcEndTime`參數的名稱已變更為「EndTime」。 + `Copy-S3Object` ([V4 cmdlet](https://docs.aws.amazon.com/powershell/v4/reference/items/Copy-S3Object.html) 和 [V5 cmdlet](https://docs.aws.amazon.com/powershell/v5/reference/items/Copy-S3Object.html))： + `ModifiedSinceDate` 參數已移除，且`UtcModifiedSinceDate`參數的名稱已變更為 "ModifiedSinceDate"。 + `UnmodifiedSinceDate` 參數已移除，且`UtcUnmodifiedSinceDate`參數的名稱已變更為「UnmodifiedSinceDate」。 以下是受此變更影響的 cmdlet 完整清單。 ### 開啟以檢視項目 + [Get-ASScheduledAction](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-ASScheduledAction.html) + [Write-ASScheduledUpdateGroupAction](https://docs.aws.amazon.com/powershell/v5/reference/items/Write-ASScheduledUpdateGroupAction.html) + [Get-CWAlarmHistory](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-CWAlarmHistory.html) + [Get-CWMetricData](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-CWMetricData.html) + [Get-CWMetricStatistic](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-CWMetricStatistic.html) （別名 Get-CWMetricStatistics) + [New-EC2Fleet](https://docs.aws.amazon.com/powershell/v5/reference/items/New-EC2Fleet.html) + [Get-EC2FleetHistory](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-EC2FleetHistory.html) + [Get-EC2ScheduledInstance](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-EC2ScheduledInstance.html) + [Get-EC2ScheduledInstanceAvailability](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-EC2ScheduledInstanceAvailability.html) + [Get-EC2SpotFleetRequestHistory](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-EC2SpotFleetRequestHistory.html) + [Get-EC2SpotPriceHistory](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-EC2SpotPriceHistory.html) + [Import-EC2Image](https://docs.aws.amazon.com/powershell/v5/reference/items/Import-EC2Image.html) + [Import-EC2Snapshot](https://docs.aws.amazon.com/powershell/v5/reference/items/Import-EC2Snapshot.html) + [Request-EC2SpotFleet](https://docs.aws.amazon.com/powershell/v5/reference/items/Request-EC2SpotFleet.html) + [Request-EC2SpotInstance](https://docs.aws.amazon.com/powershell/v5/reference/items/Request-EC2SpotInstance.html) + [Send-EC2InstanceStatus](https://docs.aws.amazon.com/powershell/v5/reference/items/Send-EC2InstanceStatus.html) + [Get-ECEvent](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-ECEvent.html) + [Get-EBEnvironment](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-EBEnvironment.html) + [Get-EBEvent](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-EBEvent.html) + [Get-IOTTaskList](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-IOTTaskList.html) + [Get-IOTViolationEventList](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-IOTViolationEventList.html) + [Get-RDSEvent](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-RDSEvent.html) + [Reset-RDSDBCluster](https://docs.aws.amazon.com/powershell/v5/reference/items/Reset-RDSDBCluster.html) + [Restore-RDSDBClusterToPointInTime](https://docs.aws.amazon.com/powershell/v5/reference/items/Restore-RDSDBClusterToPointInTime.html) + [Restore-RDSDBInstanceToPointInTime](https://docs.aws.amazon.com/powershell/v5/reference/items/Restore-RDSDBInstanceToPointInTime.html) + [Get-RSClusterSnapshot](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-RSClusterSnapshot.html) （別名 Get-RSClusterSnapshots) + [Get-RSEvent](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-RSEvent.html) （別名 Get-RSEvents) + [Copy-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Copy-S3Object.html) + [Read-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Read-S3Object.html) + [Get-S3ObjectMetadata](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-S3ObjectMetadata.html) + [Send-SESBounce](https://docs.aws.amazon.com/powershell/v5/reference/items/Send-SESBounce.html) + [Get-WDActivity](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-WDActivity.html) ## 管道和 `$AWSHistory` 在 V4 AWS Tools for PowerShell 之前的 版本中，引進`$AWSHistory`了一個名為 的工作階段變數，可維護 AWS cmdlet 調用的記錄，以及每次調用時收到的服務回應。 在 Tools for PowerShell 的 V4 中，此工作階段變數已棄用，有利於 `-Select *` 參數和引數，可用於傳回整個服務回應。`-Select *` 參數說明於 [管道、輸出和反覆運算](pstools-pipelines.md)。 在 Tools for PowerShell 的 V5 中，`$AWSHistory`工作階段變數已完全移除。因此， `Clear-AWSHistory`和 `Set-AWSHistoryConfiguration` cmdlet 也已移除。 ## `-PassThru` 參數 `-PassThru` 參數已移除。當 cmdlet 預設不會傳回任何輸出時，使用者可以使用 請求傳回的參數值`-Select ^ParameterName`。如需其他詳細資訊和範例，請參閱 [ V5 的 AWS Tools for PowerShell 部落格文章預覽 1](https://aws.amazon.com/blogs/developer/preview-1-of-aws-tools-for-powershell-v5/)。 ## 有些 DynamoDB cmdlet 已移動並重新命名 `Get-DDBStream` 和 `Get-DDBStreamList` cmdlet 已從 DynamoDBV2 模組移至名為 DynamoDBStreams 的新模組。它們也分別重新命名為 [Get-DDBSStream](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-DDBSStream.html) 和 [Get-DDBSStreamList](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-DDBSStreamList.html)。 ## 記錄敏感資訊 記錄行為已變更，因此潛在敏感資訊不太可能包含在 cmdlet 輸出中，尤其是在 CI/CD 情況下。如需如何還原至 V4 行為的詳細資訊和指示，請參閱 [記錄敏感資訊](additional-security-considerations.md#add-sec-cons-sensitive-logs)。 ## 憑證和設定檔解析 AWS Tools for PowerShell 已更新為在解析 cmdlet 的登入資料時使用特定環境變數：`AWS_PROFILE`、`AWS_SECRET_ACCESS_KEY`、 `AWS_ACCESS_KEY_ID`和 `AWS_SESSION_TOKEN`。此外，登入資料和設定檔的解析順序有一些變更。如需詳細資訊，請參閱[憑證和設定檔解析](creds-assign.md)。 ## 登入資料錯誤訊息 如果無法取得適當的登入資料， AWS Tools for PowerShell 會傳回的錯誤訊息已變更。 在工具的 v4 中，訊息類似如下： ``` Get-SFNExecutionList -Region us-west-2 Get-SFNExecutionList: No credentials specified or obtained from persisted/shell defaults. ``` 在工具的 V5 中，訊息與以下內容類似： ``` Get-SFNExecutionList -Region us-west-2 Get-SFNExecutionList: Failed to resolve AWS credentials. The credential providers used to search for credentials returned the following errors: ... ``` ## 一致的自動反覆運算 根據預設，所有分頁 cmdlet 都已更新為自動重複所有資料。您可以使用 [Set-AWSAutoIterationMode](https://docs.aws.amazon.com/powershell/v5/reference/items/Set-AWSAutoIterationMode.html) cmdlet 還原此行為。如果您執行 `Set-AWSAutoIterationMode -IterationMode v4`，在 v4 中自動反覆運算的操作仍會自動反覆運算，但其餘操作則會還原為手動反覆運算。若要判斷自動反覆運算設定為何種模式，請使用 [Get-AWSAutoIterationMode](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-AWSAutoIterationMode.html) cmdlet。 若要查看以這種方式更新的 cmdlet 範例，請參閱 `Get-CWLLogEvent` cmdlet ([V4 cmdlet](https://docs.aws.amazon.com/powershell/v4/reference/index.html?page=Get-CWLLogEvent.html&tocid=Get-CWLLogEvent) 和 [V5 cmdlet](https://docs.aws.amazon.com/powershell/v5/reference/index.html?page=Get-CWLLogEvent.html&tocid=Get-CWLLogEvent))。 如需自動反覆運算的詳細資訊，請參閱 [透過分頁資料反覆運算](pstools-pipelines.md#pstools-iteration)。 ## S3 cmdlet 已棄用並取代 對於 Amazon S3，[Get-S3ACL](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-S3ACL.html) 和 [Set-S3ACL](https://docs.aws.amazon.com/powershell/v5/reference/items/Set-S3ACL.html) cmdlet 已棄用。請改用下列新的 cmdlet：[Get-S3BucketACL](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-S3BucketACL.html)、[Set-S3BucketACL](https://docs.aws.amazon.com/powershell/v5/reference/items/Set-S3BucketACL.html)、[Get-S3ObjectACL](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-S3ObjectACL.html)、[Set-S3ObjectACL](https://docs.aws.amazon.com/powershell/v5/reference/items/Set-S3ObjectACL.html)。 ## 清理和修剪 S3 金鑰參數 某些 Amazon S3 cmdlet 接受名為 `Key`和 的參數`KeyPrefix`。的 V4 AWS Tools for PowerShell 會以下列方式清理和修剪這些參數：移除前導空格、斜線 ("/") 和反斜線 ("\$1")、將所有其他斜線轉換為前導斜線，以及移除後導空格。在 Tools for PowerShell 的 V5 中，這不再是預設行為。您可以透過指定 `-EnableLegacyKeyCleaning` 參數來還原至此行為。 此資訊適用於下列 cmdlet： + [Copy-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Copy-S3Object.html) + [Get-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-S3Object.html) + [Get-S3ObjectV2](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-S3ObjectV2.html) + [Read-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Read-S3Object.html) + [Remove-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Remove-S3Object.html) + [Set-S3ACL](https://docs.aws.amazon.com/powershell/v5/reference/items/Set-S3ACL.html) + [Write-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Write-S3Object.html) ## 互動式工作階段功能 互動式工作階段功能已新增至 [Start-SSMSession](https://docs.aws.amazon.com/powershell/v5/reference/items/Start-SSMSession.html) Cmdlet，這符合 AWS CLI 行為。例如： ``` Start-SSMSession -Target 'i-1234567890abcdef0' ``` 如果您需要舊版行為，請在 `Start-SSMSession`命令中包含 `-DisablePluginInvocation` 參數。 ## CloudWatch 警示 [Get-CWAlarm](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-CWAlarm.html) cmdlet 已更新，預設會傳回指標和複合 Amazon CloudWatch 警示。若要將輸出限制為指標或複合警示，您必須`Get-CWAlarm -AlarmType 'CompositeAlarms'`分別指定 `-AlarmType` 參數： `Get-CWAlarm -AlarmType 'MetricAlarms'`或 。 ## `LitJson` AWS Tools for PowerShell 已更新為使用 `System.Text.Json`而非`LitJson`序列化。 `LitJson` 已從 V5 工具中移除。 ## `LoggedAt` 輸出屬性 `LoggedAt` 輸出屬性已移除。在工具的 V4 中，此屬性預設為在某些 cmdlet 上傳回 （例如 `Get-SSMCommandInvocationDetail`和 `Invoke-LMFunction`)。 如果您需要複寫`LoggedAt`輸出屬性提供的資訊，您可以在指令碼中包含類似以下內容的內容： ``` $loggedAt = (Get-Date).ToUniversalTime().ToString('s') ``` ## 已移除的程式設計元素 已從 Tools for PowerShell 的 V5 中移除許多程式設計元素。如果先前尚未涵蓋這些項目，以及您可以採取以適應其移除的潛在步驟，則會列出如下。 + `Invoke-LMFunctionAsync` Cmdlet。 + `Get-EC2ImageByName` Cmdlet。請改用 [Get-SSMLatestEC2Image](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-SSMLatestEC2Image.html) cmdlet。 + 來自 [Write-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Write-S3Object.html) cmdlet 的 `CalculateContentMD5Header` 參數。