管道傳輸和 $AWSHistory

針對傳回集合的 AWS 服務呼叫，集合內的物件會列舉到管道。包含集合以外欄位以及不是分頁控制欄位的結果物件，會將這些欄位新增為呼叫的 Note 屬性。如果您需要存取這些資料，這些 Note 屬性記錄在新的 $AWSHistory 工作階段變數中。下一節會說明 $AWSHistory 變數。

注意

在 v1.1 之前的 Tools for Windows PowerShell 版本中，會發出集合物件本身，這需要使用 foreach {$_.getenumerator()} 來繼續管道輸送。

範例

下列範例會傳回 AWS 區域和每個區域中您 Amazon EC2 機器映像 (AMI) 的清單。

PS > Get-AWSRegion | % { Echo $_.Name; Get-EC2Image -Owner self -Region $_ }

下列範例會停止目前預設區域中的所有 Amazon EC2 執行個體。

PS > Get-EC2Instance | Stop-EC2Instance

由於集合會列舉到管道，所以指定 cmdlet 的輸出可能會是 $null、單一物件或集合。如果是集合，您可以使用 .Count 屬性來判斷集合的大小。不過，僅發出單一物件時，.Count 屬性不存在。如果您的指令碼需要以一致的方法判斷發出多少物件，您可在 $AWSHistory 中檢查最後一個命令值的 EmittedObjectsCount 屬性。

$AWSHistory

為提供管道傳輸更好的支援，從 AWS cmdlet 的輸出不會重新改造為包含服務回應和結果執行個體，做為發出集合物件的 Note 屬性。而是改為對於發出單一集合做為輸出的這些呼叫，現在將集合列舉到 PowerShell 管道。這表示 AWS 開發套件回應和結果資料無法存在於管道中，因為沒有可連接的包含集合物件。

雖然大多數使用者可能不需要此資料，但它可用於診斷目的，因為您可以查看 cmdlet 所進行基礎 AWS 服務呼叫已傳送和已接收的確實內容。

從版本 1.1 起，名為 $AWSHistory 的新 shell 變數現在提供此項資料及更多資料。此變數維護 AWS cmdlet 叫用的記錄以及每個叫用收到的服務回應。或者，這個歷史記錄也可以設定為記錄每個 cmdlet 記錄所進行的服務請求。另外也可以從每個項目取得其他有用資料，例如 cmdlet 整體執行時間。基於安全理由，預設情況下不會記錄包含敏感資料的請求和回應。但是，如果需要的話，可以設定歷史記錄以覆寫此行為。如需詳細資訊，請參閱下方顯示的 Set-AWSHistoryConfiguration Cmdlet。

$AWSHistory.Commands 清單中的每個項目都是 AWSCmdletHistory 類型。此類型有下列有用的成員：

CmdletName

Cmdlet 的名稱。

CmdletStart

Cmdlet 執行的日期時間。

CmdletEnd

Cmdlet 完成所有處理的日期時間。

請求

如果啟用請求記錄，此為最後服務請求清單。

回應

收到的最後服務回應清單。

LastServiceResponse

傳回最新服務回應的 Helper。

LastServiceRequest

傳回最新服務回應的小幫手 (如有)。

請注意，直到使用進行服務呼叫的 AWS cmdlet，$AWSHistory 變數才會建立。在該時間之前，它會判斷值為 $null。

注意

舊版 Tools for Windows PowerShell 將服務回應的相關資料發出為傳回物件的 Note 屬性。這些項目現在可在清單中為每個叫用記錄的回應項目中找到。

Set-AWSHistoryConfiguration

Cmdlet 呼叫可以保留零或多個服務請求和回應項目。為了降低對記憶體的影響，預設情況下 $AWSHistory 清單僅保留最後五個 cmdlet 執行的記錄，以及對於每個記錄的最後五個服務回應 (若啟用，則也包含最後五個服務請求)。您可以執行 Set-AWSHistoryConfiguration cmdlet 來變更這些預設限制。這可讓您同時控制清單大小，以及是否記錄服務請求：

PS > Set-AWSHistoryConfiguration -MaxCmdletHistory <value> -MaxServiceCallHistory <value> -RecordServiceRequests -IncludeSensitiveData

所有參數都是選用的。

MaxCmdletHistory 參數設定隨時可追蹤的 cmdlet 數量上限。0 值會關閉記錄 AWS cmdlet 活動。MaxServiceCallHistory 參數設定針對每個 cmdlet 追蹤的服務回應 (和/或請求) 數量上限。RecordServiceRequests 參數 (如果指定) 會開啟追蹤每個 cmdlet 的服務請求。如果指定 IncludeSensitiveData 參數，則會開啟追蹤包含每個 Cmdlet 之敏感資料的服務回應和請求 (如果已追蹤)。

如果不使用參數執行，Set-AWSHistoryConfiguration 會單純關閉任何之前的請求記錄，將目前清單大小保持不變。

若要清除目前歷史記錄清單中的所有項目，請執行 Clear-AWSHistory cmdlet。

$AWSHistory 範例

列舉管道清單中保留的 AWS cmdlet 詳細資訊。

PS > $AWSHistory.Commands

存取最後一個執行的 AWS cmdlet 詳細資訊：

PS > $AWSHistory.LastCommand

存取最後一個執行 AWS cmdlet 所收到最後服務回應的詳細資訊。如果 AWS cmdlet 是分頁輸出，它可能會進行多個服務呼叫以取得所有資料或最大資料量 (取決於 cmdlet 的參數)。

PS > $AWSHistory.LastServiceResponse

存取最後發出請求的詳細資訊 (同樣的，如果代表使用者進行分頁，cmdlet 可能會進行多次請求)。除非服務請求追蹤已啟用，否則會產生 $null。

PS > $AWSHistory.LastServiceRequest

對於傳回多個頁面的作業，自動為分頁到完成

對於特定呼叫施行預設最大物件傳回計數或支援可分頁結果集的服務 API，所有 cmdlet 預設為「分頁到完成」(page-to-completion)。每個 cmdlet 會代表您進行所需數量的呼叫，以傳回完整資料集至管道。

在使用 Get-S3Object 的下列範例中，$c 變數包含儲存貯體 test 中每個金鑰的 S3Object 執行個體，可能會是非常大的資料集。

PS > $c = Get-S3Object -BucketName test

如果您想要保有對傳回資料量的控制權，您可以使用個別 cmdlet 上的參數 (例如 Get-S3Object 上的 MaxKey)，或者您也可以使用 cmdlet 的分頁參數組合以及 $AWSHistory 變數中存放的資料來取得服務的後續字符資料，以明確地自行處理分頁。以下範例使用 MaxKeys 參數，限制傳回的 S3Object 執行個體數量為不超過儲存貯體中找到的前 500 個。

PS > $c = Get-S3Object -BucketName test -MaxKey 500

若要知道是否有更多可用資料但不傳回這些資料，請使用記錄 cmdlet 所進行服務呼叫的 $AWSHistory 工作階段變數項目。

如果以下表達式判斷值為 $true，您可以使用 $AWSHistory.LastServiceResponse.NextMarker 找到下一個結果集的 next 標記。

$AWSHistory.LastServiceResponse -ne $null && $AWSHistory.LastServiceResponse.IsTruncated

若要使用 Get-S3Object 手動控制分頁，請搭配使用 cmdlet 的 MaxKey 與 Marker 參數，以及最後一個記錄回應的 IsTruncated/NextMarker 備註。在下列範例中，變數 $c 包含在指定的金鑰前綴標記開始之後，在儲存貯體中找到的下 500 個物件的最多 500 個 S3Object 執行個體。

PS > $c = Get-S3Object -BucketName test -MaxKey 500 -Marker $AWSHistory.LastServiceResponse.NextMarker