AWS Tools for PowerShell 4.0がリリースされました

しばたです。
ちょっと前の話なのですが、AWS Tools for PowerShellのメジャーバージョンアップであるVer.4.0がリリースされました。
AWS Developer Blogでも以下の記事で紹介されています。

https://aws.amazon.com/jp/blogs/developer/aws-tools-for-powershell-is-now-generally-available-with-version-4-0/

本記事ではAWS Developer Blogの記事を参考にしつつ、実際にAWS Tools for PowerShell 4.0を試してその内容を解説していきます。

AWS Tools for PowerShell 4.0 の入手方法

以前にDevelopers.IOでAWS Tools for PowerShellのモジュール構成が変更されてる件をお伝えしました。

https://dev.classmethod.jp/server-side/preview-release-of-new-aws-tools-for-powershell/

AWS Tools for PowerShell 4.0ではこちらが正式リリースとなり、

• AWS.Tools.[各サービス名]

となるモジュールとして提供されています。
各サービスの共通部分である、AWS.Tools.Commonをベースに必要なサービスの分だけ自分でモジュールをインストールする形となっており、例えばEC2を扱いたい場合はAWS.Tools.EC2モジュールをインストールする必要があります。

Install-Module -Name AWS.Tools.EC2

ただ、従来のAWSPowerShellモジュールやAWSPowerShell.NetCoreモジュールも同時に更新されており、しばらくは3種類のモジュールが利用可能な状態が続くでしょう。
従来のモジュールの今後については現時点では特に明言されていません。

AWS.Tools.Installer モジュール

AWS.Tools.*なモジュールはAWSサービス毎にモジュールが分割され依存関係ができたため従来のモジュール比べ更新作業が煩雑になります。
このためAWS Tools for PowerShell 4.0ではインストールの補助を行うAWS.Tools.Installerモジュールが追加でリリースされました。
このモジュールはPowerShell Galleryからインストールできます。

Install-Module -Name AWS.Tools.Installer

モジュールで公開されているコマンドレットは以下の3つとなります。

C:\> Get-Command -Module AWS.Tools.Installer                                                                            
CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Function        Install-AWSToolsModule                             1.0.0.1    AWS.Tools.Installer
Function        Uninstall-AWSToolsModule                           1.0.0.1    AWS.Tools.Installer
Function        Update-AWSToolsModule                              1.0.0.1    AWS.Tools.Installer

本記事ではこの細かい使い方までは解説しませんが、AWS Developer Blogで紹介されている例を引用すると、以下の様にすると古いバージョンのモジュールを削除し、 EC2, S3 用の最新モジュールをインストールしてくれます。

# 古いバージョンのモジュールを削除し、 EC2, S3 用の最新モジュールをインストール
Install-AWSToolsModule AWS.Tools.EC2, AWS.Tools.S3 -CleanUp

最初に紹介した方法ではなくこのモジュールを使ってインストールするのがおすすめです。
もちろんインストール時だけでなく更新時もよしなに処理してくれる便利なやつです。

対応プラットフォーム

この3種類のモジュールは歴史的経緯もあるため対応プラットフォームが微妙に異なります。
ざっとまとめると以下の様になります。

AWS Developer BlogによればAWSPowerShellはレガシーサポート向けに残しつつもAWS.Tools.*への移行を図っている様です。
特段の事情がない限りは極力AWS.Tools.*なモジュールを使う様にすると良いと思います。

新機能

AWS Tools for PowerShell 4.0は過去バージョン(Ver.3系)との互換性を重視しているため機能的にはそこまでドラスティックな変更点はありません。

モジュールロード時間、メモリ使用量の改善

AWS Tools for PowerShell 4.0のAWS.Tools.*なモジュールではこれまでの巨大な単体モジュールからサービス毎のモジュールに分割されたため、メモリ使用量やロード時間が改善されています。
以前解説したモジュールの自動ロードに関する問題も解消されています。

-Select パラメーター

モジュール内の共通パラメーターに-Selectパラメーターが追加されました。
これはコマンドレットで取得したオブジェクトに対して特定のプロパティのみ取得するパラメーターとなり、例えば、従来

# Get-EC2Instance は Reservation オブジェクトを返し、インスタンス情報を取得するにはさらに Instances プロパティを見る必要がある
Get-EC2Instance | Select-Object Instances 

の様にしていたのが

# -Select パラメーターで取得するオブジェクトを調整できる
Get-EC2Instance -Select Reservations.Instances 

の様に記述することができます。

構文は異なりますがAWS CLIの--queryパラメーターに近いものと考えるとわかりやすいでしょう。

必須パラメーター

AWS.Tools.*なモジュールでは必須パラメーターの挙動が改善されました。
AWS Developers Blogに記載されている例を引用すると、Get-EC2InstanceAttributeで-InstanceIdパラメーターを指定しなかった際に、従来は直ちにエラーとなるのがAWS.Tools.EC2モジュールでは入力プロンプトが表示される様になっています。

# AWS.Tools.EC2 モジュールでは入力必須の InstanceId パラメーターの入力が促される
Get-EC2InstanceAttribute -Attribute instanceType -Select InstanceAttribute.InstanceType

(AWS Tools for PowerShell 4.0では InstanceId パラメーターの入力が促される)

(従来のバージョンでは直ちにパラメーター未指定のエラーとなる)

また、この変更によるエンバグや新たな不具合を防ぐために必須パラメーターに$nullを指定した場合は警告メッセージを表示し、不具合が出る場合はGitHubのリポジトリにIssueを上げる様に促してくれます。

# 必須パラメーターである -InstanceId と -Attribute に $null を指定する例
Get-EC2InstanceAttribute -InstanceId $null -Attribute $null

なお、互換性を考慮してVer.4.0以降のモジュールでもAWSPowerShellおよびAWSPowerShell.NetCoreモジュールではこの変更は入っていません。

オブジェクト列挙の改善

AWS.Tools.*なモジュールではオブジェクト列挙の自動ページネーションがサポートされ、従来からある-MaxItemsパラメーターを指定した際の挙動が変わりました。
例えばこれまで、

# AWS Tools for PowerShell 4.0 では自動ページネーションがサポートされる
# -MaxItems は1どのページ処理における最大取得数となり、
# 下記の例だと 2 オブジェクトずつオブジェクトの取得を試みる
Get-S3Object -BucketName 'Your backet name' -MaxItems 2

の様に書いていた処理はSelect-Objectを使い、

Get-S3Object -BucketName 'Your backet name' | Select-Object -First 2

の様に書く必要があります。
なお、-MaxItemsパラメーターは処理全体での最大取得数から一度のページ処理における最大取得数に意味が変わっています。

この変更の経緯はプレビュー版リリース時のアナウンスに詳細が記載されており、

• サービスによっては取得最大数を保証できない場合があった
• サービスにによっては-MaxItems 1といった少ない値を指定するとエラーになる場合があった
• すべてサービスで-MaxItemパラメーターがサポートされているわけではない
• 新しく導入した-Selectパラメーターと-MaxItemパラメーター組み合わせが混乱しやすい

といった理由から変更に至ったとのことです。
自動ページネーションをしたくない場合は-NoAutoPaginationパラメーターを付けることで従来の挙動と同じになる様です。

# -NoAutoPagination パラメーターにより、最大2オブジェクトの取得を一回のみ行う
Get-S3Object -BucketName 'Your backet name' -MaxItems 2 -NoAutoPagination

Get-AWSService

AWSサービス検索のためGet-AWSServiceコマンドレットが追加されました。

Stream型、Byte[]型パラメーターの改善

型定義がStreamやbyte[]となっているパラメーターで、string、string[]、FileInfo型を受け入れる様に改善されました。
文字列はUTF-8のバイトストリームに変換され引き渡されます。

AWS Developer Blogの例を引用するとInvoke-LMFunctionコマンドレットの-PayloadStreamパラメーターはbyte[]型定義ですが、以下の様にJSON文字列やその配列、JSONファイルオブジェクトを指定してやることが可能になりました。

# -PayloadStream パラメーターに文字列を指定
Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream '{
  "some": "json"
}'
# 文字列の配列も可
Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream @('{', '"some": "json"', '}')

# -PayloadStream パラメーターにファイルオブジェクトを指定
Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream (dir .\file.json)

これは非常に便利な改善ですね。

プロパティ名でのパラメーターバインディングによるパイプ

ユーザーエクスペリエンスの一貫性をもたせるためにパイプラインでプロパティ名でのパラメーターバインディング(ByPropertyName)を可能にしています。
AWS Tools for PowerShell 4.0では以下の様なパイプラインが可能です。

# ByPropertyName Paramteter Binding が可能
[PSCustomObject]@{ BucketName='myBucket'; Key='file1.txt'; PartNumber=1 } | Get-S3ObjectMetadata

共通パラメーターの改善

これまでのバージョンでは-AccessKey、-SecretKey、-ProfileName、-Regionといった共通パラメーターがDynamicParameterとして定義されており、これにより一部のコマンドレットで問題が発生していました。
たとえばGet-EC2Regionコマンドレットで以下の処理を実行した場合、

Get-EC2Region -Region us-west-2

Get-EC2Regionには-RegionNameパラメーターも存在しておりDynamicParameterである-Regionパラメーターより先に解決されてしまいます。
このためこのコマンドは

# -Region が常に -RegionName と解釈されてしまう
Get-EC2Region -RegionName us-west-2

と解釈され本来意図した動作になりません。
このため問題が起きるコマンドレットにおいては共通パラメーターを通常のStaticなパラメーターに変更することで問題を解消しています。

この改善は以下のコマンドレットが対象となっています。

• Remove-IAMAccessKey、Get-IAMAccessKeyLastUsed、Update-IAMAccessKeyの-AccessKeyパラメーター
• New-AG2Integration、Update-AG2Integration、New-IOTRoleAlias、Update-IOTRoleAliasnの-Credentialパラメーター
• New-AGDomainName、Get-DDBGlobalTableList、Get-EC2Region、Get-RDSSourceRegion、Update-R53HealthCheckの-Regionパラメーター

削除された機能

AWS Tools for PowerShell 4.0では以下の機能が削除されています。

• Stop-EC2Instanceから-Terminateパラメーターが削除されました。
  • Stop-EC2Instanceの代わりにRemove-EC2Instanceを使います
• Clear-AWSCredentialから-ProfileNameパラメーターが削除されました。
  • Clear-AWSCredentialの代わりにRemove-AWSCredentialProfileを使います
• Import-EC2InstanceとImport-EC2Volumeコマンドレットが削除されました。
• ドキュメント化されていない幾つかの拡張パラメーターが廃止されました

PowerShell 2.0サポート終了に関して

2020年1月にWindows Server 2008 R2のEOLを迎えますが、それに合わせる形でPowerShell 2.0をサポートするAWSPowerShellモジュールの新規リリースを止めるとの事です。具体的な時期については明言されていません。
従来のPowershell 2.0をサポートするモジュールはPowerShell Galleryから入手可能にしておくそうです。

完全なソース公開

これまでAWS Tools for PowerShellのGitHubリポジトリではリリース履歴とIssue管理のみ行われてきたのですが、AWS Tools for PowerShell 4.0にリリースに合わせて遂にソースコードがApache Licnese version 2のもと公開されました。

最高ですね！

最後に

以上がAWS Tools for PowerShell 4.0の更新内容となります。

最初に触れた通り従来のバージョンとの互換性を重視した更新となっていますので導入へのハードルもそこまで高くないと思います。
便利な機能も増えてますので隙あらば新しいバージョンを試していくのが良いでしょう。