のバージョン 5 (V5) AWS Tools for PowerShell がリリースされました。

新しいバージョンのツールの使用を開始するには、「AWS Tools for PowerShell ユーザーガイド (V5)」、特に V5 への移行に関するトピックを参照してください。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS Tools for PowerShell でのパイプライン処理、出力、イテレーション

パイプライン処理

PowerShell では、パイプラインを使用して、あるコマンドレットの出力を次のコマンドレットの入力に渡すことをお勧めします。次の例では、AWS Tools for PowerShell を使用した場合のこの動作を示しています。このコマンドは、現在のデフォルトリージョンにあるすべての Amazon EC2 インスタンスを取得した後、停止します。

PS > Get-EC2Instance | Stop-EC2Instance

コマンドレットの出力

パイプライン処理をより適切にサポートするために、AWS SDK for .NET のレスポンスから一部のデータがデフォルトで破棄される場合があります。AWS Tools for PowerShell コマンドレットの出力は、サービスレスポンスや結果インスタンスを出力コレクションオブジェクトの Note プロパティとして含めるようには整形されません。代わりに、出力として単一のコレクションを送信する呼び出しについては、コレクションが PowerShell パイプラインに列挙されるようになりました。この仕様により、SDK のレスポンスや結果データはパイプラインには存在しなくなります。それらのアタッチ先となるコレクションオブジェクトが存在しないためです。

ほとんどのユーザーにとって、このデータは不要かもしれませんが、診断目的には役立つ場合があります。コマンドレットによって基になる AWS サービスの呼び出しで送受信された内容を正確に確認できるためです。AWS Tools for PowerShell V4 以降、コマンドレットでは -Select * パラメータと引数を使用してサービスレスポンス全体を返すことができます。

レスポンスからすべてのデータを返す方法については、次の例を参照してください。

最初の例は、単に 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

2 つ目の例は、AWS SDK for .NET レスポンスオブジェクトを返します。-Select * を指定しているため、出力には API レスポンス全体が含まれ、その中の Buckets プロパティにバケットのコレクションが含まれています。この例では、Format-List コマンドレットは厳密には不要ですが、すべてのプロパティを確実に表示するために使用されています。

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

ページ分割されたデータのイテレーション

以降のセクションでは、可能なさまざまなタイプのイテレーションについて説明します。

自動イテレーション

1 回の呼び出しで返されるオブジェクト数にデフォルトの上限があるサービス API や、ページ分割可能な結果セットをサポートする API の場合、ほとんどのコマンドレットは自動イテレーションを実装しており、「完了するまでページ分割する」というデフォルト動作が有効になっています。このシナリオでは、コマンドレットがユーザーに代わって必要な回数だけ呼び出しを行い、完全なデータセットをパイプラインに返します。

次の例では Get-S3Object コマンドレットを使用しています。$result 変数には amzn-s3-demo-bucket1 バケット内のすべてのキーに対応する S3Object インスタンスが格納されますが、この変数は非常に大きなデータセットになる可能性があります。

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

次の例では、自動イテレーション時の 1 ページあたりの結果数を、デフォルトの 1000 件から 500 件に減らしています。1 回の呼び出しで返される結果数が半分になるため、この例では自動イテレーションの呼び出し回数が 2 倍になります。

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

自動イテレーションを無効にする

Tools for PowerShell でデータの最初のページのみを返すには、-NoAutoIteration パラメータを追加して、2 ページ目以降のデータが返されないようにします。

次の例では、-NoAutoIteration および -MaxKey パラメータを使用して、返される S3Object インスタンスの数を、バケット内で最初に見つかった 500 個以下に制限しています。

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

未取得のデータが残っているかどうかを判断するには、-Select * パラメータと引数を使用して、次のトークンプロパティに値があるか確認します。

次の例では、バケットに 500 個を超えるオブジェクトがある場合は $true を、それ以外の場合は $false を返します。

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

手動イテレーション

次の例では、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 の スプラッティング (splatting) を使用しています。