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

Pipelining, saída e iteração no Ferramentas da AWS para PowerShell

Pipelining

O PowerShell incentiva usuários a se conectarem cmdlets em 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.

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

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

Iteração manual

O exemplo a seguir retorna todos os objetos do S3 de um bucket usando um loop 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 do PowerShell para evitar uma linha de código longa que seria causada pela declaração de parâmetros e argumentos em linha.