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.

Objets de commande dans la AWS SDK for PHP version 3

AWS SDK for PHP Utilise le modèle de commande pour encapsuler les paramètres et le gestionnaire qui seront utilisés pour transférer une HTTP demande ultérieurement.

Utilisation implicite de commandes

Si vous examinez une classe de clients, vous pouvez constater que les méthodes correspondant aux API opérations n'existent pas réellement. Elles sont implémentées à l'aide de la méthode magique __call(). Ces pseudo-méthodes sont en fait des raccourcis qui encapsulent l'utilisation des objets SDK de commande par les utilisateurs.

Vous n'avez généralement pas besoin d'interagir directement avec les objets de commande. Lorsque vous appelez des méthodes telles que Aws\S3\S3Client::putObject()SDK, le crée un Aws\CommandInterface objet en fonction des paramètres fournis, exécute la commande et renvoie un Aws\ResultInterface objet rempli (ou lance une exception en cas d'erreur). Un flux similaire se produit lors de l'appel de l'une des Async méthodes d'un client (par exemple,Aws\S3\S3Client::putObjectAsync()) : le client crée une commande basée sur les paramètres fournis, sérialise une HTTP demande, initie la demande et renvoie une promesse.

Les exemples suivants sont équivalents d'un point de vue fonctionnel.

$s3Client = new Aws\S3\S3Client([
    'version' => '2006-03-01',
    'region'  => 'us-standard'
]);

$params = [
    'Bucket' => 'foo',
    'Key'    => 'baz',
    'Body'   => 'bar'
];

// Using operation methods creates a command implicitly
$result = $s3Client->putObject($params);

// Using commands explicitly
$command = $s3Client->getCommand('PutObject', $params);
$result = $s3Client->execute($command);

Paramètres de commande

Toutes les commandes prennent en charge quelques paramètres spéciaux qui ne font pas partie du comportement d'un service API mais contrôlent SDK son comportement.

@http

À l'aide de ce paramètre, il est possible d'affiner la façon dont le HTTP gestionnaire sous-jacent exécute la demande. Vous pouvez inclure dans le paramètre @http les mêmes options que celles définies lors de l'instanciation du client à l'aide de l'option client « http ».

// Configures the command to be delayed by 500 milliseconds
$command['@http'] = [
    'delay' => 500,
];

@retries

Comme l'option client « retries », @retries (nouvelles tentatives) contrôle le nombre de fois où une commande peut être relancée avant que celle-ci ne soit considérée comme ayant échoué. Définissez-la sur 0 pour désactiver les nouvelles tentatives.

// Disable retries
$command['@retries'] = 0;

Création d'objets de commande

Vous pouvez créer une commande à l'aide de la méthode getCommand() d'un client. Il n'exécute ou ne transfère pas immédiatement une HTTP demande, mais n'est exécuté que lorsqu'elle est transmise à la execute() méthode du client. Vous avez ainsi la possibilité de modifier l'objet de commande avant d'exécuter la commande.

$command = $s3Client->getCommand('ListObjects');
$command['MaxKeys'] = 50;
$command['Prefix'] = 'foo/baz/';
$result = $s3Client->execute($command);

// You can also modify parameters
$command = $s3Client->getCommand('ListObjects', [
    'MaxKeys' => 50,
    'Prefix'  => 'foo/baz/',
]);
$command['MaxKeys'] = 100;
$result = $s3Client->execute($command);

Commande HandlerList

Lorsqu'une commande est créée à partir d'un client, elle reçoit un clone de l'objet Aws\HandlerList du client. La commande reçoit un clone de la liste des gestionnaires du client pour autoriser une commande à utiliser un intergiciel et des gestionnaires personnalisés qui n'affectent pas les autres commandes exécutées par le client.

Cela signifie que vous pouvez utiliser un HTTP client différent par commande (par exempleAws\MockHandler) et ajouter un comportement personnalisé par commande via un intergiciel. L'exemple suivant utilise a MockHandler pour créer des résultats fictifs au lieu d'envoyer des HTTP demandes réelles.

use Aws\Result;
use Aws\MockHandler;

// Create a mock handler
$mock = new MockHandler();
// Enqueue a mock result to the handler
$mock->append(new Result(['foo' => 'bar']));
// Create a "ListObjects" command
$command = $s3Client->getCommand('ListObjects');
// Associate the mock handler with the command
$command->getHandlerList()->setHandler($mock);
// Executing the command will use the mock handler, which returns the
// mocked result object
$result = $client->execute($command);

echo $result['foo']; // Outputs 'bar'

En plus de changer le gestionnaire utilisé par la commande, vous pouvez également injecter un intergiciel personnalisé dans la commande. L'exemple suivant utilise l'intergiciel tap, qui fonctionne comme observateur dans la liste des gestionnaires.

use Aws\CommandInterface;
use Aws\Middleware;
use Psr\Http\Message\RequestInterface;

$command = $s3Client->getCommand('ListObjects');
$list = $command->getHandlerList();

// Create a middleware that just dumps the command and request that is
// about to be sent
$middleware = Middleware::tap(
    function (CommandInterface $command, RequestInterface $request) {
        var_dump($command->toArray());
        var_dump($request);
    }
);

// Append the middleware to the "sign" step of the handler list. The sign
// step is the last step before transferring an HTTP request.
$list->append('sign', $middleware);

// Now transfer the command and see the var_dump data
$s3Client->execute($command);

CommandPool

Le Aws\CommandPool vous permet d'exécuter des commandes simultanément à l'aide d'un itérateur générant des objets Aws\CommandInterface. Le CommandPool veille à ce qu'un nombre constant de commandes soient exécutées simultanément pendant l'itération sur les commandes du groupe (à mesure que les commandes se terminent, d'autres sont exécutées pour garantir une taille de groupe constante).

Voici un exemple très simple illustrant l'envoi de quelques commandes à l'aide d'un CommandPool.

use Aws\S3\S3Client;
use Aws\CommandPool;

// Create the client
$client = new S3Client([
    'region'  => 'us-standard',
    'version' => '2006-03-01'
]);

$bucket = 'example';
$commands = [
    $client->getCommand('HeadObject', ['Bucket' => $bucket, 'Key' => 'a']),
    $client->getCommand('HeadObject', ['Bucket' => $bucket, 'Key' => 'b']),
    $client->getCommand('HeadObject', ['Bucket' => $bucket, 'Key' => 'c'])
];

$pool = new CommandPool($client, $commands);

// Initiate the pool transfers
$promise = $pool->promise();

// Force the pool to complete synchronously
$promise->wait();

Cet exemple est relativement peu puissant pour le CommandPool. Essayons un exemple plus complexe. Supposons que vous souhaitiez télécharger des fichiers sur disque dans un compartiment Amazon S3. Pour obtenir une liste de fichiers à partir du disque, nous pouvons utiliser PHP DirectoryIterator Cet itérateur génère des objets SplFileInfo. Le CommandPool accepte un itérateur générant des objets Aws\CommandInterface. Nous devons donc mapper les objets SplFileInfo pour renvoyer des objets Aws\CommandInterface.

<?php
require 'vendor/autoload.php';

use Aws\Exception\AwsException;
use Aws\S3\S3Client;
use Aws\CommandPool;
use Aws\CommandInterface;
use Aws\ResultInterface;
use GuzzleHttp\Promise\PromiseInterface;

// Create the client
$client = new S3Client([
    'region'  => 'us-standard',
    'version' => '2006-03-01'
]);

$fromDir = '/path/to/dir';
$toBucket = 'amzn-s3-demo-bucket';

// Create an iterator that yields files from a directory
$files = new DirectoryIterator($fromDir);

// Create a generator that converts the SplFileInfo objects into
// Aws\CommandInterface objects. This generator accepts the iterator that
// yields files and the name of the bucket to upload the files to.
$commandGenerator = function (\Iterator $files, $bucket) use ($client) {
    foreach ($files as $file) {
        // Skip "." and ".." files
        if ($file->isDot()) {
            continue;
        }
        $filename = $file->getPath() . '/' . $file->getFilename();
        // Yield a command that is executed by the pool
        yield $client->getCommand('PutObject', [
            'Bucket' => $bucket,
            'Key'    => $file->getBaseName(),
            'Body'   => fopen($filename, 'r')
        ]);
    }
};

// Now create the generator using the files iterator
$commands = $commandGenerator($files, $toBucket);

// Create a pool and provide an optional array of configuration
$pool = new CommandPool($client, $commands, [
    // Only send 5 files at a time (this is set to 25 by default)
    'concurrency' => 5,
    // Invoke this function before executing each command
    'before' => function (CommandInterface $cmd, $iterKey) {
        echo "About to send {$iterKey}: "
            . print_r($cmd->toArray(), true) . "\n";
    },
    // Invoke this function for each successful transfer
    'fulfilled' => function (
        ResultInterface $result,
        $iterKey,
        PromiseInterface $aggregatePromise
    ) {
        echo "Completed {$iterKey}: {$result}\n";
    },
    // Invoke this function for each failed transfer
    'rejected' => function (
        AwsException $reason,
        $iterKey,
        PromiseInterface $aggregatePromise
    ) {
        echo "Failed {$iterKey}: {$reason}\n";
    },
]);

// Initiate the pool transfers
$promise = $pool->promise();

// Force the pool to complete synchronously
$promise->wait();

// Or you can chain the calls off of the pool
$promise->then(function() { echo "Done\n"; });

Configuration CommandPool

Le constructeur Aws\CommandPool accepte différentes options de configuration.

Collecte manuelle des déchets entre les commandes

Si vous atteignez la limite de mémoire avec de grands pools de commandes, cela peut être dû à des références cycliques générées par le fait que le ramasse-miettes ne les a SDK pas encore PHPcollectées lorsque votre limite de mémoire a été atteinte. L'appel manuel de l'algorithme de nettoyage entre les commandes peut permettre le traitement des cycles avant que cette limite ne soit atteinte. L'exemple suivant crée un CommandPool qui appelle l'algorithme de nettoyage en utilisant un rappel avant l'envoi de chaque commande. Notez que l'appel du nettoyage de mémoire représente un coût en termes de performances, et que l'utilisation optimale dépendra de votre cas d'utilisation et de l'environnement.

$pool = new CommandPool($client, $commands, [
    'concurrency' => 25,
    'before' => function (CommandInterface $cmd, $iterKey) {
        gc_collect_cycles();
    }
]);