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

Pola penggunaan dasar AWS SDK for PHP Versi 3

Topik ini berfokus pada pola penggunaan dasarAWS SDK for PHP.

Prasyarat

Termasuk SDK dalam kode Anda

Apa pun teknik yang Anda gunakan untuk menginstal SDK, Anda dapat menyertakan SDK dalam kode Anda hanya dengan satu require pernyataan. Lihat tabel berikut untuk kode PHP yang paling sesuai dengan teknik instalasi Anda. Ganti setiap instance /path/to/ dengan jalur aktual di sistem Anda.

Dalam topik ini, kita mengasumsikan metode instalasi Composer. Jika Anda menggunakan metode instalasi yang berbeda, Anda dapat merujuk kembali ke bagian ini untuk menemukan require kode yang benar untuk digunakan.

Ringkasan penggunaan

Untuk menggunakan SDK untuk berinteraksi dengan AWS layanan, buat instance objek Klien. Objek klien memiliki metode yang sesuai dengan operasi di API layanan. Untuk menjalankan operasi tertentu, Anda memanggil metode yang sesuai. Metode ini mengembalikan objek Result seperti array pada keberhasilan, atau melempar Exception pada kegagalan.

Membuat klien

Anda dapat membuat klien dengan meneruskan array pilihan asosiatif ke konstruktor klien.

Impor

require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Exception\AwsException;

Kode Sampel

//Create an S3Client
$s3 = new Aws\S3\S3Client([
    'region' => 'us-east-2'  // Since version 3.277.10 of the SDK,
]);                          // the 'version' parameter defaults to 'latest'.

Informasi tentang parameter “versi” opsional tersedia di topik opsi konfigurasi.

Perhatikan bahwa kami tidak secara eksplisit memberikan kredensyal kepada klien. Itu karena SDK harus mendeteksi kredensil dari variabel lingkungan, Berbagi config dan credentials file di direktori HOME Anda, kredensial profil instans AWS Identity and Access Management (IAM), atau penyedia kredensi.

Semua opsi konfigurasi klien umum dijelaskan secara rinci diKonfigurasi untuk AWS SDK for PHP Versi 3. Array opsi yang diberikan kepada klien dapat bervariasi berdasarkan klien mana yang Anda buat. Opsi konfigurasi klien kustom ini dijelaskan dalam dokumentasi API untuk setiap klien.

Menggunakan Sdk Kelas

Aws\SdkKelas bertindak sebagai pabrik klien dan digunakan untuk mengelola opsi konfigurasi bersama di beberapa klien. Banyak opsi yang dapat diberikan kepada konstruktor klien tertentu juga dapat diberikan ke Aws\Sdk kelas. Opsi ini kemudian diterapkan ke setiap konstruktor klien.

Impor

require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Exception\AwsException;

Kode Sampel

// The same options that can be provided to a specific client constructor can also be supplied to the Aws\Sdk class.
// Use the us-west-2 region and latest version of each client.
$sharedConfig = [
    'region' => 'us-west-2'
];
// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk($sharedConfig);
// Create an Amazon S3 client using the shared configuration data.
$client = $sdk->createS3();

Opsi yang dibagikan di semua klien ditempatkan dalam pasangan nilai kunci tingkat root. Data konfigurasi khusus layanan dapat disediakan dalam kunci yang sama dengan namespace layanan (misalnya, “S3", “”, dll.)DynamoDb.

$sdk = new Aws\Sdk([
    'region'   => 'us-west-2',
    'DynamoDb' => [
        'region' => 'eu-central-1'
    ]
]);

// Creating an Amazon DynamoDb client will use the "eu-central-1" AWS Region
$client = $sdk->createDynamoDb();

Nilai konfigurasi khusus layanan adalah gabungan dari nilai spesifik layanan dan nilai tingkat root (yaitu, nilai khusus layanan digabungkan secara dangkal ke nilai tingkat root).

Menjalankan operasi layanan

Anda dapat menjalankan operasi layanan dengan memanggil metode dengan nama yang sama pada objek klien. Misalnya, untuk melakukan PutObjectoperasi Amazon S3, Anda harus memanggil metode. Aws\S3\S3Client::putObject()

Impor

require 'vendor/autoload.php';

use Aws\S3\S3Client;

Kode Sampel

// Use the us-east-2 region and latest version of each client.
$sharedConfig = [
    'profile' => 'default',
    'region' => 'us-east-2'
];

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk($sharedConfig);

// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();

// Send a PutObject request and get the result object.
$result = $s3Client->putObject([
    'Bucket' => 'my-bucket',
    'Key' => 'my-key',
    'Body' => 'this is the body!'
]);

// Download the contents of the object.
$result = $s3Client->getObject([
    'Bucket' => 'my-bucket',
    'Key' => 'my-key'
]);

// Print the body of the result by indexing into the result object.
echo $result['Body'];

Operasi yang tersedia untuk klien dan struktur input dan output didefinisikan pada runtime berdasarkan file deskripsi layanan. Saat membuat klien, Anda harus memberikan versi (misalnya, “2006-03-01" atau “terbaru”). SDK menemukan file konfigurasi yang sesuai berdasarkan versi yang disediakan.

Metode operasi seperti putObject() semua menerima argumen tunggal, array asosiatif yang mewakili parameter operasi. Struktur array ini (dan struktur objek hasil) didefinisikan untuk setiap operasi dalam Dokumentasi API SDK (misalnya, lihat dokumen API untuk operasi putObject).

Opsi penangan HTTP

Anda juga dapat menyempurnakan bagaimana penangan HTTP yang mendasari mengeksekusi permintaan dengan menggunakan parameter khusus. @http Opsi yang dapat Anda sertakan dalam @http parameter sama dengan yang dapat Anda atur saat Anda membuat instance klien dengan opsi klien “http”.

// Send the request through a proxy
$result = $s3Client->putObject([
    'Bucket' => 'my-bucket',
    'Key'    => 'my-key',
    'Body'   => 'this is the body!',
    '@http'  => [
        'proxy' => 'http://192.168.16.1:10'
    ]
]);

Permintaan asinkron

Anda dapat mengirim perintah secara bersamaan menggunakan fitur asinkron SDK. Anda dapat mengirim permintaan secara asinkron dengan akhiran nama operasi dengan. Async Ini memulai permintaan dan mengembalikan janji. Janji dipenuhi dengan objek hasil pada keberhasilan atau ditolak dengan pengecualian pada kegagalan. Ini memungkinkan Anda untuk membuat beberapa janji dan meminta mereka mengirim permintaan HTTP secara bersamaan ketika penangan HTTP yang mendasari mentransfer permintaan.

Impor

require 'vendor/autoload.php';
use Aws\S3\S3Client;
use Aws\Exception\AwsException;

Kode Sampel

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk([
    'region'   => 'us-west-2'
]);
// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();
//Listing all S3 Bucket
$CompleteSynchronously = $s3Client->listBucketsAsync();
// Block until the result is ready.
$CompleteSynchronously = $CompleteSynchronously->wait();

Anda dapat memaksakan janji untuk menyelesaikan secara serempak dengan menggunakan wait metode janji. Memaksa janji untuk menyelesaikan juga “membuka” status janji secara default, yang berarti itu akan mengembalikan hasil janji atau membuang pengecualian yang ditemui. Saat memanggil wait() janji, proses memblokir sampai permintaan HTTP selesai dan hasilnya diisi atau pengecualian dilemparkan.

Saat menggunakan SDK dengan pustaka loop peristiwa, jangan blokir hasil. Sebagai gantinya, gunakan then() metode hasil untuk mengakses janji yang diselesaikan atau ditolak saat operasi selesai.

Impor

require 'vendor/autoload.php';
use Aws\S3\S3Client;
use Aws\Exception\AwsException;

Kode Sampel

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk([
    'region'   => 'us-west-2'
]);
// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();

$promise = $s3Client->listBucketsAsync();
$promise
    ->then(function ($result) {
        echo 'Got a result: ' . var_export($result, true);
    })
    ->otherwise(function ($reason) {
        echo 'Encountered an error: ' . $reason->getMessage();
    });

Bekerja dengan objek hasil

Mengeksekusi operasi yang berhasil mengembalikan Aws\Result objek. Alih-alih mengembalikan data XHTML atau JSON mentah dari suatu layanan, SDK memaksa data respons ke dalam struktur array asosiatif. Ini menormalkan beberapa aspek data berdasarkan pengetahuannya tentang layanan spesifik dan struktur respons yang mendasarinya.

Anda dapat mengakses data dari AWSResult objek seperti array PHP asosiatif.

Impor

require 'vendor/autoload.php';
use Aws\S3\S3Client;
use Aws\Exception\AwsException;

Kode Sampel

// Use the us-east-2 region and latest version of each client.
$sharedConfig = [
    'profile' => 'default',
    'region' => 'us-east-2',
];

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk($sharedConfig);

// Use an Aws\Sdk class to create the S3Client object.
$s3 = $sdk->createS3();
$result = $s3->listBuckets();
foreach ($result['Buckets'] as $bucket) {
    echo $bucket['Name'] . "\n";
}

// Convert the result object to a PHP array
$array = $result->toArray();

Isi objek hasil tergantung pada operasi yang dijalankan dan versi layanan. Struktur hasil dari setiap operasi API didokumentasikan dalam dokumen API untuk setiap operasi.

SDK terintegrasi dengan JMESPath, DSL yang digunakan untuk mencari dan memanipulasi data JSON atau, dalam kasus kami, array PHP. Objek hasil berisi search() metode yang dapat Anda gunakan untuk mengekstrak data secara lebih deklaratif dari hasilnya.

Kode Sampel

$s3 = $sdk->createS3();
$result = $s3->listBuckets();

$names = $result->search('Buckets[].Name');

Menangani kesalahan

Penanganan Kesalahan Sinkron

Jika terjadi kesalahan saat melakukan operasi, pengecualian dilemparkan. Untuk alasan ini, jika Anda perlu menangani kesalahan dalam kode Anda, gunakantry/catchblok di sekitar operasi Anda. SDK menampilkan pengecualian khusus layanan saat terjadi kesalahan.

Contoh berikut menggunakanAws\S3\S3Client. Jika ada kesalahan, pengecualian yang dilemparkan akan menjadi tipeAws\S3\Exception\S3Exception. Semua pengecualian khusus layanan yang dilemparkan SDK diperluas dari kelas. Aws\Exception\AwsException Kelas ini berisi informasi yang berguna tentang kegagalan, termasuk request-id, kode kesalahan, dan jenis kesalahan. Catatan untuk beberapa layanan yang mendukungnya, data respons dipaksa menjadi struktur array asosiatif (mirip dengan Aws\Result objek), yang dapat diakses seperti array asosiatif PHP normal. toArray()Metode ini akan mengembalikan data tersebut, jika ada.

Impor

require 'vendor/autoload.php';

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

Kode Sampel

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk([
    'region'   => 'us-west-2'
]);

// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();

try {
    $s3Client->createBucket(['Bucket' => 'my-bucket']);
} catch (S3Exception $e) {
    // Catch an S3 specific exception.
    echo $e->getMessage();
} catch (AwsException $e) {
    // This catches the more generic AwsException. You can grab information
    // from the exception using methods of the exception object.
    echo $e->getAwsRequestId() . "\n";
    echo $e->getAwsErrorType() . "\n";
    echo $e->getAwsErrorCode() . "\n";

    // This dumps any modeled response data, if supported by the service
    // Specific members can be accessed directly (e.g. $e['MemberName'])
    var_dump($e->toArray());
}

Penanganan kesalahan asinkron

Pengecualian tidak dilemparkan saat mengirim permintaan asinkron. Sebagai gantinya, Anda harus menggunakan then() atau otherwise() metode janji yang dikembalikan untuk menerima hasil atau kesalahan.

Impor

require 'vendor/autoload.php';

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

Kode Sampel

//Asynchronous Error Handling
$promise = $s3Client->createBucketAsync(['Bucket' => 'my-bucket']);
$promise->otherwise(function ($reason) {
    var_dump($reason);
});

// This does the same thing as the "otherwise" function.
$promise->then(null, function ($reason) {
    var_dump($reason);
});

Anda dapat “membuka” janji dan menyebabkan pengecualian dilemparkan sebagai gantinya.

Impor

require 'vendor/autoload.php';

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

Kode Sampel

$promise = $s3Client->createBucketAsync(['Bucket' => 'my-bucket']);

//throw exception
try {
    $result = $promise->wait();
} catch (S3Exception $e) {
    echo $e->getMessage();
}