Penangan dan middleware diAWS SDK for PHPVersi 3

Mekanisme utama untuk memperpanjangAWS SDK for PHPadalah melaluiHandlerdanmiddleware. Setiap kelas klien SDK memilikiAws\HandlerListcontoh yang dapat diakses melaluigetHandlerList()metode klien. Anda dapat mengambil klienHandlerListdan memodifikasinya untuk menambah atau menghapus perilaku klien.

Handler

Sebuah handler adalah fungsi yang melakukan transformasi aktual dari perintah dan permintaan menjadi hasil. Sebuah handler biasanya mengirimkan permintaan HTTP. Penangan dapat disusun dengan middleware untuk menambah perilaku mereka. Sebuah handler adalah fungsi yang menerimaAws\CommandInterfacedanPsr\Http\Message\RequestInterfacedan mengembalikan janji yang dipenuhi denganAws\ResultInterfaceatau ditolak denganAws\Exception\AwsExceptionAlasan.

Berikut adalah handler yang mengembalikan hasil tiruan yang sama untuk setiap panggilan.

use Aws\CommandInterface;
use Aws\Result;
use Psr\Http\Message\RequestInterface;
use GuzzleHttp\Promise;

$myHandler = function (CommandInterface $cmd, RequestInterface $request) {
    $result = new Result(['foo' => 'bar']);
    return Promise\promise_for($result);
};

Anda kemudian dapat menggunakan handler ini dengan klien SDK dengan menyediakanhandlerpilihan dalam konstruktor klien.

// Set the handler of the client in the constructor
$s3 = new Aws\S3\S3Client([
    'region'  => 'us-east-1',
    'version' => '2006-03-01',
    'handler' => $myHandler
]);

Anda juga dapat mengubah handler klien setelah dibangun menggunakansetHandlermetodeAws\ClientInterface.

// Set the handler of the client after it is constructed
$s3->getHandlerList()->setHandler($myHandler);

$multiRegionClient->useCustomHandler($myHandler);

Handler Mock

Sebaiknya gunakanMockHandlersaat menulis tes yang menggunakan SDK. Anda dapat menggunakanAws\MockHandleruntuk mengembalikan hasil yang diejek atau membuang pengecualian tiruan. Anda enqueue hasil atau pengecualian, dan MockHandler dequeues mereka dalam urutan FIFO.

use Aws\Result;
use Aws\MockHandler;
use Aws\DynamoDb\DynamoDbClient;
use Aws\CommandInterface;
use Psr\Http\Message\RequestInterface;
use Aws\Exception\AwsException;

$mock = new MockHandler();

// Return a mocked result
$mock->append(new Result(['foo' => 'bar']));

// You can provide a function to invoke; here we throw a mock exception
$mock->append(function (CommandInterface $cmd, RequestInterface $req) {
    return new AwsException('Mock exception', $cmd);
});

// Create a client with the mock handler
$client = new DynamoDbClient([
    'region'  => 'us-west-2',
    'version' => 'latest',
    'handler' => $mock
]);

// Result object response will contain ['foo' => 'bar']
$result = $client->listTables();

// This will throw the exception that was enqueued
$client->listTables();

Middleware

Middleware adalah tipe khusus dari fungsi tingkat tinggi yang menambah perilaku mentransfer perintah, dan mendelegasikan ke handler “berikutnya”. fungsi Middleware menerimaAws\CommandInterfacedanPsr\Http\Message\RequestInterfacedan kembalilah janji yang dipenuhi denganAws\ResultInterfaceatau ditolak denganAws\Exception\AwsExceptionAlasan.

Middleware adalah fungsi higher-order yang memodifikasi perintah, permintaan, atau hasil saat melewati middleware. Sebuah middleware mengambil bentuk berikut.

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

$middleware = function () {
    return function (callable $handler) use ($fn) {
        return function (
            CommandInterface $command,
            RequestInterface $request = null
        ) use ($handler, $fn) {
            // Do something before calling the next handler
            // ...
            $promise = $fn($command, $request);
            // Do something in the promise after calling the next handler
            // ...
            return $promise;
        };
    };
};

Sebuah middleware menerima perintah untuk mengeksekusi dan objek permintaan opsional. Middleware dapat memilih untuk menambah permintaan dan perintah atau membiarkannya apa adanya. Sebuah middleware kemudian memanggil pegangan berikutnya dalam rantai atau dapat memilih untuk hubungan pendek handler berikutnya dan mengembalikan janji. Promise yang dibuat dengan menerapkan handler berikutnya kemudian dapat ditambah menggunakanthenmetode promise untuk memodifikasi hasil akhirnya atau kesalahan sebelum mengembalikan promise back up tumpukan middleware.

HandlerList

SDK menggunakanAws\HandlerListuntuk mengelola middleware dan penangan yang digunakan saat menjalankan perintah. Setiap klien SDK memilikiHandlerList, dan iniHandlerListdikloning dan ditambahkan ke setiap perintah yang dibuat klien. Anda dapat melampirkan middleware dan handler default untuk digunakan untuk setiap perintah yang dibuat oleh klien dengan menambahkan middleware ke klienHandlerList. Anda dapat menambahkan dan menghapus middleware dari perintah tertentu dengan memodifikasiHandlerListdimiliki oleh perintah tertentu.

SEBUAHHandlerListmerupakan tumpukan middleware yang digunakan untuk membungkuspengurus. Untuk membantu mengelola daftar middleware dan urutan di mana mereka membungkus handler,HandlerListmemecah tumpukan middleware menjadi langkah-langkah bernama yang mewakili bagian dari siklus hidup mentransfer perintah:

Middleware yang tersedia

SDK menyediakan beberapa middleware yang dapat Anda gunakan untuk menambah perilaku klien atau untuk mengamati eksekusi perintah.

MapCommand

KlasterAws\Middleware::mapCommandmiddleware berguna ketika Anda perlu memodifikasi perintah sebelum perintah serial sebagai permintaan HTTP. Misalnya,mapCommanddapat digunakan untuk melakukan validasi atau menambahkan parameter default. KlastermapCommandfungsi menerima callable yang menerimaAws\CommandInterfaceobjek dan mengembalikanAws\CommandInterfaceobjek.

use Aws\Middleware;
use Aws\CommandInterface;

// Here we've omitted the require Bucket parameter. We'll add it in the
// custom middleware.
$command = $s3Client->getCommand('HeadObject', ['Key' => 'test']);

// Apply a custom middleware named "add-param" to the "init" lifecycle step
$command->getHandlerList()->appendInit(
    Middleware::mapCommand(function (CommandInterface $command) {
        $command['Bucket'] = 'mybucket';
        // Be sure to return the command!
        return $command;
    }),
    'add-param'
);

MapRequest

KlasterAws\Middleware::mapRequestmiddleware berguna ketika Anda perlu memodifikasi permintaan setelah serial tapi sebelum dikirim. Misalnya, ini dapat digunakan untuk menambahkan header HTTP khusus ke permintaan. KlastermapRequestfungsi menerima callable yang menerimaPsr\Http\Message\RequestInterfaceargumen dan mengembalikanPsr\Http\Message\RequestInterfaceobjek.

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

// Create a command so that we can access the handler list
$command = $s3Client->getCommand('HeadObject', [
    'Key'    => 'test',
    'Bucket' => 'mybucket'
]);

// Apply a custom middleware named "add-header" to the "build" lifecycle step
$command->getHandlerList()->appendBuild(
    Middleware::mapRequest(function (RequestInterface $request) {
        // Return a new request with the added header
        return $request->withHeader('X-Foo-Baz', 'Bar');
    }),
    'add-header'
);

Sekarang ketika perintah dijalankan, itu dikirim dengan header kustom.

MapResult

KlasterAws\Middleware::mapResultmiddleware berguna ketika Anda perlu memodifikasi hasil eksekusi perintah. KlastermapResultfungsi menerima callable yang menerimaAws\ResultInterfaceargumen dan mengembalikanAws\ResultInterfaceobjek.

use Aws\Middleware;
use Aws\ResultInterface;

$command = $s3Client->getCommand('HeadObject', [
    'Key'    => 'test',
    'Bucket' => 'mybucket'
]);

$command->getHandlerList()->appendSign(
    Middleware::mapResult(function (ResultInterface $result) {
        // Add a custom value to the result
        $result['foo'] = 'bar';
        return $result;
    })
);

Sekarang ketika perintah dijalankan, hasil yang dikembalikan akan berisifooatribut.

riwayat

Klasterhistorymiddleware berguna untuk menguji bahwa SDK menjalankan perintah yang Anda harapkan, mengirim permintaan HTTP yang Anda harapkan, dan menerima hasil yang Anda harapkan. Ini pada dasarnya adalah middleware yang bertindak mirip dengan sejarah browser web.

use Aws\History;
use Aws\Middleware;

$ddb = new Aws\DynamoDb\DynamoDbClient([
    'version' => 'latest',
    'region'  => 'us-west-2'
]);

// Create a history container to store the history data
$history = new History();

// Add the history middleware that uses the history container
$ddb->getHandlerList()->appendSign(Middleware::history($history));

SesiAws\Historysejarah kontainer menyimpan 10 entri secara default sebelum membersihkan entri. Anda dapat menyesuaikan jumlah entri dengan meneruskan jumlah entri untuk bertahan ke konstruktor.

// Create a history container that stores 20 entries
$history = new History(20);

Anda dapat memeriksa wadah sejarah setelah mengeksekusi permintaan yang lulus middleware sejarah.

// The object is countable, returning the number of entries in the container
count($history);

// The object is iterable, yielding each entry in the container
foreach ($history as $entry) {
    // You can access the command that was executed
    var_dump($entry['command']);
    // The request that was serialized and sent
    var_dump($entry['request']);
    // The result that was received (if successful)
    var_dump($entry['result']);
    // The exception that was received (if a failure occurred)
    var_dump($entry['exception']);
}

// You can get the last Aws\CommandInterface that was executed. This method
// will throw an exception if no commands have been executed.
$command = $history->getLastCommand();

// You can get the last request that was serialized. This method will throw an exception
// if no requests have been serialized.
$request = $history->getLastRequest();

// You can get the last return value (an Aws\ResultInterface or Exception).
// The method will throw an exception if no value has been returned for the last
// executed operation (e.g., an async request has not completed).
$result = $history->getLastReturn();

// You can clear out the entries using clear
$history->clear();

keran

Klastertapmiddleware digunakan sebagai pengamat. Anda dapat menggunakan middleware ini untuk memanggil fungsi saat mengirim perintah melalui rantai middleware. Klastertapfungsi menerima callable yang menerimaAws\CommandInterfacedan opsionalPsr\Http\Message\RequestInterfaceyang sedang dieksekusi.

use Aws\Middleware;

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

$handlerList = $s3->getHandlerList();

// Create a tap middleware that observes the command at a specific step
$handlerList->appendInit(
    Middleware::tap(function (CommandInterface $cmd, RequestInterface $req = null) {
        echo 'About to send: ' . $cmd->getName() . "\n";
        if ($req) {
            echo 'HTTP method: ' . $request->getMethod() . "\n";
        }
    }
);

Membuat handler kustom

Sebuah handler hanyalah sebuah fungsi yang menerimaAws\CommandInterfaceobjek danPsr\Http\Message\RequestInterfaceobjek, dan mengembalikanGuzzleHttp\Promise\PromiseInterfaceyang dipenuhi denganAws\ResultInterfaceatau ditolak denganAws\Exception\AwsException.

Meskipun SDK memiliki beberapa@httppilihan, handler hanya perlu tahu bagaimana menggunakan pilihan berikut:

Kecuali opsi ditentukan sebagai opsional, handler HARUS dapat menangani opsi atau HARUS mengembalikan janji yang ditolak.

Selain penanganan spesifik@httppilihan, handler HARUS menambahkanUser-Agentheader yang mengambil bentuk berikut, di mana “3.X” dapat diganti denganAws\Sdk::VERSIONdan”HandlerSpecificData/version...” harus diganti dengan string User-Agent khusus handler Anda.

User-Agent: aws-sdk-php/3.X HandlerSpecificData/version ...