AWS Tools for PowerShell 버전 3.3에서 버전 4로 마이그레이션

AWS Tools for PowerShell 버전 4는 AWS Tools for PowerShell 3.3의 이전 버전과 호환되는 업데이트입니다. 기존 cmdlet 동작을 유지하면서 기능이 상당히 향상되었습니다.

새 버전으로 업그레이드한 후에도 기존 스크립트가 계속 작동하지만 프로덕션 환경을 업그레이드하기 전에 철저히 테스트하는 것이 좋습니다.

이 단원에서는 변경 사항에 대해 설명하고 이러한 변경 사항이 스크립트에 어떤 영향을 미칠 수 있는지에 대해 다룹니다.

새롭게 완전 모듈화된 AWS.Tools 버전

그 AWSPowerShell. NetCore 그리고 AWSPowerShell 패키지는 “모놀리식”이었습니다. 즉, 모든 AWS 서비스가 동일한 모듈에서 지원되었으며, 이로 인해 규모가 매우 커지고 각각의 새로운 AWS 서비스 및 기능이 추가될 때마다 규모가 점점 커졌습니다. 새 AWS.Tools 패키지는 소형 모듈로 분할되므로 사용 중인 AWS 서비스에 필요한 모듈만 다운로드하고 설치할 수 있는 유연성을 제공합니다. 패키지에는 다른 모든 모듈에서 필요로 하는 공유 AWS.Tools.Common 모듈과 필요에 따라 모듈의 설치, 업데이트 및 제거를 간소화하는 AWS.Tools.Installer 모듈이 포함되어 있습니다.

또한 Import-module을 우선 호출하지 않고도 첫 번째 호출 시 cmdlet을 자동으로 가져올 수 있습니다. 하지만 cmdlet을 호출하기 전에 연관된.NET 개체와 상호 작용하려면 여전히 관련 .NET 유형을 PowerShell 알리기 Import-Module 위해 호출해야 합니다.

예를 들어 다음 명령에는 Amazon.EC2.Model.Filter에 대한 참조가 있습니다. 이 유형의 참조는 자동 가져오기를 트리거할 수 없으므로 우선 Import-Module을 호출해야 합니다. 그렇지 않으면 명령이 실패합니다.

PS > $filter = [Amazon.EC2.Model.Filter]@{Name="vpc-id";Values="vpc-1234abcd"}
  InvalidOperation: Unable to find type [Amazon.EC2.Model.Filter].

PS > Import-Module AWS.Tools.EC2
PS > $filter = [Amazon.EC2.Model.Filter]@{Name="vpc-id";Values="vpc-1234abcd"}
PS > Get-EC2Instance -Filter $filter -Select Reservations.Instances.InstanceId
  i-0123456789abcdefg
  i-0123456789hijklmn

새로운 Get-AWSService cmdlet

모듈의 AWS.Tools 컬렉션에서 각 AWS 서비스에 대한 모듈 이름을 보다 수월하게 찾으려면 Get-AWSService cmdlet을 사용합니다.

PS > Get-AWSService
  Service : ACMPCA
  CmdletNounPrefix : PCA
  ModuleName : AWS.Tools.ACMPCA
  SDKAssemblyVersion : 3.3.101.56
  ServiceName : Certificate Manager Private Certificate Authority

  Service : AlexaForBusiness
  CmdletNounPrefix : ALXB
  ModuleName : AWS.Tools.AlexaForBusiness
  SDKAssemblyVersion : 3.3.106.26
  ServiceName : Alexa For Business
  ...

Cmdlet에서 반환된 객체를 제어하는 새로운 -Select 파라미터

버전 4에서 대부분의 cmdlet은 새로운 -Select 파라미터를 지원합니다. 각 cmdlet은 AWS SDK for .NET를 사용하여 AWS 서비스 API를 호출합니다. 그러면 AWS Tools for PowerShell 클라이언트가 응답을 PowerShell 스크립트에서 사용할 수 있는 개체로 변환하고 다른 명령으로 파이프합니다. 최종 PowerShell 개체의 원래 응답에 필요한 것보다 많은 필드나 속성이 있는 경우도 있고, 기본적으로 없는 응답의 필드나 속성을 개체에 포함해야 하는 경우도 있습니다. -Select 파라미터를 사용하면 cmdlet에서 반환된 .NET 객체에 포함시킬 사항을 지정할 수 있습니다.

예를 들어 Get-S3Object cmdlet은 Amazon S3 SDK 작업을 호출합니다. ListObjects ListObjectsResponse이 작업은 객체를 반환합니다. 하지만 기본적으로 Get-S3Object cmdlet은 SDK 응답의 S3Objects 요소만 사용자에게 반환합니다. PowerShell 다음 예제에서 이 객체는 2개 원소가 있는 배열입니다.

PS > Get-S3Object -BucketName mybucket

ETag : "01234567890123456789012345678901111"
BucketName : mybucket
Key : file1.txt
LastModified : 9/30/2019 1:31:40 PM
Owner : Amazon.S3.Model.Owner
Size : 568
StorageClass : STANDARD

ETag : "01234567890123456789012345678902222"
BucketName : mybucket
Key : file2.txt
LastModified : 7/15/2019 9:36:54 AM
Owner : Amazon.S3.Model.Owner
Size : 392
StorageClass : STANDARD

AWS Tools for PowerShell 버전 4에서는 SDK API 호출에 의해 반환된 완전한 .NET 응답 객체를 반환하도록 -Select *를 지정할 수 있습니다.

PS > Get-S3Object -BucketName mybucket -Select *
  IsTruncated    : False
  NextMarker     :
  S3Objects      : {file1.txt, file2.txt}
  Name           : mybucket
  Prefix         :
  MaxKeys        : 1000
  CommonPrefixes : {}
  Delimiter      :

또한 원하는 특정 중첩 속성에 대한 경로를 지정할 수도 있습니다. 다음 예제에서는 S3Objects 배열에 있는 각 원소의 Key 속성만 반환합니다.

PS > Get-S3Object -BucketName mybucket -Select S3Objects.Key
file1.txt
file2.txt

특정 상황에서는 cmdlet 파라미터를 반환하는 것이 유용할 수 있습니다. -Select ^ParameterName을 사용해 이 작업을 수행할 수 있습니다. 이 기능은 -PassThru 파라미터(여전히 사용 가능하지만 더 이상 사용되지 않음)를 대체합니다.

PS > Get-S3Object -BucketName mybucket -Select S3Objects.Key |
>> Write-S3ObjectTagSet -Select ^Key -BucketName mybucket -Tagging_TagSet @{ Key='key'; Value='value'}
  file1.txt
  file2.txt

각 cmdlet에 대한 참조 항목에서 -Select 파라미터를 지원하는지 여부를 식별합니다.

출력 항목 수에 대한 보다 일관된 제한

이전 버전의 AWS Tools for PowerShell에서는 -MaxItems 파라미터를 사용하여 최종 출력에서 반환되는 최대 객체 수를 지정할 수 있었습니다.

이 동작은 AWS.Tools에서 제거됩니다.

이 동작은 에서 더 이상 사용되지 않습니다. AWSPowerShell NetCore 및 AWSPowerShell 향후 릴리스에서 해당 버전에서 제거될 예정입니다.

기본 서비스 API가 MaxItems 파라미터를 지원하는 경우, 계속 사용할 수 있으며 API에서 지정한 대로 작동합니다. 하지만 cmdlet의 출력에서 반환되는 항목 수를 제한하는 동작을 더 이상 수행하지 않습니다.

최종 출력에서 반환되는 항목 수를 제한하려면 출력을 Select-Object cmdlet으로 파이핑하고 -First n 파라미터를 지정합니다. 여기서 n은 최종 출력에 포함할 최대 항목 수입니다.

PS > Get-S3ObjectV2 -BucketName BUCKET_NAME -Select S3Objects.Key | select -first 2
file1.txt
file2.txt

모든 AWS 서비스가 동일한 방식으로 -MaxItems를 지원하지는 않으므로, 가끔씩 발생하는 불일치와 예기치 않은 결과가 제거됩니다. 또한 -MaxItems가 새로운 -Select 파라미터와 결합되면 때때로 혼란스러운 결과가 발생할 수 있습니다.

더욱 사용하기 쉬워진 Stream 파라미터

Stream 또는 byte[] 유형의 파라미터는 이제 string, string[] 또는 FileInfo 값을 수락합니다.

예를 들어 다음 예제 중 하나를 사용할 수 있습니다.

PS > Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream '{
>> "some": "json"
>> }'

PS > Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream (ls .\some.json)

PS > Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream @('{', '"some": "json"', '}')

AWS Tools for PowerShell는 UTF-8 인코딩을 사용하여 모든 문자열을 byte[]로 변환합니다.

속성 이름별로 파이프 확장

이제 모든 파라미터에 대한 속성 이름을 지정하여 파이프라인 입력을 전달할 수 있으므로 보다 일관된 사용자 경험을 제공할 수 있습니다.

다음 예제에서는 대상 cmdlet의 파라미터 이름과 일치하는 이름을 가진 속성이 있는 사용자 지정 객체를 만듭니다. cmdlet이 실행되면 이러한 속성을 자동으로 해당 파라미터로 사용합니다.

PS > [pscustomobject] @{ BucketName='myBucket'; Key='file1.txt'; PartNumber=1 } | Get-S3ObjectMetadata

참고

일부 속성은 AWS Tools for PowerShell의 이전 버전에서 이 기능을 지원했었습니다. 버전 4에서는 모든 파라미터에 대해 이를 활성화함으로써 일관성을 개선했습니다.

정적 공통 파라미터

AWS Tools for PowerShell의 버전 4.0에서는 일관성을 개선하기 위해 모든 파라미터가 정적 파라미터입니다.

AWS Tools for PowerShell의 이전 버전에서는 AccessKey, SecretKey, ProfileName 또는 Region과 같은 일부 공통 파라미터는 동적 파라미터였고, 기타 모든 파라미터는 정적 파라미터였습니다. 이렇게 하면 정적 매개변수가 동적 매개변수보다 먼저 PowerShell 바인딩되므로 문제가 발생할 수 있습니다. 예를 들어 다음 명령을 실행했다고 가정해보겠습니다.

PS > Get-EC2Region -Region us-west-2

이전 버전의 에서는 -Region 동적 파라미터 대신 -RegionName 정적 us-west-2 파라미터에 값을 PowerShell 바인딩했습니다. 이러한 수행은 사용자를 혼란스럽게 할 수 있습니다.

AWS.Tools 필수 파라미터 선언 및 강제 시행

AWS.Tools.* 모듈은 이제 필수 cmdlet 파라미터를 선언하고 강제 시행합니다. AWS서비스에서 API의 매개 변수가 필요하다고 선언하면 해당 cmdlet 매개 변수를 지정하지 않은 경우 해당 cmdlet 매개 변수를 PowerShell 입력하라는 메시지가 표시됩니다. 이것은 AWS.Tools에만 적용됩니다. 이전 버전과의 호환성을 보장하기 위해 이 내용은 적용되지 않습니다. AWSPowerShell NetCore 또는 AWSPowerShell.

모든 파라미터에 Null 값 사용 가능

이제 값 유형 파라미터(숫자 및 날짜)에 $null을 지정할 수 있습니다. 이 변경 사항은 기존 스크립트에 영향을 주지 않습니다. 이렇게 하면 필수 파라미터에 대해 표시되는 메시지를 우회할 수 있습니다. 필수 파라미터는 AWS.Tools에서만 강제 시행됩니다.

버전 4를 사용하여 다음 예제를 실행하면 각 필수 파라미터에 “값”을 제공하기 때문에 클라이언트 측 검증을 실질적으로 우회할 수 있습니다. 하지만 AWS 서비스에서 여전히 해당 정보가 필요하기 때문에 Amazon EC2 API 서비스 호출이 실패합니다.

PS > Get-EC2InstanceAttribute -InstanceId $null -Attribute $null
WARNING: You are passing $null as a value for parameter Attribute which is marked as required.
In case you believe this parameter was incorrectly marked as required, report this by opening 
an issue at https://github.com/aws/aws-tools-for-powershell/issues.
WARNING: You are passing $null as a value for parameter InstanceId which is marked as required.
In case you believe this parameter was incorrectly marked as required, report this by opening
an issue at https://github.com/aws/aws-tools-for-powershell/issues.

Get-EC2InstanceAttribute : The request must contain the parameter instanceId

더 이상 사용되지 않는 기능 제거

다음 기능은 AWS Tools for PowerShell의 이전 릴리스에서 더 이상 사용되지 않으며 버전 4에서 제거되었습니다.

• Stop-EC2Instance cmdlet에서 -Terminate 파라미터가 제거되었습니다. 대신 Remove-EC2Instance을 사용하세요.

• Clear- AWSCredential cmdlet에서 -ProfileName 매개 변수를 제거했습니다. 대신 Remove-AWSCredentialProfile을 사용하세요.

• cmdlet Import-EC2Instance 및 Import-EC2Volume이 제거되었습니다.