A versão 5 (V5) do Ferramentas da AWS para PowerShell foi lançada!

Para começar a usar a nova versão do SDK, consulte o Guia do usuário do Ferramentas da AWS para PowerShell (V5), especialmente o tópico Migração para V5.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Migrar do Ferramentas da AWS para PowerShell versão 3.3 para a versão 4

O Ferramentas da AWS para PowerShell versão 4 é uma atualização compatível com versões anteriores para o Ferramentas da AWS para PowerShell versão 3.3. Ele adiciona melhorias significativas enquanto mantém o comportamento existente do cmdlet.

Os scripts existentes devem continuar a funcionar após a atualização para a nova versão, mas recomendamos que você os teste minuciosamente antes de atualizar os ambientes de produção.

Esta seção descreve as alterações e explica como elas podem impactar os scripts.

Nova versão totalmente modularizada do AWS.Tools

Os pacotes AWSPowerShell.NetCore e AWSPowerShell eram "monolíticos". Isso significava que todos os serviços da AWS eram compatíveis no mesmo módulo, tornando-o muito grande e aumentando a cada vez que um novo recurso e serviço da AWS era adicionado. O novo pacote AWS.Tools está dividido em módulos menores que oferecem a flexibilidade de fazer download e instalar somente aqueles exigidos para os serviços da AWS que você usa. O pacote inclui um módulo AWS.Tools.Common compartilhado que é exigido por todos os outros módulos e um módulo AWS.Tools.Installer que simplifica a instalação, a atualização e a remoção de módulos conforme necessário.

Isso também permite importar os cmdlets automaticamente na primeira chamada, sem precisar chamar primeiro Import-module. No entanto, para interagir com os objetos .NET associados antes de chamar um cmdlet, é necessário ainda chamar Import-Module para permitir que o PowerShell saiba sobre os tipos .NET relevantes.

Por exemplo, o comando a seguir tem uma referência a Amazon.EC2.Model.Filter. Esse tipo de referência não pode acionar a importação automática, portanto, é necessário chamar Import-Module primeiro ou o comando falhará.

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

Novo cmdlet Get-AWSService

Para ajudar a descobrir os nomes dos módulos para cada serviço da AWS na coleção de módulos do AWS.Tools, é possível usar o cmdlet Get-AWSService.

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
  ...

Novo parâmetro -Select para controlar o objeto retornado por um cmdlet

A maioria dos cmdlets na versão 4 oferecem suporte a um novo parâmetro -Select. Cada cmdlet chama as APIs de serviço da AWS para você usando o AWS SDK para .NET. Depois, o cliente do Ferramentas da AWS para PowerShell converte a resposta em um objeto que pode ser usado nos scripts do PowerShell e canaliza para outros comandos. Às vezes, o objeto final do PowerShell tem mais campos ou propriedades na resposta original do que o necessário e, outras vezes, você pode querer que o objeto inclua campos ou propriedades da resposta que não estão lá por padrão. O parâmetro -Select permite que você especifique o que está incluído no objeto .NET retornado pelo cmdlet.

Por exemplo, o cmdlet Get-S3Object invoca a operação ListObjects do Amazon S3 SDK. Essa operação retorna um objeto ListObjectsResponse. No entanto, por padrão, o cmdlet Get-S3Object retorna somente o elemento S3Objects da resposta do SDK para o usuário do PowerShell. No exemplo a seguir, esse objeto é uma matriz com dois elementos.

PS > Get-S3Object -BucketName amzn-s3-demo-bucket

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

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

No Ferramentas da AWS para PowerShell versão 4, é possível especificar -Select * para retornar o objeto de resposta .NET completo retornado pela chamada de API do SDK.

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

Também é possível especificar o caminho para a propriedade aninhada específica que você deseja. O exemplo a seguir retorna somente a propriedade Key de cada elemento na matriz S3Objects.

PS > Get-S3Object -BucketName amzn-s3-demo-bucket -Select S3Objects.Key
file1.txt
file2.txt

Em determinadas situações, pode ser útil retornar um parâmetro de cmdlet. É possível fazer isso com -Select ^ParameterName. Esse recurso substitui o parâmetro -PassThru, que ainda está disponível, mas defasado.

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

O tópico de referência para cada cmdlet identifica se ele é compatível com o parâmetro -Select.

Limitação mais consistente do número de itens na saída

As versões anteriores do Ferramentas da AWS para PowerShell permitiam usar o parâmetro -MaxItems para especificar o número máximo de objetos retornados na saída final.

Esse comportamento foi removido do AWS.Tools.

Esse comportamento est[a defasado no AWSPowerShell.NetCore e AWSPowerShell e será removido dessas versões em uma versão futura.

Se a API do serviço subjacente oferecer suporte a um parâmetro MaxItems, ele ainda estará disponível e funcionará conforme a API especifica. No entanto, ele não terá mais o comportamento adicionado de limitar o número de itens retornados na saída do cmdlet.

Para limitar o número de itens retornados na saída final, canalize a saída para o cmdlet Select-Object e especifique o parâmetro -First n, onde n é o número máximo de itens a serem incluídos na saída final.

PS > Get-S3ObjectV2 -BucketName amzn-s3-demo-bucket -Select S3Objects.Key | select -first 2
file1.txt
file2.txt

Nem todos os serviços da AWS ofereciam suporte ao -MaxItems da mesma forma, portanto, isso remove essa inconsistência e os resultados inesperados que às vezes ocorriam. Além disso, o -MaxItems combinado com o novo parâmetro -Select poderia, às vezes, produzir resultados confusos.

Parâmetros de fluxo mais fáceis de usar

Agora os parâmetros do tipo Stream ou byte[] podem aceitar os valores string, string[] ou FileInfo.

Por exemplo, você pode usar qualquer um dos exemplos a seguir.

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"', '}')

O Ferramentas da AWS para PowerShell converte todas as strings para byte[] usando a codificação UTF-8.

Estendendo o pipe por nome da propriedade

Para tornar a experiência do usuário mais consistente, agora é possível passar a entrada do pipeline especificando o nome da propriedade para qualquer parâmetro.

No exemplo a seguir, criamos um objeto personalizado com propriedades que têm nomes que correspondem aos nomes de parâmetro do cmdlet de destino. Quando o cmdlet é executado, ele consome automaticamente essas propriedades como seus parâmetros.

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

Parâmetros comuns estáticos

Para melhorar a consistência na versão 4.0 do Ferramentas da AWS para PowerShell, todos os parâmetros são estáticos.

Em versões anteriores do Ferramentas da AWS para PowerShell, alguns parâmetros comuns, como AccessKey,SecretKey, ProfileName, ou Region, eram dinâmicos, e todos os outros parâmetros eram estáticos. Isso pode criar problemas porque o PowerShell vincula parâmetros estáticos antes dos dinâmicos. Por exemplo, digamos que você tenha executado o comando a seguir.

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

As versões anteriores do PowerShell vinculavam o valor us-west-2 ao parâmetro estático -RegionName em vez do parâmetro dinâmico -Region. Provavelmente, isso poderia confundir os usuários.

AWS.ToolsO declara e aplica os parâmetros obrigatórios

Agora os módulos do AWS.Tools.* declaram e aplicam os parâmetros de cmdlet obrigatórios. Quando um serviço da AWS declara que um parâmetro de uma API é necessário, o PowerShell solicita o parâmetro de cmdlet correspondente se ele não tiver sido especificado. Isso se aplica somente a o AWS.Tools. Para garantir a compatibilidade com versões anteriores, isso não se aplica ao AWSPowerShell.NetCore nem ao AWSPowerShell.

Todos os parâmetros são anuláveis

Agora é possível atribuir $null aos parâmetros de tipo de valor (números e datas), Essa alteração não deve afetar os scripts existentes. Isso permite que você ignore o prompt para um parâmetro obrigatório. Os parâmetros obrigatórios são aplicados somente no AWS.Tools.

Se você executar o exemplo a seguir usando a versão 4, ele efetivamente ignorará a validação no lado do cliente porque você fornece um "valor" para cada parâmetro obrigatório. No entanto, a chamada de serviço de API do Amazon EC2 falhará, pois o serviço da AWS ainda exige essas informações.

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

Remover recursos defasados anteriormente

Os seguintes recursos foram defasados nas versões anteriores do Ferramentas da AWS para PowerShell e foram removidos da versão 4: