第 3 AWS SDK for PHP 版的基本使用模式 - AWS SDK for PHP
必要條件在您的程式碼SDK中包含 用量摘要建立用戶端使用 Sdk 類別執行服務操作非同步請求使用結果物件處理錯誤

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

第 3 AWS SDK for PHP 版的基本使用模式

本主題聚焦於 AWS SDK for PHP的基本使用模式。

必要條件

在您的程式碼SDK中包含

無論您使用哪種技術來安裝 SDK，您都可以將 包含在程式碼SDK中，只要一個require陳述式即可。如需最適合您安裝技術的PHP程式碼，請參閱下表。以系統上的實際路徑來替換任何 /path/to/ 的執行個體。

安裝技術 需要陳述式

使用 Composer

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

使用 phar

require '/path/to/aws.phar';

使用 ZIP

require '/path/to/aws-autoloader.php';

在本主題中，我們採用 Composer 安裝方法。若您正在使用不同的安裝方法，您可以重新參考本節來尋找要使用的正確 require 程式碼。

用量摘要

若要使用 SDK 與服務互動 AWS ，請初始化用戶端物件。用戶端物件的方法與服務 中的操作對應API。若要執行特定的操作，請呼叫其對應的方法。這個方法會在成功時傳回如陣列般的結果物件，或在失敗時丟出例外。

建立用戶端

您可以藉由將選項的關聯陣列傳遞至用戶端的建構函數，來建立用戶端。

匯入 

require 'vendor/autoload.php';

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

範例程式碼 

//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'.

選擇性「版本」參數的相關資訊可在組態選項主題中找到。

請注意，我們並未明確提供登入資料給用戶端。這是因為 SDK應該會從環境變數 、HOME目錄中共用config和credentials檔案的 、 AWS Identity and Access Management （IAM） 執行個體設定檔憑證 或憑證提供者 偵測憑證。

所有一般用戶端組態選項都會在 中詳細說明第 3 AWS SDK for PHP 版的組態。提供給用戶端的選項陣列可能會因您正在建立的用戶端而不同。這些自訂用戶端組態選項會在每個用戶端的API文件中說明。

使用 Sdk 類別

Aws\Sdk 類別做為用戶端 factory，用於管理跨多個用戶端的共用組態選項。可以提供給特定用戶端建構器的許多選項也可以提供給 Aws\Sdk類別。這些選項接著會套用到每個用戶端建構函式。

匯入 

require 'vendor/autoload.php';

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

範例程式碼 

// 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();

在所有用戶端共用的選項將放入根層級的金鑰值組。服務特定的組態資料可以在與服務命名空間 （例如「S3」、「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();

服務特定的組態值為服務特定值與根層級值的整合 (即服務特定值以淺層合併至根層級值)。

注意

如果您正在您的應用程式中使用多個用戶端執行個體，我們強烈建議您使用 Sdk 類別。Sdk 類別會自動為每個HTTP用戶端使用相同的SDK用戶端，允許不同 服務的SDK用戶端執行非封鎖HTTP請求。如果SDK用戶端不使用相同的HTTP用戶端，則SDK用戶端傳送的HTTP請求可能會封鎖服務之間的承諾協調。

執行服務操作

您可以透過在用戶端物件上呼叫相同名稱的方法來執行服務操作。例如，若要執行 Amazon S3 PutObject操作 ，您必須呼叫 Aws\S3\S3Client::putObject()方法。

匯入 

require 'vendor/autoload.php';

use Aws\S3\S3Client;

範例程式碼 

// 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'];

用戶端可使用的操作以及輸入與輸出的結構皆根據服務描述檔在執行時間時定義。建立用戶端時，您必須提供版本 (例如「2006-03-01」或「最新」)。會根據提供的版本SDK尋找對應的組態檔案。

如 putObject() 的操作方法皆接受陳述式，為代表操作參數的相關陣列。此陣列的結構 （和結果物件的結構） 是針對 SDKAPI文件中的每個操作定義 （例如，請參閱putObject操作 API的文件）。

HTTP 處理常式選項

您也可以使用特殊@http參數微調基礎HTTP處理常式執行請求的方式。您可以在 @http 參數中包含的選項與您在使用 “http” 用戶端選項執行個體化用戶端時可設定的選項相同。

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

非同步請求

您可以使用 的非同步功能同時傳送命令SDK。您可以在操作名稱中加入 Async 前綴來以非同步方式傳送請求。這將啟動請求並傳回承諾。承諾以成功或以例外狀況遭拒的結果物件履行。這可讓您建立多個承諾，並在基礎HTTP處理常式傳輸HTTP請求時，讓他們同時傳送請求。

匯入 

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

範例程式碼 

// 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();

您可以透過使用承諾的 wait 方法同步強制承諾完成。強制 promise 完成的同時也會根據預設「取消包裝」promise 的狀態，表示其會傳回 promise 的結果或者拋出遇到的例外狀況。wait() 呼叫承諾時，程序會封鎖，直到HTTP請求完成並填入結果或擲回例外狀況為止。

SDK 搭配事件迴路程式庫使用 時，請勿封鎖結果。相反地，請使用結果的 then() 方法來存取在操作完成時解決或拒絕的承諾。

匯入 

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

範例程式碼 

// 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();
    });

使用結果物件

執行成功操作會傳回 Aws\Result 物件。會SDK強制回應資料進入關聯陣列結構，而不是傳回服務的原始XML或JSON資料。將根據對於特定服務的知識以及基礎回應結構來標準化資料中的部分面向。

您可以從 AWSResult 物件存取資料，例如關聯PHP陣列。

匯入 

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

範例程式碼 

// 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();

結果物件的內容會根據執行的操作以及服務版本而定。每個API操作的結果結構都會記錄在每個操作的API文件中。

與 SDK整合JMESPath， DSL是用來搜尋和操作JSON資料的 ，或在我們的案例中是PHP陣列。結果物件包含您可以用於更明顯宣告從結果中擷取資料的 search() 方法。

範例程式碼 

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

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

處理錯誤

同步錯誤處理

執行操作時若發生錯誤，將顯示例外情況。因此，如果您需要處理程式碼中的錯誤，請在操作周圍使用 try/catch 區塊。發生錯誤時， 會SDK捨棄服務特定的例外狀況。

下列為使用 Aws\S3\S3Client 的範例。如果發生錯誤，丟出的例外狀況將會是類型 Aws\S3\Exception\S3Exception。SDK 捨棄從Aws\Exception\AwsException類別延伸的所有服務特定例外狀況。此類別包含關於失敗的實用資訊，包括請求 ID、錯誤碼和錯誤類型。請注意，對於某些支援 的服務，回應資料會強制成為關聯陣列結構 （類似Aws\Result物件），這可以像一般PHP關聯陣列一樣存取。toArray() 方法將傳回任何這類資料，如果存在的話。

匯入 

require 'vendor/autoload.php';

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

範例程式碼 

// 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());
}

非同步錯誤處理

傳送非同步請求時不會丟出例外狀況。但是，您必須使用傳回承諾的 then() 或 otherwise() 方法接來收結果或錯誤。

匯入 

require 'vendor/autoload.php';

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

範例程式碼 

//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);
});

您可以「取消包裝」promise，並拋出例外狀況。

匯入 

require 'vendor/autoload.php';

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

範例程式碼 

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

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