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.

Paginateurs dans laAWS SDK for PHP version 3

Certaines opérationsAWS de service sont paginées et donnent des résultats tronqués. Par exemple, l'ListObjectsopération Amazon S3 ne renvoie que 1 000 objets à la fois. Ces opérations (qui comportent généralement le préfixe « list » ou « describe ») requièrent l'exécution des demandes suivantes avec des paramètres jeton (ou marqueur) afin de récupérer l'ensemble des résultats.

Les programmes de pagination sont une fonction du kit AWS SDK for PHP et jouent un rôle d’abstraction sur ce processus pour faciliter l’utilisation des API paginées pour les développeurs. Un programme de pagination est principalement un itérateur de résultats. Ils est créé grâce à la méthode getPaginator() du client. Lorsque vous appelez getPaginator(), vous devez fournir le nom de l'opération et ses arguments (comme lors de l'exécution d'une opération). Vous pouvez itérer sur un objet de programme de pagination en utilisant foreach pour obtenir les objets Aws\Result individuels.

$results = $s3Client->getPaginator('ListObjects', [
    'Bucket' => 'my-bucket'
]);

foreach ($results as $result) {
    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
}

Objets Paginator

L'objet renvoyé par cette méthode getPaginator() est une instance de la classe Aws\ResultPaginator. Cette classe met en œuvre une interface native PHP iterator ; c'est pourquoi elle fonctionne avec foreach. Il peut également être utilisé avec des fonctions d’itérateur, comme iterator_to_array, et s’intègre parfaitement avec les itérateurs SPL comme l’objet LimitIterator.

Les objets de programme de pagination ne peuvent contenir qu'une seule « page » de résultats à la fois et sont exécutés lentement. Ceci signifie qu'ils réalisent uniquement les demandes dont ils ont besoin pour obtenir la page de résultats. Par exemple, l'ListObjectsopération Amazon S3 ne renvoie que 1 000 objets à la fois. Par conséquent, si votre compartiment contient environ 10 000 objets, le paginateur devra effectuer 10 requêtes au total. Lorsque vous parcourez les résultats, la première demande est exécutée lorsque vous démarrez l'itération, la deuxième lors de la deuxième itération de la boucle, et ainsi de suite.

Énumération des données à partir des résultats

Les objets de programme de pagination possèdent une méthode appelée search(), ce qui vous permet de créer des itérateurs pour les données dans un ensemble de résultats. Lorsque vous appelez search(), fournissez une expression JMESPath pour spécifier les données à extraire. Appeler search() renvoie un itérateur qui génère les résultats de l'expression sur chaque page de résultats. Ceci est évalué lentement, à mesure que vous parcourez l'itérateur renvoyé.

L'exemple suivant est équivalent à l'exemple de code précédent, mais utilise la méthode ResultPaginator::search() pour être plus concis.

$results = $s3Client->getPaginator('ListObjects', [
    'Bucket' => 'my-bucket'
]);

foreach ($results->search('Contents[].Key') as $key) {
    echo $key . "\n";
}

Les expressions JMESPath vous permettent de réaliser des opérations assez complexes. Par exemple, si vous souhaitez imprimer toutes les clés d'objet et les préfixes communs (par ex., faire un ls d'un compartiment), vous pouvez effectuer les opérations suivantes.

// List all prefixes ("directories") and objects ("files") in the bucket
$results = $s3Client->getPaginator('ListObjects', [
    'Bucket'    => 'my-bucket',
    'Delimiter' => '/'
]);

$expression = '[CommonPrefixes[].Prefix, Contents[].Key][]';
foreach ($results->search($expression) as $item) {
    echo $item . "\n";
}

Pagination asynchrone

Vous pouvez itérer sur les résultats d'une programme de pagination de manière asynchrone en fournissant un rappel pour la méthode each() d'une Aws\ResultPaginator. La méthode de rappel est appelée pour chaque valeur générée par le programme de pagination.

$results = $s3Client->getPaginator('ListObjects', [
    'Bucket' => 'my-bucket'
]);

$promise = $results->each(function ($result) {
    echo 'Got ' . var_export($result, true) . "\n";
});

Une valeur de retour non nulle provenant du rappel sera générée par la promesse basée sur la coroutine sous-jacente. Cela signifie que vous pouvez renvoyer les promesses provenant du rappel qui doivent être résolues avant de continuer l'itération sur les éléments restants, en fusionnant principalement d'autres promesses à l'itération. La dernière valeur non nulle renvoyée par le rappel est le résultat qui répond à la promesse de toutes les promesses en aval. Si la dernière valeur renvoyée est une promesse, la résolution de cette promesse est le résultat qui répond ou rejette les promesses en aval.

// Delete all keys that end with "Foo"
$promise = $results->each(function ($result) use ($s3Client) {
    if (substr($result['Key'], -3) === 'Foo') {
        // Merge this promise into the iterator
        return $s3Client->deleteAsync([
            'Bucket' => 'my-bucket',
            'Key'    => 'Foo'
        ]);
    }
});

$promise
    ->then(function ($result) {
        // Result would be the last result to the deleteAsync operation
    })
    ->otherwise(function ($reason) {
        // Reason would be an exception that was encountered either in the
        // call to deleteAsync or calls performed while iterating
    });

// Forcing a synchronous wait will also wait on all of the deleteAsync calls
$promise->wait();