中的管道、輸出和反覆運算 AWS Tools for PowerShell - AWS Tools for PowerShell （第 4 版）
管道Cmdlet 輸出透過分頁資料反覆運算

第 5 版 (V5) AWS Tools for PowerShell 已發行！

若要開始使用新版本的工具，請參閱 AWS Tools for PowerShell 使用者指南 (V5)，特別是遷移至 V5 的主題。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

中的管道、輸出和反覆運算 AWS Tools for PowerShell

管道

PowerShell 鼓勵使用者將 cmdlet 連接到管道，將一個 cmdlet 的輸出引導至下一個 cmdlet 的輸入。下列範例顯示使用 時的此行為 AWS Tools for PowerShell。命令會取得並停止目前預設區域中的所有 Amazon EC2 執行個體。

PS > Get-EC2Instance | Stop-EC2Instance

Cmdlet 輸出

為了更好地支援管道，預設 適用於 .NET 的 AWS SDK 可能會捨棄來自 回應的一些資料。 AWS Tools for PowerShell Cmdlet 的輸出不會重塑，以包含服務回應和結果執行個體做為所發出集合物件上的Note屬性。而是改為對於發出單一集合做為輸出的這些呼叫，現在將集合列舉到 PowerShell 管道。這表示 SDK 回應和結果資料不能存在於管道中，因為沒有包含可附加的集合物件。

雖然大多數使用者可能不需要此資料，但它對於診斷用途很有用，因為您可以查看 Cmdlet 發出的基礎 AWS 服務呼叫傳送和接收的內容。從 AWS Tools for PowerShell V4 開始，Cmdlet 可以使用 -Select * 參數和引數傳回整個服務回應。

注意

在 V4 AWS Tools for PowerShell 之前的 版本中，$AWSHistory引進了一個名為 的工作階段變數，可維護 AWS cmdlet 調用的記錄以及每次調用收到的服務回應。在 Tools for PowerShell 的 V4 中，此工作階段變數已棄用，有利於 -Select * 參數和引數，可用於傳回整個服務回應。本主題說明此參數。

注意

這是預覽版本之服務的發行前版本文件。內容可能變動。

$AWSHistory 變數將在 的 V5 中移除 AWS Tools for PowerShell。如需詳細資訊，請參閱部落格文章關於即將推出 AWS 的 Tools for PowerShell 主要版本 5 的通知。

若要說明如何傳回回應中的所有資料，請考慮下列範例。

第一個範例只會傳回 Amazon S3 儲存貯體的清單。這是預設行為。

PS > Get-S3Bucket

CreationDate           BucketName
------------           ----------
9/22/2023 10:54:35 PM  amzn-s3-demo-bucket1
9/22/2023 11:04:37 AM  amzn-s3-demo-bucket2
9/22/2023 12:54:34 PM  amzn-s3-demo-bucket3

第二個範例會傳回 適用於 .NET 的 AWS SDK 回應物件。因為 -Select * 已指定，所以輸出會包含整個 API 回應，其中包含 Buckets 屬性中的儲存貯體集合。在此範例中，Format-ListCmdlet 並非絕對必要，但存在以確保顯示所有屬性。

PS > Get-S3Bucket -Select * | Format-List

LoggedAt          : 10/1/2023 9:45:52 AM
Buckets           : {amzn-s3-demo-bucket1, amzn-s3-demo-bucket2,
                    amzn-s3-demo-bucket3}
Owner             : Amazon.S3.Model.Owner
ContinuationToken :
ResponseMetadata  : Amazon.Runtime.ResponseMetadata
ContentLength     : 0
HttpStatusCode    : OK

透過分頁資料反覆運算

下列各節說明各種可能的反覆運算類型。

自動反覆運算

對於對指定呼叫或支援可分頁結果集施加預設最大傳回物件數量的服務 APIs，大多數 cmdlet 會實作自動反覆運算，這會啟用預設行為 "page-to-completion"。在此案例中，Cmdlet 會代表您進行任意數量的呼叫，將完整的資料集傳回管道。

在下列使用 Get-S3Object cmdlet 的範例中，$result變數包含名為 之儲存貯體中每個金鑰的S3Object執行個體amzn-s3-demo-bucket1，這可能是非常大型的資料集。

PS > $result = Get-S3Object -BucketName amzn-s3-demo-bucket1

下列範例會將自動反覆運算期間每個頁面的結果數目，從預設值 1000 減少為 500。此範例會執行兩倍的自動重複呼叫，因為每次呼叫只會傳回一半的結果。

PS > $result = Get-S3Object -BucketName amzn-s3-demo-bucket1 -MaxKey 500
注意

在 AWS Tools for PowerShell V4 中，某些分頁操作的 cmdlet 不會實作自動反覆運算。如果 cmdlet 沒有 -NoAutoIteration 參數，將在下一節中討論，則不會實作自動反覆運算。

停用自動反覆運算

如果您希望 Tools for PowerShell 僅傳回資料第一頁，您可以新增 -NoAutoIteration 參數，以防止傳回其他頁面的資料。

下列範例使用 -NoAutoIteration和 -MaxKey 參數，將傳回的S3Object執行個體數量限制為不超過儲存貯體中找到的前 500 個執行個體。

PS > $result = Get-S3Object -BucketName amzn-s3-demo-bucket1 -MaxKey 500 -NoAutoIteration

若要判斷是否有更多可用但未傳回的資料，請使用 -Select * 參數和引數，並檢查下一個權杖屬性中是否有值。

$true 如果儲存貯體中有 500 個以上的物件，$false則以下範例會傳回 。

PS > $result = Get-S3Object -BucketName amzn-s3-demo-bucket1 -MaxKey 500 -NoAutoIteration -Select *
PS > $null -eq $result.NextMarker
注意

下一個權杖回應屬性和 cmdlet 參數的名稱會因 cmdlet 而異。如需詳細資訊，請參閱每個 cmdlet 的說明文件。

手動反覆運算

下列範例使用 do 迴圈傳回儲存貯體中的所有 S3 物件，它會在每次反覆運算後評估條件。do 迴圈會執行反覆運算，直到 Get-S3Object $result.NextMarker設定為 $null為止，表示不再有分頁資料。迴圈的輸出會指派給 $s3Objects變數。

$s3Objects = do
{
    $splatParams = @{
        BucketName = 'amzn-s3-demo-bucket1'
        MaxKey = 500 
        Marker = $result.NextMarker 
        NoAutoIteration = $true
        Select = '*'
    }
    $result = Get-S3Object @splatParams
    
    $result.S3Objects
}
while ($null -ne $result.NextMarker)

此範例使用 PowerShell 潑濺，以避免因為內嵌宣告參數和引數而造成的長行程式碼。