Migración de la versión 3.3 de AWS Tools for PowerShell a la versión 4

La versión 4 de AWS Tools for PowerShell es una actualización compatible con versiones anteriores a la versión 3.3 de AWS Tools for 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

El AWSPowerShell. NetCore y AWSPowerShell los paquetes 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, para interactuar con los objetos de.NET asociados antes de llamar a un cmdlet, debe seguir llamando Import-Module para PowerShell informar sobre 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 for .NET. A continuación, el AWS Tools for PowerShell cliente convierte la respuesta en un objeto que puede utilizar en sus PowerShell scripts y canalizarla a otros comandos. A veces, el PowerShell objeto final tiene más campos o propiedades en la respuesta original de los que necesita y, en otras ocasiones, es posible que desee que el objeto incluya 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 del SDK de Amazon S3. ListObjects Esa operación devuelve un ListObjectsResponseobjeto. Sin embargo, de forma predeterminada, el Get-S3Object cmdlet devuelve al usuario solo el S3Objects elemento de la respuesta del PowerShell SDK. En el siguiente ejemplo, ese objeto es una matriz con dos elementos.

PS > Get-S3Object -BucketName mybucket

ETag : "01234567890123456789012345678901111"
BucketName : mybucket
Key : file1.txt
LastModified : 9/30/2019 1:31:40 PM
Owner : Amazon.S3.Model.Owner
Size : 568
StorageClass : STANDARD

ETag : "01234567890123456789012345678902222"
BucketName : mybucket
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 AWS Tools for 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 mybucket -Select *
  IsTruncated    : False
  NextMarker     :
  S3Objects      : {file1.txt, file2.txt}
  Name           : mybucket
  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 mybucket -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 mybucket -Select S3Objects.Key |
>> Write-S3ObjectTagSet -Select ^Key -BucketName mybucket -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 AWS Tools for 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 en una versión futura.

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

AWS Tools for 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='myBucket'; Key='file1.txt'; PartNumber=1 } | Get-S3ObjectMetadata

nota

Algunas propiedades ya admitían esto en versiones anteriores de AWS Tools for PowerShell. La versión 4 hace que este comportamiento sea más coherente, ya que está habilitado en todos los parámetros.

Parámetros comunes estáticos

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

En versiones anteriores de AWS Tools for 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 podría crear problemas porque 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 -RegionName estático en lugar del -Region dinámico. 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 AWS servicio declara que se requiere un parámetro de una API, PowerShell le solicita el parámetro del cmdlet correspondiente si no lo especificó. 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 AWS Tools for PowerShell y se han quitado en la versión 4:

• El parámetro -Terminate se ha eliminado del cmdlet Stop-EC2Instance. En su lugar, use Remove-EC2Instance.

• Se quitó el -ProfileName parámetro del AWSCredential cmdlet Clear-. En su lugar, use Remove-AWSCredentialProfile.

• Los cmdlets Import-EC2Instance y Import-EC2Volume se han eliminado.