Migration de AWS Tools for PowerShell Version 3.3 à Version 4 - AWS Tools for PowerShell

Migration de AWS Tools for PowerShell Version 3.3 à Version 4

AWS Tools for PowerShell version 4 est une mise à jour rétrocompatible des AWS Tools for PowerShell version 3.3. Elle apporte des améliorations significatives tout en maintenant le comportement existant de l'applet de commande.

Vos scripts existants devraient continuer à fonctionner après la mise à niveau vers la nouvelle version. Toutefois, nous vous recommandons de les tester soigneusement avant de procéder à la mise à niveau de vos environnements de production.

Cette section décrit les modifications et décrit l’impact qu’elles peuvent avoir sur vos scripts.

Nouvelle version AWS.Tools entièrement modulaire

Les packages AWSPowerShell.NetCore et AWSPowerShell étaient « monolithiques ». Cela signifiait que tous les services AWS étaient pris en charge dans le même module. Très volumineux, celui-ci s’agrandissait encore à l’ajout de chaque nouveau service ou de chaque nouvelle fonctionnalité AWS. Le nouveau package AWS.Tools est divisé en modules plus petits qui vous donnent la possibilité de télécharger et d'installer uniquement ceux dont vous avez besoin pour les services AWS que vous utilisez. Le package comprend un module AWS.Tools.Common partagé requis par tous les autres modules, et un module AWS.Tools.Installer qui simplifie l'installation, la mise à jour et la suppression des modules selon les besoins.

Ceci permet également l'importation automatique des applets de commande lors du premier appel, sans devoir d’abord appeler Import-module. Toutefois, pour interagir avec les objets .NET associés avant d'appeler une applet de commande, vous devez toujours appeler Import-Module pour informer PowerShell des types .NET pertinents.

Par exemple, la commande suivante comporte une référence à Amazon.EC2.Model.Filter. Ce type de référence ne peut pas déclencher l'importation automatique, vous devez donc d’abord appeler Import-Module pour éviter l’échec de la commande.

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

Nouvelle applet de commande Get-AWSService

Pour vous aider à identifier les noms des modules de chaque service AWS dans la collection de modules AWS.Tools, vous pouvez utiliser l'applet de commande 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 ...

Nouveau paramètre -Select pour contrôler l'objet renvoyé par une applet de commande

La plupart des applets de commande de la version 4 prennent en charge un nouveau paramètre -Select. Chaque applet de commande appelle les API de services AWS pour vous à l’aide du AWS SDK for .NET. Ensuite, le client AWS Tools for PowerShell convertit la réponse en un objet que vous pouvez utiliser dans vos scripts PowerShell et diriger vers d'autres commandes. Parfois, l'objet PowerShell final comporte plus de champs ou de propriétés que vous n'en avez besoin dans la réponse initiale. D’autres fois, vous souhaiterez peut-être que l'objet inclue des champs ou des propriétés de la réponse qui ne sont pas là par défaut. Le paramètre -Select vous permet de spécifier ce qui est inclus dans l'objet .NET renvoyé par l'applet de commande.

Par exemple, l'applet de commande Get-S3Object appelle l'opération Amazon S3 SDK ListObjects. Cette opération renvoie un objet ListObjectObjectResponse. Toutefois, par défaut, l'applet de commande Get-S3Object renvoie uniquement l'élément S3Objects de la réponse SDK à l'utilisateur PowerShell. Dans l'exemple suivant, cet objet est un tableau avec deux éléments.

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

Dans les AWS Tools for PowerShell version 4, vous pouvez indiquer à -Select * de renvoyer l'objet de réponse .NET complet renvoyé par l'appel de l'API SDK.

PS > Get-S3Object -BucketName mybucket -Select * IsTruncated : False NextMarker : S3Objects : {file1.txt, file2.txt} Name : mybucket Prefix : MaxKeys : 1000 CommonPrefixes : {} Delimiter :

Vous pouvez également spécifier le chemin d'accès vers la propriété imbriquée spécifique de votre choix. L'exemple suivant renvoie uniquement la propriété Key de chaque élément du tableau S3Objects.

PS > Get-S3Object -BucketName mybucket -Select S3Objects.Key file1.txt file2.txt

Dans certaines situations, il peut être utile de renvoyer un paramètre d'applet de commande. Vous pouvez effectuer cette opération avec -Select ^ParameterName. Cette fonctionnalité supplante le paramètre -PassThru, qui est toujours disponible, mais obsolète.

PS > Get-S3Object -BucketName mybucket -Select S3Objects.Key | >> Write-S3ObjectTagSet -Select ^Key -BucketName mybucket -Tagging_TagSet @{ Key='key'; Value='value'} file1.txt file2.txt

La rubrique de référence de chaque applet de commande identifie si elle prend en charge le paramètre -Select.

Limitation plus cohérente du nombre d'éléments dans la sortie

Les versions antérieures des AWS Tools for PowerShell vous permettaient d'utiliser le paramètre -MaxItems pour spécifier le nombre maximal d'objets renvoyés dans la sortie finale.

Ce comportement est supprimé de AWS.Tools.

Ce comportement est obsolète dans AWSPowerShell.NetCore et dans AWSPowerShell, et sera prochainement supprimé de ces versions.

Si l'API de service sous-jacente prend en charge un paramètre MaxItems, il sera toujours disponible et fonctionnera comme le spécifie l'API. Mais il ne présente plus le comportement qui consiste à limiter le nombre d'éléments renvoyés dans la sortie de l'applet de commande.

Pour limiter le nombre d'éléments renvoyés dans la sortie finale, dirigez la sortie vers l'applet de commande Select-Items et spécifiez le paramètre -First n, où n est le nombre maximal d'éléments à inclure dans la sortie finale.

PS > Get-S3Object -BucketName mybucket -Select S3Objects.Key | select -first 1* file1.txt

Tous les services AWS ne prenaient pas en charge -MaxItems de la même manière, ce qui supprime cette incohérence et les résultats inattendus qui se produisaient parfois. De plus, -MaxItems combiné avec le nouveau paramètre -Select entraînait parfois des résultats déroutants.

Paramètres de flux plus faciles à utiliser

Les paramètres de type Stream ou byte[] peuvent désormais accepter les valeurs string, string[] ou FileInfo.

Par exemple, vous pouvez utiliser l'un des exemples suivants.

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

Les AWS Tools for PowerShell convertissent toutes les chaînes en byte[] à l’aide du codage UTF-8.

Extension du pipeline par nom de propriété

Pour rendre l'expérience utilisateur plus cohérente, vous pouvez désormais transmettre l'entrée de pipeline en spécifiant le nom de propriété pour n'importe quel paramètre.

Dans l'exemple suivant, nous créons un objet personnalisé avec des propriétés dont les noms correspondent aux noms de paramètres de l'applet de commande cible. Lorsque l'applet de commande s'exécute, elle utilise automatiquement ces propriétés comme paramètres.

PS > [pscustomobject] @{ BucketName='myBucket'; Key='file1.txt'; PartNumber=1 } | Get-S3ObjectMetadata
Note

Certaines propriétés prenaient cela en charge dans les versions antérieures des AWS Tools for PowerShell. La version 4 rend cela plus cohérent en l'activant pour tous les paramètres.

Paramètres communs statiques

Pour améliorer la cohérence dans la version 4.0 des AWS Tools for PowerShell, tous les paramètres sont statiques.

Dans les versions antérieures de AWS Tools for PowerShell, certains paramètres communs tels que AccessKey,SecretKey, ProfileName ou Region étaient dynamiques, tandis que tous les autres paramètres étaient statiques. Ceci pouvait créer des problèmes, car PowerShell lie les paramètres statiques avant les paramètres dynamiques. Par exemple, imaginons que vous ayez exécuté la commande suivante.

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

Les versions antérieures de PowerShell liaient la valeur us-west-2 au paramètre statique -RegionName au lieu du paramètre dynamique -Region. Ceci pouvait perturber les utilisateurs.

AWS.Tools déclare et applique les paramètres obligatoires

Les modules AWS.Tools.* déclarent et appliquent désormais les paramètres obligatoires de l’applet de commande. Lorsqu'un service AWS déclare qu'un paramètre d'une API est requis, PowerShell vous invite à saisir le paramètre d'applet de commande correspondant, si vous ne l'avez pas spécifié. Ceci s'applique uniquement à AWS.Tools. Pour assurer la rétrocompatibilité, ceci ne s'applique pas à AWSPowerShell.NetCore ni à AWSPowerShell.

Tous les paramètres sont nullables

Vous pouvez désormais attribuer $null aux paramètres de type valeur (nombres et dates). Cette modification ne devrait pas affecter les scripts existants. Ceci vous permet de contourner l'invite pour un paramètre obligatoire. Les paramètres obligatoires sont appliqués dans AWS.Tools uniquement.

Si vous exécutez l'exemple suivant en utilisant la version 4, il contournera efficacement la validation côté client, car vous fournissez une « valeur » pour chaque paramètre obligatoire. Cependant, l'appel de service d’API Amazon EC2 échouera, car le service AWS nécessite toujours ces informations.

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

Suppression des fonctions obsolètes dans les versions antérieures

Les fonctionnalités suivantes étaient obsolètes dans les versions précédentes des AWS Tools for PowerShell et sont supprimées dans la version 4 :

  • Suppression du paramètre -Terminate de l'applet de commande Stop-EC2Instance. Utilisez Remove-EC2Instance à la place.

  • Suppression du paramètre -ProfileName de l'applet de commande Clear-AWScredential. Utilisez Remove-AWSCredentialProfile à la place.

  • Suppression des applets de commande Import-EC2Instance et Import-EC2Volume.