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á. # Pipelining, saída e iteração no Ferramentas da AWS para PowerShell ## Pipelining O PowerShell incentiva usuários a se conectarem cmdlets em [pipelines](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_pipelines) que direcionam a saída de um cmdlet para a entrada do próximo. O exemplo a seguir mostra esse comportamento durante o uso do Ferramentas da AWS para PowerShell. O comando obtém e, em seguida, interrompe todas as instâncias do Amazon EC2 na região padrão atual. ``` PS > Get-EC2Instance | Stop-EC2Instance ``` ## Saída do cmdlet Para dar um suporte melhor ao pipelining, alguns dados das respostas do AWS SDK para .NET podem ser descartados por padrão. A saída dos cmdlets Ferramentas da AWS para PowerShell não é remodelada para incluir a resposta do serviço e as instâncias de resultado como propriedades `Note` no objeto de coleção emitido. Em vez disso, para essas chamadas que emitem uma única coleção como saída, a coleção agora é enumerada para o pipeline do PowerShell. Isso significa que a resposta do SDK e os dados do resultado não podem existir no pipe, pois não há objeto de coleção contêiner ao qual eles possam ser anexados. Embora a maioria dos usuários provavelmente não precise desses dados, eles podem ser úteis para fins de diagnóstico, pois você pode ver exatamente o que foi enviado e recebido pelas chamadas de serviço AWS subjacentes feitas pelo cmdlet. A partir do Ferramentas da AWS para PowerShell V4, os cmdlets podem usar o parâmetro `-Select *` e o argumento para retornar toda a resposta do serviço. **nota** Nas versões do Ferramentas da AWS para PowerShell anteriores a V4, uma variável de sessão chamada `$AWSHistory` foi introduzida e mantém um registro de invocações do cmdlet da AWS e as respostas de serviço que foram recebidas para cada invocação. Na V4 do Tools for PowerShell, essa variável de sessão foi descontinuada em favor do parâmetro `-Select *` e do argumento, que podem ser usados para retornar toda a resposta do serviço. Esse parâmetro está descrito neste tópico. Esta é uma documentação de pré-lançamento de um recurso em versão de pré-visualização. Está sujeita a alteração. A variável `$AWSHistory` será removida na V5 do Ferramentas da AWS para PowerShell. Para obter mais informações, consulte a postagem no blog: [Aviso da próxima versão principal 5 do AWS Tools for PowerShell](https://aws.amazon.com/blogs/developer/notice-of-upcoming-major-version-5-of-aws-tools-for-powershell/). Para ilustrar como todos os dados de uma resposta podem ser retornados, considere os exemplos a seguir. O primeiro exemplo simplesmente retorna uma lista de buckets do Amazon S3. Esse é o comportamento padrão. ``` 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 ``` O segundo exemplo retorna um objeto de resposta do AWS SDK para .NET. Como `-Select *` foi especificado, a saída inclui toda a resposta da API, que contém a coleção de buckets na propriedade `Buckets`. Neste exemplo, o cmdlet `Format-List` não é estritamente necessário, mas está presente para garantir que todas as propriedades sejam exibidas. ``` 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 ``` ## Iteração por meio de dados paginados As seções a seguir descrevem tipos variados de iteração possíveis. ### Iteração automática Para APIs de serviço que impõem um número máximo padrão de objetos retornados para uma determinada chamada ou que dão suporte a conjuntos de resultados pagináveis, a maioria dos cmdlets implementa a iteração automática, o que permite o comportamento padrão de “page-to-completion”. Neste cenário, um cmdlet faz quantas chamadas forem necessárias em seu nome para retornar o conjunto de dados completo para o pipeline. No exemplo a seguir, que usa o cmdlet `Get-S3Object`, a variável `$result` contém instâncias `S3Object` para cada chave em um bucket chamado `amzn-s3-demo-bucket1`, potencialmente um conjunto de dados muito grande. ``` PS > $result = Get-S3Object -BucketName amzn-s3-demo-bucket1 ``` O exemplo a seguir reduz o número de resultados de cada página durante a iteração automática do valor padrão de 1.000 para 500. O exemplo realiza o dobro de chamadas de iteração automática porque apenas metade dos resultados retorna para cada chamada. ``` PS > $result = Get-S3Object -BucketName amzn-s3-demo-bucket1 -MaxKey 500 ``` **nota** No Ferramentas da AWS para PowerShell V4, alguns cmdlets para operações paginadas não implementam a iteração automática. Se um cmdlet não tiver o parâmetro `-NoAutoIteration`, abordado na próxima seção, ele não implementará a iteração automática. ### Desabilitar iteração automática Se quiser que o Tools for PowerShell retorne apenas a primeira página de dados, você poderá adicionar o parâmetro `-NoAutoIteration` para evitar que páginas adicionais de dados sejam retornadas. O exemplo a seguir usa os parâmetros `-NoAutoIteration` e `-MaxKey` para limitar o número de instâncias `S3Object` retornadas às primeiras 500 encontradas no bucket. ``` PS > $result = Get-S3Object -BucketName amzn-s3-demo-bucket1 -MaxKey 500 -NoAutoIteration ``` Para determinar se mais dados estavam disponíveis, mas não foram retornados, use o parâmetro `-Select *` e o argumento, e verifique se há um valor na próxima propriedade de token. O exemplo a seguir retornará `$true` se houver mais de 500 objetos no bucket e `$false` do contrário. ``` PS > $result = Get-S3Object -BucketName amzn-s3-demo-bucket1 -MaxKey 500 -NoAutoIteration -Select * PS > $null -eq $result.NextMarker ``` **nota** Os nomes da próxima propriedade de resposta do token e do parâmetro do cmdlet variam entre cmdlets. Para obter detalhes, consulte a documentação de ajuda de cada cmdlet. ### Iteração manual O exemplo a seguir retorna todos os objetos do S3 de um bucket usando um loop [do](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_do), que avaliará a condição depois de cada iteração. O loop `do` realizará iterações até `Get-S3Object` definir `$result.NextMarker` como `$null`, indicando que não há mais dados paginados. A saída do loop é atribuída à variável `$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) ``` Este exemplo usa o [splatting](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_splatting) do PowerShell para evitar uma linha de código longa que seria causada pela declaração de parâmetros e argumentos em linha.