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

Migración de la versión 3.3 de Herramientas de AWS para PowerShell a la versión 4

La versión 4 de Herramientas de AWS para PowerShell es una actualización compatible con versiones anteriores a la versión 3.3 de Herramientas de AWS para PowerShell. Agrega mejoras significativas a la vez que mantiene el comportamiento existente del cmdlet.

Los scripts existentes deberían seguir funcionando después de actualizar a la nueva versión, pero recomendamos que los pruebe a fondo antes de actualizar los entornos de producción.

En esta sección, se describen los cambios y se explica cómo pueden afectar a los scripts.

Nueva versión de AWS.Tools dividida completamente en módulos

Los paquetes AWSPowerShell.NetCore y AWSPowerShell eran “monolíticos”. es decir, todos los servicios de AWS se basaban en el mismo módulo, lo que lo hacía muy grande, ya que iba creciendo a medida que se agregaba cada nueva característica y servicio de AWS. El nuevo paquete AWS.Tools se divide en módulos más pequeños que le ofrecen flexibilidad para descargar e instalar únicamente aquellos módulos que son necesarios para los servicios de AWS que utiliza. El paquete incluye un módulo AWS.Tools.Common compartido que todos los demás módulos necesitan y un módulo AWS.Tools.Installer que simplifica la instalación, actualización y eliminación de módulos, en función de las necesidades.

Esto también permite importar automáticamente cmdlets en la primera llamada sin tener que invocar primero a Import-module. Sin embargo, a la hora interactuar con los objetos de .NET asociados antes de llamar a un cmdlet, sigue siendo necesario llamar a Import-Module para que PowerShell conozca los tipos de .NET pertinentes.

Por ejemplo, el comando siguiente contiene una referencia a Amazon.EC2.Model.Filter. Este tipo de referencia no puede desencadenar la importación automática, por lo que será necesario llamar primero a Import-Module o el comando no se ejecutará correctamente.

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

Nuevo cmdlet Get-AWSService

Para ayudarle a detectar los nombres de los módulos de cada servicio de AWS entre la colección de módulos de AWS.Tools, puede utilizar el cmdlet Get-AWSService.

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

Nuevo parámetro -Select para controlar el objeto devuelto por un cmdlet

La mayoría de los cmdlets de la versión 4 admiten el nuevo parámetro -Select. Cada cmdlet llama por usted a las API de los servicios de AWS utilizando AWS SDK para .NET. A continuación, el cliente de Herramientas de AWS para PowerShell convierte la respuesta en un objeto que se puede utilizar en los scripts de PowerShell y canalizar a otros comandos. A veces, el objeto final de PowerShell puede contener más campos o propiedades en la respuesta original que los que se necesitan, mientras que otras veces es posible que le gustaría que el objeto incluyera campos o propiedades de la respuesta que no aparecen de forma predeterminada. El parámetro -Select permite especificar el contenido que se va a incluir en el objeto .NET devuelto por el cmdlet.

Por ejemplo, el cmdlet Get-S3Object invoca la operación de SDK de Amazon S3 ListObjects. Esta operación devuelve un objeto ListObjectsResponse . Sin embargo, de forma predeterminada, el cmdlet Get-S3Object solo devuelve el elemento S3Objects de la respuesta del SDK al usuario de PowerShell. En el siguiente ejemplo, ese objeto es una matriz con dos 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

En la versión 4 de Herramientas de AWS para PowerShell, puede especificar -Select * para obtener el objeto de respuesta .NET completo devuelto por la llamada a la API del 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      :

También puede especificar la ruta de acceso a una propiedad anidada específica que desee. En el ejemplo siguiente, solo se devuelve la propiedad Key de cada elemento de la matriz S3Objects.

PS > Get-S3Object -BucketName amzn-s3-demo-bucket -Select S3Objects.Key
file1.txt
file2.txt

En determinadas situaciones, puede ser útil devolver un parámetro de cmdlet. Puede hacerlo con -Select ^ParameterName. Esta función suplanta al parámetro -PassThru, que, aunque sigue estando disponible, se ha quedado obsoleto.

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

En el tema de referencia de cada cmdlet, se indica si se admite el parámetro -Select.

Limitación más coherente del número de elementos de la salida

Las versiones anteriores de Herramientas de AWS para PowerShell permitían utilizar el parámetro -MaxItems para especificar el número máximo de objetos que se devolvían en la salida final.

Este comportamiento se ha eliminado en AWS.Tools.

Este comportamiento está obsoleto en AWSPowerShell.NetCore y AWSPowerShell, y se eliminará de esas versiones próximamente.

Si la API del servicio subyacente es compatible con el parámetro MaxItems, seguirá estando disponible y funcionará tal y como especifica la API. Sin embargo, no dispondrá del comportamiento adicional que permite limitar el número de elementos devueltos en el resultado del cmdlet.

Para limitar el número de elementos devueltos en la salida final, canalice el resultado al cmdlet Select-Object y especifique el parámetro -First n, donde n es el número máximo de elementos que se van a incluir en la salida final.

PS > Get-S3ObjectV2 -BucketName amzn-s3-demo-bucket -Select S3Objects.Key | select -first 2
file1.txt
file2.txt

No todos los servicios de AWS admiten -MaxItems de la misma manera, por lo que esto elimina esa inconsistencia y los resultados inesperados que a veces se producían. Además, -MaxItems combinado con el nuevo parámetro -Select podría dar lugar en ocasiones a resultados confusos.

Parámetros de flujo más fáciles de usar

Los parámetros de tipo Stream o byte[] ahora pueden aceptar valores string, string[] o FileInfo.

Por ejemplo, puede utilizar cualquiera de los siguientes ejemplos.

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"', '}')

Herramientas de AWS para PowerShell convierte todas las cadenas a byte[] utilizando la codificación UTF-8.

Ampliación de la canalización por nombre de propiedad

Para que la experiencia del usuario sea más coherente, ahora puede pasar la entrada de la canalización especificando el nombre de propiedad de cualquier parámetro.

En el ejemplo siguiente, creamos un objeto personalizado con propiedades cuyos nombres coinciden con los nombres de parámetro del cmdlet de destino. Cuando se ejecuta el cmdlet, automáticamente consume esas propiedades como parámetros.

PS > [pscustomobject] @{ BucketName='amzn-s3-demo-bucket'; Key='file1.txt'; PartNumber=1 } | Get-S3ObjectMetadata

Parámetros comunes estáticos

Para mejorar la coherencia en la versión 4.0 de Herramientas de AWS para PowerShell, todos los parámetros son estáticos.

En versiones anteriores de Herramientas de AWS para PowerShell, algunos parámetros comunes, como AccessKey, SecretKey, ProfileName, o Region eran dinámicos, mientras que todos los demás parámetros eran estáticos. Esto podía crear problemas, ya que PowerShell vincula los parámetros estáticos antes que los dinámicos. Por ejemplo, supongamos que antes ejecutaba el siguiente comando.

PS > Get-EC2Region -Region us-west-2

Las versiones anteriores de PowerShell vinculaban el valor us-west-2 al parámetro estático -RegionName en lugar de al parámetro dinámico -Region. Probablemente, esto podría confundir a los usuarios.

AWS.Tools declara y aplica parámetros obligatorios

Todos los módulos de AWS.Tools.* ahora declaran y aplican parámetros de cmdlet obligatorios. Cuando un servicio de AWS declara que un parámetro de una API es obligatorio, PowerShell pide el parámetro del cmdlet correspondiente si no se ha especificado. Esto solo es aplicable a AWS.Tools. Para garantizar la compatibilidad con versiones anteriores, esto no se aplica a AWSPowerShell.NetCore o AWSPowerShell.

Todos los parámetros pueden ser nulos

Ahora puede asignar $null a los parámetros de tipo de valor (números y fechas). Este cambio no debería afectar a los scripts existentes. Esto le permitirá omitir el mensaje sobre la obligatoriedad de un parámetro. Los parámetros obligatorios solo se aplican forzosamente en AWS.Tools.

Si ejecuta el siguiente ejemplo utilizando la versión 4, se omitirá eficazmente la validación del lado del cliente porque se proporcionará un «valor» para cada parámetro obligatorio. Sin embargo, la llamada al servicio de la API de Amazon EC2 no se ejecutará correctamente, ya que el servicio de AWS aún necesita esa información.

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

Get-EC2InstanceAttribute : The request must contain the parameter instanceId

Eliminación de características que ya estaban obsoletas

Las siguientes características se quedaron obsoletas en versiones anteriores de Herramientas de AWS para PowerShell y se han quitado en la versión 4: