Mise en pipeline et $AWSHistory - AWS Tools for PowerShell

Mise en pipeline et $AWSHistory

Pour les appels de service AWS qui renvoient des collections, les objets de la collection sont désormais toujours énumérés sur le pipeline. Les objets de résultat qui contiennent des champs supplémentaires au-delà de la collection et qui ne sont pas des champs de contrôle de pagination ont ces champs ajoutés comme propriétés Note pour les appels. Ces propriétés Note sont enregistrées dans la nouvelle variable de session $AWSHistory, si vous devez accéder à ces données. La variable $AWSHistory est décrite dans la section suivante.

Note

Dans les versions des Tools for Windows PowerShelltait antérieures à v1.1, l'objet collection lui-même é émis, ce qui nécessitait l'utilisation de foreach {$_.getenumerator()} pour poursuivre la mise en pipeline.

Exemples

L'exemple suivant renvoie une liste de régions AWS et d'AMI (Amazon EC2 machine images) dans chaque région.

PS > Get-AWSRegion | % { Echo $_.Name; Get-EC2Image -Owner self -Region $_ }

L'exemple suivant montre comment arrêter toutes les instances Amazon EC2 de la région par défaut actuelle.

PS > Get-EC2Instance | Stop-EC2Instance

Dans la mesure où les collections sont énumérées sur le pipeline, la sortie d'une applet de commande fournie peut être $null, un seul objet ou une collection. S'il s'agit d'une collection, vous pouvez utiliser la propriété .Count pour déterminer la taille de la collection. Cependant, la propriété .Count n'est pas présente lorsqu'un seul objet est émis. Si votre script a besoin de déterminer, de manière cohérente, le nombre d'objets émis, vous pouvez utiliser la propriété EmittedObjectsCount de la valeur de la dernière commande dans $AWSHistory.

$AWSHistory

Pour une meilleure prise en charge du pipeline, la sortie des applets de commande AWS n'est plus remodelée pour inclure la réponse du service et les instances de résultat comme propriétés Note sur l'objet de collection émis. Au lieu de cela, pour ces appels qui émettent une seule collection comme sortie, la collection est désormais énumérée dans le pipeline PowerShell. Cela signifie que le SDK AWS et les données des résultats ne peuvent pas exister dans le pipeline, car il n'y a pas d'objet de collection contenant auquel ils peuvent être attachés.

Bien que la plupart des utilisateurs n'aient probablement pas besoin de ces données, elles peuvent être utiles à des fins de diagnostic, car vous pouvez voir exactement ce qui a été envoyé et reçu vers ou depuis les appels de service AWS sous-jacents effectués par l'applet de commande.

À partir de la version 1.1, ces données, entre autres, sont désormais disponibles dans une nouvelle variable shell nommée $AWSHistory. Cette variable conserve un enregistrement des appels d'applets de commande AWS et les réponses de services reçues pour chaque appel. Le cas échéant, cet historique peut également être configuré pour enregistrer aussi les demandes de service que chaque applet de commande a effectuées. Des données utiles supplémentaires, telles que la durée d'exécution globale de l'applet de commande, peuvent aussi être obtenus à partir de chaque entrée.

Chaque entrée de la liste $AWSHistory.Commands est de type AWSCmdletHistory. Ce type comporte les membres utiles suivants :

CmdletName

Nom de l'applet de commande.

CmdletStart

Date et heure auxquelles l'applet de commande a été exécutée.

CmdletEnd

Date et heure auxquelles l'applet de commande a terminé l'ensemble du traitement.

Requêtes

Si l'enregistrement de la demande est activé, la liste des dernières demandes de service.

Réponses

Liste des dernières réponses de service reçues.

LastServiceResponse

Annotations pour renvoyer la dernière réponse du service.

LastServiceRequest

Annotations pour renvoyer la dernière demande du service, le cas échéant.

Notez que la variable $AWSHistory ne sera pas créée avant qu'une applet de commande AWS effectuant un appel de service soit utilisée. Elle est analysée comme ayant la valeur $null jusqu'à ce stade.

Note

Les versions antérieures des Tools for Windows PowerShell émettaient les données relatives aux réponses de service en tant que propriétés Note sur l'objet renvoyé. Ces données sont désormais disponibles dans les entrées de réponse enregistrées pour chaque appel de la liste.

Définir AWSHistoryConfiguration

Un appel d'applet de commande peut contenir zéro ou plusieurs entrées de demande et réponse de service. Pour limiter l'impact sur la mémoire, la liste $AWSHistory conserve par défaut un enregistrement des seules cinq dernières exécutions d'applet de commande ; et pour chacune, les cinq dernières réponses de service (et, si cette option est activée, les cinq dernières demandes de service). Vous pouvez modifier ces limites par défaut en exécutant l'applet de commande Set-AWSHistoryConfiguration. Vous pouvez ainsi contrôler la taille de la liste et si les demandes de service sont également enregistrées :

PS > Set-AWSHistoryConfiguration -MaxCmdletHistory <value> -MaxServiceCallHistory <value> -RecordServiceRequests

Le paramètre -MaxCmdletHistory définit le nombre maximal d'applets de commande qui peuvent être suivis à tout moment. La valeur 0 désactive l'enregistrement de l'activité des applets de commande AWS. Le paramètre -MaxServiceCallHistory définit le nombre maximal de réponses de service (et/ou de demandes) qui sont suivies pour chaque applet de commande. Le paramètre -RecordServiceRequests, s'il est spécifié, active le suivi des demandes de service pour chaque applet de commande. Tous les paramètres sont facultatifs.

En cas d'exécution sans paramètres, Set-AWSHistoryConfiguration désactive simplement tout enregistrement de demandes précédentes et laisse inchangées les tailles de liste actuelles.

Pour effacer toutes les entrées de la liste d'historique actuelle, exécutez l'applet de commande Clear-AWSHistory.

$AWSHistoryExemples

Énumérez les détails des applets de commande AWS conservées dans la liste du pipeline.

PS > $AWSHistory.Commands

Accédez aux détails de la dernière applet de commande AWS qui a été exécutée :

PS > $AWSHistory.LastCommand

Accédez aux détails de la dernière réponse de service reçue par la dernière applet de commande AWS exécutée. Si une applet de commande AWS pagine la sortie, elle peut effectuer plusieurs appels de service pour obtenir toutes les données ou la quantité maximale de données (déterminée par les paramètres de l'applet de commande).

PS > $AWSHistory.LastServiceResponse

Accédez aux détails de la dernière demande effectuée (à nouveau, une applet de commande peut effectuer plus d'une demande si elle pagine au nom de l'utilisateur). Génère $null, à moins que le suivi de demande de service ne soit activé.

PS > $AWSHistory.LastServiceRequest

Achèvement de page automatique pour les opérations qui retournent plusieurs pages

Pour les API de service qui imposent un nombre maximal de retours d'objet par défaut pour un appel donné ou qui prennent en charge les jeux de résultats paginables, toutes les applets de commande effectuent un achèvement de page par défaut. Chaque applet de commande effectue autant d'appels que nécessaire en votre nom pour renvoyer l'ensemble complet des données au pipeline.

Dans l'exemple suivant, qui utilise Get-S3Object, la variable $c contient les instances de S3Object de chaque clé du compartiment test, potentiellement un très large ensemble de données.

PS > $c = Get-S3Object -BucketName test

Si vous souhaitez conserver le contrôle de la quantité de données renvoyées, vous pouvez utiliser des paramètres sur les applets de commande individuelles (par exemple, MaxKey sur Get-S3Object) ou traiter explicitement la pagination vous-même en utilisant une combinaison des paramètres de pagination sur les applets de commande, et les données placées dans la variable $AWSHistory pour obtenir les données du jeton suivant du service. L'exemple suivant utilise le paramètre MaxKeys pour limiter le nombre d'instances S3Object renvoyées aux seules premières 500 du compartiment.

PS > $c = Get-S3Object -BucketName test -MaxKey 500

Pour savoir si d'autres données sont disponibles, mais n'ont pas été retournées, utilisez l'entrée de la variable de session $AWSHistory qui a enregistré les appels de service effectués par l'applet de commande.

Si l'expression suivante a la valeur $true, vous pouvez trouver le marqueur next du prochain ensemble de résultats à l'aide de $AWSHistory.LastServiceResponse.NextMarker :

$AWSHistory.LastServiceResponse -ne $null && $AWSHistory.LastServiceResponse.IsTruncated

Pour contrôler manuellement la pagination avec Get-S3Object, utilisez une combinaison des paramètres MaxKey et Marker de l'applet de commande et les annotations IsTruncated/NextMarker de la dernière réponse enregistrée. Dans l'exemple suivant, la variable $c contient jusqu'à un maximum de 500 instances S3Object pour les 500 objets suivants trouvés dans le compartiment après le début du marqueur de préfixe de clé spécifié.

PS > $c = Get-S3Object -BucketName test -MaxKey 500 -Marker $AWSHistory.LastServiceResponse.NextMarker