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

# 使用 适用于 PHP 的 Amazon SDK 版本 3 提出 Amazon Web Services 服务 请求
<a name="making-service-requests"></a>

## SDK 请求工作流程概述
<a name="usage-summary"></a>

使用 适用于 PHP 的 Amazon SDK 版本 3 在所有版本中都遵循一致的模式 Amazon Web Services 服务。基本工作流程包括三个主要步骤：

1. [**创建服务客户端**](#creating-a-client)-为 Amazon Web Services 服务 要使用的实例化一个**客户端**对象。

1. [**执行操作**](#executing-service-operations) — 在客户端上调用与服务 API 中的操作相对应的方法。

1. [**处理结果**](#result-objects) — 使用成功时返回的类似数组的 **Result** 对象，或者处理失败时引发的任何 **Exception**。

以下各节将详细说明上述每个步骤，首先介绍如何创建和配置服务客户端。

## 创建基本服务客户端
<a name="creating-a-client"></a>

您可以通过向客户端的构造函数传递选项的关联数组来创建客户端。

 **导入** 

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

有关可选“版本”参数的信息，请参阅[配置选项](guide_configuration.md#cfg-version)主题。

请注意，我们**并未**向客户端显式提供凭证。这是因为 SDK 使用[默认凭证提供程序链](guide_credentials_default_chain.md)来查找凭证信息。

在 [适用于 PHP 的 Amazon SDK 版本 3 的客户端构造器选项](guide_configuration.md) 中详细介绍了所有通用的客户端配置选项。创建的客户端不同，提供的选项数组也不同。每个客户端的 [API 文档](https://docs.amazonaws.cn/aws-sdk-php/latest/)中介绍了这些自定义客户端配置选项。

上述示例显示的是基本客户端创建过程，您也可以自定义服务客户端以满足特定要求。有关通过代码配置服务客户端的更多详细信息，请参阅[在 适用于 PHP 的 Amazon SDK 版本 3 的代码中配置服务客户端](configuring-service-clients-code.md)。如果需要使用外部配置文件或环境变量来配置服务客户端，请参阅[在外部配置 适用于 PHP 的 Amazon SDK 版本 3 的服务客户端](configuring-service-clients-ext.md)。

## 发出请求
<a name="executing-service-operations"></a>

通过在客户端对象上调用同名方法，可发出服务请求。例如，要执行 Amazon S3 [PutObject操作](https://docs.amazonaws.cn/AmazonS3/latest/API/RESTObjectPUT.html)，您需要调用`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' => 'amzn-s3-demo-bucket',
    'Key' => 'my-key',
    'Body' => 'this is the body!'
]);

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

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

客户端提供的操作，以及输入、输出的结构是根据服务描述文件在运行时定义的。创建客户端时，如果您未提供服务模型的 `version` 参数（例如，*“2006-03-01”*或*“latest”*），则客户端将默认使用最新版本。开发工具包会根据提供的版本找到相应的配置文件。

所有操作方法 (如 `putObject()`) 均接受单独的参数，或代表操作参数的关联数组。此数组的结构（以及结果对象的结构）是在开发工具包的 API 文档中针对每个操作进行定义的（例如，请参阅 API 文档中的 [putObject 操作](https://docs.amazonaws.cn/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject)）。

### HTTP 处理程序选项
<a name="http-handler-options"></a>

您还可以使用特殊的 `@http` 参数微调底层 HTTP 处理程序执行请求的方式。可包含在 `@http` 参数中的选项与您在使用[“http”客户端选项](guide_configuration.md#config-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'
    ]
]);
```

## 使用 Result 对象
<a name="result-objects"></a>

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

您可以访问 `AWS\Result` 对象的数据，就像访问关联 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 集成了用于搜索和操作 J [SON 数据的 DSL](http://en.wikipedia.org/wiki/Domain-specific_language)，或者在我们的例子中是 PHP 数组。[JMESPath](http://jmespath.org/)结果对象包含 `search()` 方法，可用于更具声明性地从结果中提取数据。

 **示例代码** 

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

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