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

# 使用第 3 適用於 PHP 的 AWS SDK 版提出 AWS 服務 請求
<a name="making-service-requests"></a>

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

使用 第 3 適用於 PHP 的 AWS SDK 版會遵循所有 的一致模式 AWS 服務。基本工作流程包含三個主要步驟：

1. [**建立服務用戶端**](#creating-a-client) - 為 AWS 服務 您要使用的 建立**用戶端**物件。

1. [**執行操作**](#executing-service-operations) - 在用戶端上呼叫對應至服務 API 中操作的方法。

1. [**程序結果**](#result-objects) - 使用成功傳回的類似陣列**的結果**物件，或處理失敗時擲出的任何**例外**狀況。

以下各節會詳細說明這些步驟，從如何建立和設定服務用戶端開始。

## 建立基本服務用戶端
<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)來尋找登入資料資訊。

中會詳細說明所有一般用戶端組態選項[第 3 適用於 PHP 的 AWS SDK 版的用戶端建構函式選項](guide_configuration.md)。提供給用戶端的選項陣列可能會因您正在建立的用戶端而不同。這些自訂用戶端組態選項的說明如各用戶端的 [API 文件](https://docs.aws.amazon.com/aws-sdk-php/latest/)所述。

雖然上述範例顯示基本用戶端建立，但您可以自訂服務用戶端以符合特定需求。如需透過程式碼設定服務用戶端的詳細資訊，請參閱 [在 第 3 適用於 PHP 的 AWS SDK 版的程式碼中設定服務用戶端](configuring-service-clients-code.md)。如果您需要使用外部組態檔案或環境變數來設定服務用戶端，請參閱 [在外部設定第 3 適用於 PHP 的 AWS SDK 版的服務用戶端](configuring-service-clients-ext.md)。

## 提出要求
<a name="executing-service-operations"></a>

您可以呼叫用戶端物件上相同名稱的 方法來提出服務請求。例如，若要執行 Amazon S3 [PutObject 操作](https://docs.aws.amazon.com/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」*或*「最新」*)，用戶端會預設為最新版本。開發套件根據提供的版本找到對應的組態檔案。

如 `putObject()` 的操作方法皆接受陳述式，為代表操作參數的相關陣列。此陣列的結構 (以及結果物件的結構) 已為軟體開發套件 API 文件中的各項操作定義 (例如，請參閱 [putObject 操作](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject)的 API 文件)。

### 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'
    ]
]);
```

## 使用結果物件
<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 文件中。

開發套件與 [JMESPath](http://jmespath.org/) 整合，此 [DSL](http://en.wikipedia.org/wiki/Domain-specific_language) 用於搜尋及操控 JSON 資料，即如同本文件用於操控 PHP 陣列。結果物件包含您可以用於更明顯宣告從結果中擷取資料的 `search()` 方法。

 **範例程式碼** 

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

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