Canalización, salida e iteración en Herramientas de AWS para PowerShell - Herramientas de AWS para PowerShell (versión 4)
CanalizaciónSalida de cmdletIteración a través de datos paginados

¡Se Herramientas de AWS para PowerShell ha lanzado la versión 5 (V5) del!

Para empezar a utilizar la nueva versión de Tools para PowerShell, consulte la Guía del usuario de Herramientas de AWS para PowerShell (V5), especialmente el tema sobre la Migración a la V5.

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Canalización, salida e iteración en Herramientas de AWS para PowerShell

Canalización

PowerShell recomienda a los usuarios conectar los cmdlets en canalizaciones que dirijan la salida de un cmdlet a la entrada del siguiente. El siguiente ejemplo muestra este comportamiento al usar Herramientas de AWS para PowerShell. El comando obtiene todas las instancias de Amazon EC2 de la región predeterminada actual y, a continuación, las detiene.

PS > Get-EC2Instance | Stop-EC2Instance

Salida de cmdlet

Para proporcionar una mejor canalización, es posible que algunos datos de las respuestas de AWS SDK para .NET se descarten de forma predeterminada. La salida de los cmdlets de Herramientas de AWS para PowerShell no se reestructura para incluir la respuesta del servicio y las instancias resultantes como propiedades Note en el objeto de colección emitido. En lugar de ello, para aquellas llamadas que emiten una única colección como salida, la colección ahora se enumera en la canalización de PowerShell. Esto significa que la respuesta del SDK y los datos resultantes no pueden existir en la canalización debido a que no hay ningún objeto de colección contenedor con el que se puedan asociar.

Aunque la mayoría de los usuarios probablemente no necesiten estos datos, pueden resultar útiles para fines de diagnóstico, ya que es posible ver exactamente lo que se ha enviado y recibido de las llamadas del servicio de AWS subyacente realizadas por el cmdlet. A partir de la versión 4 de Herramientas de AWS para PowerShell, los cmdlets pueden usar el argumento y el parámetro -Select * para devolver la respuesta completa del servicio.

nota

En las versiones de Herramientas de AWS para PowerShell anteriores a la V4, se introdujo una variable de sesión llamada $AWSHistory que mantiene un registro de las invocaciones de cmdlets de AWS y de las respuestas del servicio que se recibieron en cada invocación. En la versión 4 de las Herramientas para PowerShell, esta variable de sesión quedó obsoleta y se sustituyó por el argumento y el parámetro -Select *, que se puede usar para devolver la respuesta completa del servicio. En este tema se describe dicho parámetro.

nota

Esta es una documentación preliminar para una característica en versión de vista previa. Está sujeta a cambios.

La variable $AWSHistory se eliminará en la versión 5 de Herramientas de AWS para PowerShell. Para obtener más información, consulte la entrada de blog Notice of upcoming major version 5 of AWS Tools para PowerShell.

Para ilustrar cómo se pueden devolver todos los datos de una respuesta, considere los siguientes ejemplos.

El primer ejemplo simplemente devuelve una lista de buckets de Amazon S3. Este es el comportamiento predeterminado.

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

El segundo ejemplo devuelve un objeto de respuesta de AWS SDK para .NET. Como se especificó el parámetro -Select *, el resultado incluye toda la respuesta de la API, que contiene el conjunto de buckets de la propiedad Buckets. En este ejemplo, el cmdlet Format-List no es estrictamente necesario, pero está presente para garantizar que se muestren todas las propiedades.

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

Iteración a través de datos paginados

En las siguientes secciones se describen los distintos tipos de iteración posibles.

Iteración automática

En el caso de las API de servicio que imponen un número máximo predeterminado de objetos devueltos por llamada, o que admiten conjuntos de resultados paginables, la mayoría de los cmdlets implementan una iteración automática, lo que permite el comportamiento predeterminado de “paginar hasta el final”. En esta situación, cada cmdlet realiza todas las llamadas necesarias en su nombre para devolver todo el conjunto de datos a la canalización.

En el siguiente ejemplo, que utiliza el cmdlet Get-S3Object, la variable $result contiene instancias S3Object para cada clave en el bucket llamado amzn-s3-demo-bucket1, lo que puede dar lugar a un gran conjunto de datos.

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

El siguiente ejemplo reduce a la mitad el número de resultados por página durante la iteración automática: el valor predeterminado de 1000 pasa a 500. El ejemplo realiza el doble de llamadas de iteración automática porque solo se devuelve la mitad de los resultados por cada llamada.

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

En la versión 4 de Herramientas de AWS para PowerShell, algunos cmdlets para operaciones paginadas no implementan la iteración automática. Si un cmdlet no tiene el parámetro -NoAutoIteration, como se explica en la siguiente sección, no podrá implementar la iteración automática.

Deshabilitación de la iteración automática

Si desea que las Herramientas para PowerShell devuelvan únicamente la primera página de datos, puede añadir el parámetro -NoAutoIteration para evitar que se devuelvan páginas de datos adicionales.

El siguiente ejemplo utiliza los parámetros -NoAutoIteration y -MaxKey para limitar el número de instancias S3Object que se devuelven a las primeras 500 encontradas en el bucket como máximo.

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

Para determinar si había más datos disponibles que no se devolvieron, utilice el argumento y el parámetro -Select * y compruebe si hay algún valor en la siguiente propiedad del token.

En el siguiente ejemplo se devuelve $true si hay más de 500 objetos en el bucket, de lo contrario se devuelve $false.

PS > $result = Get-S3Object -BucketName amzn-s3-demo-bucket1 -MaxKey 500 -NoAutoIteration -Select *
PS > $null -eq $result.NextMarker
nota

Los nombres de la siguiente propiedad de respuesta del token y del parámetro del cmdlet varían de un cmdlet a otro. Para obtener más información, consulte la documentación de ayuda de cada cmdlet.

Iteración manual

En el siguiente ejemplo, se devuelven todos los objetos de S3 de un bucket mediante un bucle do, que evalúa la condición después de cada iteración. El bucle do realiza iteraciones hasta que Get-S3Object establece $result.NextMarker en $null, lo que indica que no quedan más datos paginados. La salida del bucle se asigna a la variable $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)

En este ejemplo, se utiliza el método splatting en PowerShell para evitar una línea de código demasiado larga, que se produciría al declarar parámetros y argumentos en línea.