Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Upgrade dari Versi 2 AWS SDK for PHP

Topik ini menunjukkan cara memigrasi kode Anda untuk menggunakan versi 3 AWS SDK for PHP dan bagaimana versi baru berbeda dari versi 2 SDK.

Pengantar

Versi 3 AWS SDK for PHP merupakan upaya yang signifikan untuk meningkatkan kemampuan SDK, menggabungkan lebih dari dua tahun umpan balik pelanggan, meningkatkan dependensi kami, meningkatkan kinerja, dan mengadopsi standar PHP terbaru.

Apa yang Baru di Versi 3?

Versi 3 dari AWS SDK for PHP mengikuti standar PSR-4 dan PSR-7 dan akan mengikuti standar ke SemVerdepan.

Fitur baru lainnya termasuk

Lapisan HTTP terpisah

Permintaan asinkron

Apa yang Berbeda dari Versi 2?

Dependensi Proyek Diperbarui

Dependensi SDK telah berubah dalam versi ini.

Opsi Wilayah dan Versi Sekarang Diperlukan

Ketika instantiating klien untuk layanan apapun, tentukan 'region' dan 'version' pilihan. Dalam versi 2 dariAWS SDK for PHP, 'version' benar-benar opsional, dan 'region' kadang-kadang opsional. Dalam versi 3, keduanya selalu diperlukan. Menjadi eksplisit tentang kedua opsi ini memungkinkan Anda untuk mengunci versi API dan AWS Wilayah yang Anda kodekan. Ketika versi API baru dibuat atau AWS Wilayah baru tersedia, Anda akan diisolasi dari kemungkinan melanggar perubahan sampai Anda siap untuk secara eksplisit memperbarui konfigurasi Anda.

Instantiation Klien Menggunakan Konstruktor

Dalam versi 3 dariAWS SDK for PHP, cara Anda instantiate klien telah berubah. Alih-alih factory metode dalam versi 2, Anda hanya dapat instantiate klien dengan menggunakan kata kunci. new

use Aws\DynamoDb\DynamoDbClient;

// Version 2 style
$client = DynamoDbClient::factory([
    'region'  => 'us-east-2'
]);

// Version 3 style
$client = new DynamoDbClient([
    'region'  => 'us-east-2',
    'version' => '2012-08-10'
]);

Konfigurasi Klien Telah Berubah

Opsi konfigurasi klien di versi 3 dari AWS SDK for PHP telah berubah sedikit dari versi 2. Lihat halaman Konfigurasi untuk AWS SDK for PHP Versi 3 untuk deskripsi semua opsi yang didukung.

Objek Sdk

Versi 3 dari AWS SDK for PHP memperkenalkan Aws\Sdk objek sebagai pengganti. Aws\Common\Aws SdkObjek bertindak sebagai pabrik klien dan digunakan untuk mengelola opsi konfigurasi bersama di beberapa klien.

Meskipun Aws kelas dalam versi 2 SDK bekerja seperti locator layanan (selalu mengembalikan instance klien yang sama), Sdk kelas dalam versi 3 mengembalikan instance baru klien setiap kali digunakan.

SdkObjek juga tidak mendukung format file konfigurasi yang sama dari SDK versi 2. Format konfigurasi itu khusus untuk Guzzle 3 dan sekarang sudah usang. Konfigurasi dapat dilakukan lebih sederhana dengan array dasar, dan didokumentasikan dalam Menggunakan Kelas Sdk.

Beberapa Hasil API Telah Berubah

Untuk memberikan konsistensi dalam cara SDK mengurai hasil operasi API, Amazon, Amazon RDSElastiCache, dan Amazon Redshift sekarang memiliki elemen pembungkus tambahan pada beberapa respons API.

Misalnya, memanggil DescribeEngineDefaultParametershasil Amazon RDS di versi 3 sekarang menyertakan elemen “EngineDefaults” pembungkus. Dalam versi 2, elemen ini tidak ada.

$client = new Aws\Rds\RdsClient([
    'region'  => 'us-west-1',
    'version' => '2014-09-01'
]);

// Version 2
$result = $client->describeEngineDefaultParameters();
$family = $result['DBParameterGroupFamily'];
$marker = $result['Marker'];

// Version 3
$result = $client->describeEngineDefaultParameters();
$family = $result['EngineDefaults']['DBParameterGroupFamily'];
$marker = $result['EngineDefaults']['Marker'];

Operasi berikut dipengaruhi dan sekarang mengandung elemen pembungkus dalam output dari hasil (disediakan di bawah ini dalam tanda kurung):

Kelas Enum Telah Dihapus

Kami telah menghapus Enum kelas (misalnya,Aws\S3\Enum\CannedAcl) yang ada di versi 2 dariAWS SDK for PHP. Enum adalah kelas konkret dalam API publik SDK yang berisi konstanta yang mewakili kelompok nilai parameter yang valid. Karena enum ini khusus untuk versi API, dapat berubah seiring waktu, dapat bertentangan dengan kata-kata cadangan PHP, dan akhirnya tidak terlalu berguna, kami telah menghapusnya dalam versi 3. Ini mendukung sifat agnostik versi berbasis data dan API versi 3.

Alih-alih menggunakan nilai dari Enum objek, gunakan nilai literal secara langsung (misalnya, CannedAcl::PUBLIC_READ →'public-read').

Fine-Grained Exception Kelas Telah Dihapus

Kami telah menghapus kelas pengecualian berbutir halus yang ada di setiap ruang nama layanan (misalnya,Aws\Rds\Exception\{SpecificError}Exception) karena alasan yang sangat mirip bahwa kami menghapus Enum. Pengecualian yang dilemparkan oleh layanan atau operasi bergantung pada versi API mana yang digunakan (mereka dapat berubah dari versi ke versi). Juga, daftar lengkap pengecualian yang dapat dilemparkan oleh operasi tertentu tidak tersedia, yang membuat kelas pengecualian berbutir halus versi 2 tidak lengkap.

Menangani kesalahan dengan menangkap kelas pengecualian root untuk setiap layanan (misalnya,Aws\Rds\Exception\RdsException). Anda dapat menggunakan getAwsErrorCode() metode pengecualian untuk memeriksa kode kesalahan tertentu. Ini secara fungsional setara dengan menangkap kelas pengecualian yang berbeda, tetapi menyediakan fungsi itu tanpa menambahkan mengasapi ke SDK.

Kelas Fasad Statis Telah Dihapus

Dalam versi 2 dariAWS SDK for PHP, ada fitur jelas terinspirasi oleh Laravel yang memungkinkan Anda untuk memanggil enableFacades() Aws kelas untuk mengaktifkan akses statis ke berbagai klien layanan. Fitur ini bertentangan dengan praktik terbaik PHP, dan kami berhenti mendokumentasikannya lebih dari setahun yang lalu. Di versi 3, fitur ini dihapus sepenuhnya. Ambil objek klien Anda dari Aws\Sdk objek dan menggunakannya sebagai contoh objek, bukan kelas statis.

Paginator menggantikan iterator

Versi 2 dari AWS SDK for PHP memiliki fitur bernama* iterator*. Ini adalah objek yang digunakan untuk iterasi atas hasil paginasi. Satu keluhan yang kami miliki tentang ini adalah bahwa mereka tidak cukup fleksibel, karena iterator hanya memancarkan nilai-nilai tertentu dari setiap hasil. Jika ada nilai lain yang Anda butuhkan dari hasil, Anda hanya bisa mengambilnya melalui event listener.

Dalam versi 3, iterator telah diganti dengan Paginators. Tujuan mereka serupa, tetapi paginator lebih fleksibel. Hal ini karena mereka menghasilkan objek hasil bukan nilai-nilai dari respon.

Contoh berikut menunjukkan bagaimana paginator berbeda dari iterator, dengan menunjukkan bagaimana untuk mengambil hasil paginasi untuk S3 ListObjects operasi di kedua versi 2 dan versi 3.

// Version 2
$objects = $s3Client->getIterator('ListObjects', ['Bucket' => 'my-bucket']);
foreach ($objects as $object) {
    echo $object['Key'] . "\n";
}

// Version 3
$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-bucket']);
foreach ($results as $result) {
    // You can extract any data that you want from the result.
    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
}

objek Paginator memiliki search() metode yang memungkinkan Anda untuk menggunakan ekspresi JMesPath untuk mengekstrak data lebih mudah dari hasil set.

$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-bucket']);
foreach ($results->search('Contents[].Key') as $key) {
    echo $key . "\n";
}

Banyak Abstraksi Tingkat Tinggi Telah Berubah

Secara umum, banyak abstraksi tingkat tinggi (objek pembantu khusus layanan, selain dari klien) telah diperbaiki atau diperbarui. Beberapa bahkan telah dihapus.

Membandingkan Sampel Kode dari Kedua Versi SDK

Contoh berikut menunjukkan beberapa cara di mana menggunakan versi 3 AWS SDK for PHP mungkin berbeda dari versi 2.

Contoh: Operasi Amazon S3 ListObjects

Dari SDK Versi 2

<?php

require '/path/to/vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\S3\Exception\S3Exception;

$s3 = S3Client::factory([
    'profile' => 'my-credential-profile',
    'region'  => 'us-east-1'
]);

try {
    $result = $s3->listObjects([
        'Bucket' => 'my-bucket-name',
        'Key'    => 'my-object-key'
    ]);

    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
} catch (S3Exception $e) {
    echo $e->getMessage() . "\n";
}

Dari SDK Versi 3

Perbedaan utama:

<?php

require '/path/to/vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\S3\Exception\S3Exception;

$s3 = new S3Client([
    'profile' => 'my-credential-profile',
    'region'  => 'us-east-1',
    'version' => '2006-03-01'
]);

try {
    $result = $s3->listObjects([
        'Bucket' => 'my-bucket-name',
        'Key'    => 'my-object-key'
    ]);

    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
} catch (S3Exception $e) {
    echo $e->getMessage() . "\n";
}

Contoh: Instantiating Klien dengan Konfigurasi global

Dari SDK Versi 2

<?php return array(
    'includes' => array('_aws'),
    'services' => array(
        'default_settings' => array(
            'params' => array(
                'profile' => 'my_profile',
                'region'  => 'us-east-1'
            )
        ),
        'dynamodb' => array(
            'extends' => 'dynamodb',
            'params' => array(
                'region'  => 'us-west-2'
            )
        ),
    )
);

<?php

require '/path/to/vendor/autoload.php';

use Aws\Common\Aws;

$aws = Aws::factory('path/to/my/config.php');

$sqs = $aws->get('sqs');
// Note: SQS client will be configured for us-east-1.

$dynamodb = $aws->get('dynamodb');
// Note: DynamoDB client will be configured for us-west-2.

Dari SDK Versi 3

Perbedaan utama:

<?php

require '/path/to/vendor/autoload.php';

$sdk = new Aws\Sdk([
    'profile' => 'my_profile',
    'region' => 'us-east-1',
    'version' => 'latest',
    'DynamoDb' => [
        'region' => 'us-west-2',
    ],
]);

$sqs = $sdk->createSqs();
// Note: Amazon SQS client will be configured for us-east-1.

$dynamodb = $sdk->createDynamoDb();
// Note: DynamoDB client will be configured for us-west-2.