A Ferramentas da AWS para PowerShell versão 5 (V5) está em pré-visualização, portanto, esse conteúdo está sujeito a alterações. Para obter informações sobre alterações significativas, instalação e migração, consulte o tópico sobre migração. Para ver o conteúdo lançado, consulte o guia do usuário da versão 4.

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

Tubulação

PowerShell incentiva os usuários a conectar cmdlets em pipelines que direcionam a saída de um cmdlet para a entrada do próximo. O exemplo a seguir mostra esse comportamento ao usar Ferramentas da AWS para PowerShell o. O comando obtém e interrompe todas as EC2 instâncias da Amazon na região padrão atual.

PS > Get-EC2Instance | Stop-EC2Instance

Saída de cmdlet

Para oferecer melhor suporte ao pipeline, alguns dados das respostas do AWS SDK para .NET podem ser descartados por padrão. A saída dos Ferramentas da AWS para PowerShell cmdlets não foi remodelada para incluir as instâncias de resposta e resultado do serviço como Note propriedades no objeto de coleção emitido. Em vez disso, para as chamadas que emitem uma única coleção como saída, a coleção agora é enumerada no pipeline. PowerShell Isso significa que os dados de resposta e resultado do SDK não podem existir no pipeline porque não há nenhum objeto de coleção contido ao qual 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 das chamadas de AWS serviço subjacentes feitas pelo cmdlet. Os cmdlets podem usar o -Select * parâmetro 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 AWS SDK para .NET resposta. Como -Select * foi especificada, a saída inclui toda a resposta da API, que contém a coleção de buckets na Buckets propriedade. Neste exemplo, o Format-List cmdlet 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 vários tipos de iteração que são possíveis.

Iteração automática

Para serviços APIs que impõem um número máximo padrão de objetos retornados para uma determinada chamada ou que oferecem 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 Nesse cenário, um cmdlet faz quantas chamadas forem necessárias em seu nome para retornar o conjunto de dados completo ao pipeline.

No exemplo a seguir, que usa o Get-S3Object cmdlet, a $result variável contém S3Object instâncias para cada chave em um bucket chamadoamzn-s3-demo-bucket1, que é 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 1000 para 500. O exemplo executa o dobro de chamadas de iteração automática porque somente metade dos resultados são retornados para cada chamada.

PS > $result = Get-S3Object -BucketName amzn-s3-demo-bucket1 -MaxKey 500

Desativar a iteração automática

Se quiser que as Ferramentas PowerShell para retornem somente a primeira página de dados, você pode adicionar o -NoAutoIteration parâmetro para evitar que páginas adicionais de dados sejam retornadas.

O exemplo a seguir usa os -MaxKey parâmetros -NoAutoIteration e para limitar o número de S3Object instâncias retornadas a não mais do que as 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 -Select * parâmetro e o argumento e verifique se há um valor na próxima propriedade do token.

O exemplo a seguir retorna $true se há mais de 500 objetos no bucket e de $false outra forma.

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 avalia a condição após cada iteração. O do loop executa iterações até $result.NextMarker ser Get-S3Object definido como$null, indicando que não há mais dados paginados. A saída do loop é atribuída à $s3Objects variável.

$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 PowerShell splatting para evitar uma longa linha de código que seria causada pela declaração de parâmetros e argumentos em linha.