AWS SDK for PHP 版本 3 的基本使用模式 - AWS SDK for PHP
先决条件SDK在你的代码中包含用法总结创建客户端使用 Sdk 类执行服务操作异步请求使用 Result 对象处理错误

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

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

本主题主要介绍 AWS SDK for PHP的基本使用模式。

先决条件

SDK在你的代码中包含

无论您使用哪种技术来安装SDK，都只需一条require语句即可将包含SDK在代码中。有关最适合您的安装技术的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 代码。

用法总结

要使用与 AWS 服务进行交互，请实例化一个 Client 对象。SDK客户端对象的方法与服务中的操作相对应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) 实例配置文件凭据或凭证提供者的证书。

在 AWS SDK for PHP 版本 3 的配置 中详细介绍了所有通用的客户端配置选项。创建的客户端不同，提供的选项数组也不同。每个客户端的API文档中都描述了这些自定义客户端配置选项。

使用 Sdk 类

Aws\Sdk 类可作为客户端工厂，用于管理多个客户端的共享配置选项。许多可提供给特定客户端构造函数的选项也可提供给 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类自动为每个HTTPSDK客户端使用相同的客户端，从而允许不同服务的SDK客户端执行非阻塞HTTP请求。如果SDK客户端不使用同一个HTTP客户端，则客户端发送的HTTPSDK请求可能会阻止服务之间的承诺编排。

执行服务操作

通过在客户端对象上调用同名方法，可执行服务操作。例如，要执行 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”或“latest”）。根据提供的版本SDK查找相应的配置文件。

所有操作方法 (如 putObject()) 均接受单独的参数，或代表操作参数的关联数组。这个数组的结构（以及结果对象的结构）是在的API文档中为每个操作定义SDK的（例如，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 后缀，异步发送请求。这样可以启动请求并返回 Promise。如果成功，结果对象可满足 Promise；如果失败，异常会导致拒绝 Promise。这使您可以创建多个 Promise，并让它们在底层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();

您可以使用 Promise 的 wait 方法，强制 Promise 同步完成。默认情况下，强制完成 Promise 也会“解封”Promise 的状态，这意味着它会返回 Promise 的结果或引发异常。调用 p wait() romise 时，进程会阻塞，直到HTTP请求完成并填充结果或引发异常。

SDK与事件循环库一起使用时，不要屏蔽结果。请使用结果的 then() 方法，在操作完成时访问已解决或被拒绝的 Promise。

导入 

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

使用 Result 对象

执行成功的操作会返回 Aws\Result 对象。不是返回服务的原始JSON数据XML或数据，而是将响应数据SDK强制转换为关联数组结构。这样可以根据它对特定服务和底层响应结构的认知，将数据的某些方面规范化。

您可以像关联PHP数组一样访问 AWSResult 对象中的数据。

导入 

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文档中。

与 a 集成 JMESPath，DSL用于搜索和操作JSON数据，或者在我们的例子中SDK是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());
}

异步处理错误

在发送异步请求的时候不会引发异常。您必须使用返回的 Promise 的 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();
}