Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Pipelining, sortie et itération dans le AWS Tools for PowerShell

Pipeline

PowerShell encourage les utilisateurs à connecter les applets de commande à des pipelines qui dirigent la sortie d'une applet de commande vers l'entrée de la suivante. L'exemple suivant illustre ce comportement lors de l'utilisation du AWS Tools for PowerShell. La commande obtient puis arrête toutes les EC2 instances Amazon dans la région par défaut actuelle.

PS > Get-EC2Instance | Stop-EC2Instance

Sortie de l'applet de commande

Pour mieux prendre en charge le pipeline, certaines données issues des réponses du AWS SDK for .NET peuvent être supprimées par défaut. La sortie des AWS Tools for PowerShell applets de commande n'est pas remodelée pour inclure la réponse du service et les instances de résultat en tant que Note propriétés de l'objet de collection émis. Au lieu de cela, pour les appels qui émettent une seule collection en sortie, la collection est désormais énumérée dans le PowerShell pipeline. Cela signifie que les données de SDK réponse et de résultat ne peuvent pas exister dans le pipeline car il n'existe aucun objet de collection contenant auquel elles peuvent être attachées.

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 par les appels de AWS service sous-jacents effectués par l'applet de commande. À partir de la AWS Tools for PowerShell version 4, les applets de commande peuvent utiliser le -Select * paramètre et l'argument pour renvoyer la réponse complète du service.

Pour illustrer comment toutes les données d'une réponse peuvent être renvoyées, considérez les exemples suivants.

Le premier exemple renvoie simplement une liste de compartiments Amazon S3. Il s'agit du comportement de par défaut.

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

Le deuxième exemple renvoie un objet de AWS SDK for .NET réponse. Comme elle -Select * a été spécifiée, la sortie inclut l'intégralité de la API réponse, qui contient l'ensemble des compartiments de la Buckets propriété. Dans cet exemple, l'Format-Listapplet de commande n'est pas strictement nécessaire, mais elle est présente pour garantir que toutes les propriétés sont affichées.

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

Itération via des données paginées

Les sections suivantes décrivent les différents types d'itérations possibles.

Itération automatique

Pour les services APIs qui imposent un nombre maximum d'objets renvoyés par défaut pour un appel donné ou qui prennent en charge les ensembles de résultats consultables, la plupart des applets de commande implémentent l'itération automatique, qui active le comportement par défaut de « ». page-to-completion Dans ce scénario, une applet de commande effectue autant d'appels que nécessaire en votre nom pour renvoyer l'ensemble de données complet au pipeline.

Dans l'exemple suivant, qui utilise l'Get-S3Objectapplet de commande, la $result variable contient des S3Object instances pour chaque clé d'un bucket appeléamzn-s3-demo-bucket1, qui est potentiellement un ensemble de données très volumineux.

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

L'exemple suivant réduit le nombre de résultats pour chaque page pendant l'itération automatique de la valeur par défaut de 1 000 à 500. L'exemple exécute deux fois plus d'appels d'itération automatique, car chaque appel renvoie deux fois moins de résultats.

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

Désactiver l'itération automatique

Si vous souhaitez que les outils PowerShell pour ne renvoient que la première page de données, vous pouvez ajouter le -NoAutoIteration paramètre pour empêcher le renvoi de pages de données supplémentaires.

L'exemple suivant utilise les -MaxKey paramètres -NoAutoIteration et pour limiter le nombre d'S3Objectinstances renvoyées à un maximum de 500 instances trouvées dans le compartiment.

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

Pour déterminer si d'autres données étaient disponibles mais n'ont pas été renvoyées, utilisez le -Select * paramètre et l'argument et vérifiez si la propriété du jeton suivant contient une valeur.

L'exemple suivant indique $true s'il y a plus de 500 objets dans le compartiment et $false sinon.

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

Itération manuelle

L'exemple suivant renvoie tous les objets S3 d'un compartiment à l'aide d'une boucle do, qui évalue la condition après chaque itération. La do boucle effectue des itérations jusqu'à ce qu'elle soit Get-S3Object définie $result.NextMarker sur$null, ce qui indique qu'il ne reste plus de données paginées. La sortie de la boucle est affectée à la $s3Objects variable.

$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)

Cet exemple utilise le PowerShell splatting pour éviter une longue ligne de code qui résulterait de la déclaration de paramètres et d'arguments en ligne.