Ferramentas da AWS para PowerShell O V4 entrou no modo de manutenção. Recomendamos que você migre para a [Ferramentas da AWS para PowerShell V5](https://docs.aws.amazon.com/powershell/v5/userguide/). Para obter detalhes e informações adicionais sobre como migrar, consulte nosso [anúncio do modo de manutenção](https://aws.amazon.com/blogs/developer/aws-tools-for-powershell-v4-maintenance-mode-announcement/). 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á. # Migrando da Ferramentas da AWS para PowerShell versão 3.3 para a versão 4 Ferramentas da AWS para PowerShell a versão 4 é uma atualização compatível com versões anteriores da versão 3.3. Ferramentas da AWS para PowerShell 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` A AWSPower concha. NetCore e os pacotes AWSPower Shell eram “monolíticos”. Isso significava que todos os AWS serviços eram suportados no mesmo módulo, tornando-o muito grande e crescendo à medida que cada novo AWS serviço e recurso era adicionado. O novo `AWS.Tools` pacote é dividido em módulos menores que oferecem a flexibilidade de baixar e instalar somente aqueles necessários para os AWS serviços 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, você ainda deve ligar `Import-Module` para PowerShell informar 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 ajudá-lo a descobrir os nomes dos módulos de cada AWS serviço na `AWS.Tools` coleção de módulos, você pode usar o `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 ... ``` ## 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 o AWS serviço APIs para você usando o. AWS SDK para .NET Em seguida, o Ferramentas da AWS para PowerShell cliente converte a resposta em um objeto que você pode usar em seus PowerShell scripts e direcionar para outros comandos. Às vezes, o PowerShell objeto final tem mais campos ou propriedades na resposta original do que você precisa, 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 [Get-S3Object](https://docs.aws.amazon.com/powershell/v4/reference/items/Get-S3Object.html)cmdlet invoca a operação do Amazon S3 SDK. [ListObjects](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html?page=S3/MS3ListObjectsListObjectsRequest.html) Essa operação retorna um [ListObjectsResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html?page=S3/MS3ListObjectsListObjectsRequest.h)objeto. No entanto, por padrão, o `Get-S3Object` cmdlet retorna somente o `S3Objects` elemento da resposta do SDK para o usuário. 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 ``` Na Ferramentas da AWS para PowerShell versão 4, você pode especificar `-Select *` o retorno do objeto de resposta.NET completo retornado pela chamada da 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](https://docs.aws.amazon.com/powershell/v4/reference/) 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 que você usasse o `-MaxItems` parâmetro para especificar o número máximo de objetos retornados na saída final. Esse comportamento foi removido do `AWS.Tools`. Esse comportamento está obsoleto no Shell. AWSPower NetCore e AWSPower Shell, e serão removidos 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 `Select-Object` cmdlet e especifique o `-First n` parâmetro, onde *n* está 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 AWS serviços são suportados `-MaxItems` da mesma forma, então 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`](#migrate-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"', '}') ``` Ferramentas da AWS para PowerShell converte todas as strings para `byte[]` usar 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 ``` **nota** Algumas propriedades suportavam isso em versões anteriores do Ferramentas da AWS para PowerShell. A versão 4 torna isso mais consistente, ativando-o para *todos* os parâmetros. ## 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. Nas versões anteriores do Ferramentas da AWS para PowerShell, alguns parâmetros comuns`AccessKey`, como,`SecretKey`, ou `ProfileName``Region`, eram [dinâmicos](https://docs.microsoft.com/dotnet/api/system.management.automation.idynamicparameters), enquanto todos os outros parâmetros eram estáticos. Isso pode criar problemas porque PowerShell vincula os 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 ``` Versões anteriores do PowerShell vinculavam o valor `us-west-2` ao parâmetro `-RegionName` estático em vez do parâmetro `-Region` dinâmico. Provavelmente, isso poderia confundir os usuários. ## O `AWS.Tools` 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 AWS serviço declara que um parâmetro de uma API é necessário, PowerShell solicita o parâmetro de cmdlet correspondente, caso você não o tenha especificado. Isso se aplica somente a o `AWS.Tools`. Para garantir a compatibilidade com versões anteriores, isso não se aplica ao AWSPower Shell. NetCore ou AWSPower Shell. ## 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 do serviço de API do Amazon EC2 falha porque o AWS serviço 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](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](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 descontinuados nas versões anteriores do Ferramentas da AWS para PowerShell e foram removidos na versão 4: + Removido o parâmetro `-Terminate` do cmdlet `Stop-EC2Instance`. Use `Remove-EC2Instance` em vez disso. + O `-ProfileName` parâmetro foi removido do AWSCredential cmdlet Clear-. Use `Remove-AWSCredentialProfile` em vez disso. + Removidos os cmdlets `Import-EC2Instance` e `Import-EC2Volume`.