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

# 使用第 3 版的 Amazon S3 範例 適用於 PHP 的 AWS SDK
<a name="s3-examples"></a>

Amazon Simple Storage Service (Amazon S3) 是一種 Web 服務，可提供高度可擴展的雲端儲存。Amazon S3 提供易於使用的物件儲存，具有簡單的 Web 服務介面，可從 Web 上的任何位置儲存和擷取任意數量的資料。

您可以在 GitHub 上 適用於 PHP 的 AWS SDK 取得 的所有範例程式碼。 [ GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)

## 憑證
<a name="examplecredentials"></a>

在執行範例程式碼之前，請先設定您的 AWS 登入資料，如中所述[AWS 使用第 3 適用於 PHP 的 AWS SDK 版向 驗證](credentials.md)。然後匯入 適用於 PHP 的 AWS SDK，如 中所述[安裝第 3 適用於 PHP 的 AWS SDK 版](getting-started_installation.md)。

**Topics**
+ [憑證](#examplecredentials)
+ [建立和使用 Amazon S3 儲存貯體](s3-examples-creating-buckets.md)
+ [管理 Amazon S3 儲存貯體存取許可](s3-examples-access-permissions.md)
+ [設定 Amazon S3 儲存貯體](s3-examples-configuring-a-bucket.md)
+ [Amazon S3 分段上傳](s3-multipart-upload.md)
+ [Amazon S3 預先簽章的 URL](s3-presigned-url.md)
+ [建立 S3 預先簽章POSTs](s3-presigned-post.md)
+ [使用 Amazon S3 儲存貯體做為靜態 Web 主機](s3-examples-static-web-host.md)
+ [使用 Amazon S3 儲存貯體政策](s3-examples-bucket-policies.md)
+ [使用 S3 存取點 ARNs](s3-examples-access-point-arn.md)
+ [使用多區域存取點](s3-multi-region-access-points.md)

# 使用第 3 版建立和使用 Amazon S3 儲存貯體 適用於 PHP 的 AWS SDK
<a name="s3-examples-creating-buckets"></a>

下列範例示範如何：
+ 使用 [ListBuckets](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#listbuckets) 傳回已驗證的請求發送者擁有的儲存貯體清單。
+ 使用 [CreateBucket](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#createbucket) 建立新的儲存貯體。
+ 使用 [PutObject](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject) 將物件新增到儲存貯體。

您可以在 GitHub 適用於 PHP 的 AWS SDK 上取得 的所有範例程式碼。 [ GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)

## 登入資料
<a name="examplecredentials"></a>

執行範例程式碼之前，請先設定您的 AWS 登入資料，如中所述[AWS 使用第 3 適用於 PHP 的 AWS SDK 版向 驗證](credentials.md)。然後匯入 適用於 PHP 的 AWS SDK，如 中所述[安裝第 3 適用於 PHP 的 AWS SDK 版](getting-started_installation.md)。

 **匯入** 

```
require 'vendor/autoload.php';

use Aws\S3\S3Client;
```

## 列出儲存貯體
<a name="list-buckets"></a>

使用下列程式碼建立 PHP 檔案。首先建立指定 AWS 區域和版本的 AWS.S3 用戶端服務。然後呼叫 `listBuckets`方法，將請求的寄件者擁有的所有 Amazon S3 儲存貯體傳回為儲存貯體結構陣列。

 **範例程式碼** 

```
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

//Listing all S3 Bucket
$buckets = $s3Client->listBuckets();
foreach ($buckets['Buckets'] as $bucket) {
    echo $bucket['Name'] . "\n";
}
```

## 建立 儲存貯體
<a name="create-a-bucket"></a>

使用下列程式碼建立 PHP 檔案。首先建立指定 AWS 區域和版本的 AWS.S3 用戶端服務。然後以陣列呼叫 `createBucket` 方法做為參數。唯一的必要欄位是 ‘Bucket’ 鍵，此字串值是欲建立儲存貯體的名稱。不過，您可以使用「CreateBucketConfiguration」欄位指定 AWS 區域。如果成功，此方法會傳回儲存貯體的 ‘Location’ (位置)。

 **範例程式碼** 

```
function createBucket($s3Client, $bucketName)
{
    try {
        $result = $s3Client->createBucket([
            'Bucket' => $bucketName,
        ]);
        return 'The bucket\'s location is: ' .
            $result['Location'] . '. ' .
            'The bucket\'s effective URI is: ' .
            $result['@metadata']['effectiveUri'];
    } catch (AwsException $e) {
        return 'Error: ' . $e->getAwsErrorMessage();
    }
}

function createTheBucket()
{
    $s3Client = new S3Client([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => '2006-03-01'
    ]);

    echo createBucket($s3Client, 'amzn-s3-demo-bucket');
}

// Uncomment the following line to run this code in an AWS account.
// createTheBucket();
```

## 將物件放入儲存貯體
<a name="put-an-object-in-a-bucket"></a>

若要將檔案新增到您的新儲存貯體，請以下列程式碼建立 PHP 檔案。

由命令列執行此檔案，並以字串傳入您想上傳檔案的儲存貯體的名稱，接著是欲上傳的檔案所在完整檔案路徑。

 **範例程式碼** 

```
$USAGE = "\n" .
    "To run this example, supply the name of an S3 bucket and a file to\n" .
    "upload to it.\n" .
    "\n" .
    "Ex: php PutObject.php <bucketname> <filename>\n";

if (count($argv) <= 2) {
    echo $USAGE;
    exit();
}

$bucket = $argv[1];
$file_Path = $argv[2];
$key = basename($argv[2]);

try {
    //Create a S3Client
    $s3Client = new S3Client([
        'profile' => 'default',
        'region' => 'us-west-2',
        'version' => '2006-03-01'
    ]);
    $result = $s3Client->putObject([
        'Bucket' => $bucket,
        'Key' => $key,
        'SourceFile' => $file_Path,
    ]);
} catch (S3Exception $e) {
    echo $e->getMessage() . "\n";
}
```

# 使用第 3 版管理 Amazon S3 儲存貯體存取許可 適用於 PHP 的 AWS SDK
<a name="s3-examples-access-permissions"></a>

存取控制清單 (ACL) 是可用來管理儲存貯體與物件存取的其中一個資源類型存取政策選項。您可以使用 ACLs將基本讀取/寫入許可授予其他 AWS 帳戶。如需進一步了解，請參閱[使用 ACL 管理存取](https://docs.aws.amazon.com/AmazonS3/latest/dev/S3_ACLs_UsingACLs.html)。

下列範例將說明：
+ 使用 [GetBucketAcl](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getbucketacl) 取得儲存貯體的存取控制政策。
+ 使用 [PutBucketAcl](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putbucketacl) 憑藉 ACL 對儲存貯體設定許可。

您可以在 GitHub 上 適用於 PHP 的 AWS SDK 取得 的所有範例程式碼。 [ GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)

## 登入資料
<a name="examplecredentials"></a>

在執行範例程式碼之前，請先設定您的 AWS 登入資料，如中所述[AWS 使用第 3 適用於 PHP 的 AWS SDK 版向 驗證](credentials.md)。然後匯入 適用於 PHP 的 AWS SDK，如 中所述[安裝第 3 適用於 PHP 的 AWS SDK 版](getting-started_installation.md)。

## 取得並設定存取控制清單政策
<a name="get-and-set-an-access-control-list-policy"></a>

 **匯入** 

```
require 'vendor/autoload.php';

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

 **範例程式碼** 

```
// Create a S3Client 
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

// Gets the access control policy for a bucket
$bucket = 'amzn-s3-demo-bucket';
try {
    $resp = $s3Client->getBucketAcl([
        'Bucket' => $bucket
    ]);
    echo "Succeed in retrieving bucket ACL as follows: \n";
    var_dump($resp);
} catch (AwsException $e) {
    // output error message if fails
    echo $e->getMessage();
    echo "\n";
}

// Sets the permissions on a bucket using access control lists (ACL).
$params = [
    'ACL' => 'public-read',
    'AccessControlPolicy' => [
        // Information can be retrieved from `getBucketAcl` response
        'Grants' => [
            [
                'Grantee' => [
                    'DisplayName' => '<string>',
                    'EmailAddress' => '<string>',
                    'ID' => '<string>',
                    'Type' => 'CanonicalUser',
                    'URI' => '<string>',
                ],
                'Permission' => 'FULL_CONTROL',
            ],
            // ...
        ],
        'Owner' => [
            'DisplayName' => '<string>',
            'ID' => '<string>',
        ],
    ],
    'Bucket' => $bucket,
];

try {
    $resp = $s3Client->putBucketAcl($params);
    echo "Succeed in setting bucket ACL.\n";
} catch (AwsException $e) {
    // Display error message
    echo $e->getMessage();
    echo "\n";
}
```

# 使用第 3 版設定 Amazon S3 儲存貯體 適用於 PHP 的 AWS SDK
<a name="s3-examples-configuring-a-bucket"></a>

跨來源資源分享 (CORS) 會定義一種方式，讓載入單一個網域的用戶端 Web 應用程式，能與不同網域中的資源互動。透過 Amazon S3 中的 CORS 支援，您可以使用 Amazon S3 建置豐富的用戶端 Web 應用程式，並選擇性地允許跨來源存取您的 Amazon S3 資源。

如需搭配 Amazon S3 儲存貯體使用 CORS 組態的詳細資訊，請參閱[跨來源資源共用 (CORS)](https://docs.aws.amazon.com/AmazonS3/latest/dev/cors.html)。

下列範例示範如何：
+ 使用 [GetBucketCors](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getbucketcors) 取得儲存貯體的 CORS 組態。
+ 使用 [PutBucketCors](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putbucketcors) 設定儲存貯體的 CORS 組態。

您可以在 GitHub 上 適用於 PHP 的 AWS SDK 取得 的所有範例程式碼。 [ GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)

## 登入資料
<a name="examplecredentials"></a>

在執行範例程式碼之前，請先設定您的 AWS 登入資料，如中所述[AWS 使用第 3 適用於 PHP 的 AWS SDK 版向 驗證](credentials.md)。然後匯入 適用於 PHP 的 AWS SDK，如 中所述[安裝第 3 適用於 PHP 的 AWS SDK 版](getting-started_installation.md)。

## 取得 CORS 組態
<a name="get-the-cors-configuration"></a>

使用下列程式碼建立 PHP 檔案。首先，建立一個 AWS.S3 用戶端服務，然後呼叫 `getBucketCors` 方法，並指定具有您所需要 CORS 組態的儲存貯體。

唯一需要的參數，就是所選取儲存貯體的名稱。如果儲存貯體目前具有 CORS 組態，Amazon S3 會將該組態傳回為 [CORSRules 物件](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#shape-corsrule)。

 **匯入** 

```
require 'vendor/autoload.php';

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

 **範例程式碼** 

```
$client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

try {
    $result = $client->getBucketCors([
        'Bucket' => $bucketName, // REQUIRED
    ]);
    var_dump($result);
} catch (AwsException $e) {
    // output error message if fails
    error_log($e->getMessage());
}
```

## 設定 CORS 組態
<a name="set-the-cors-configuration"></a>

使用下列程式碼建立 PHP 檔案。首先，建立一個 AWS.S3 用戶端服務。接著呼叫 `putBucketCors` 方法並指定您要設定其 CORS 組態的儲存貯體，然後指定 CORSConfiguration 為 [CORSRules JSON 物件](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#shape-corsrule)。

 **匯入** 

```
require 'vendor/autoload.php';

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

 **範例程式碼** 

```
$client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

try {
    $result = $client->putBucketCors([
        'Bucket' => $bucketName, // REQUIRED
        'CORSConfiguration' => [ // REQUIRED
            'CORSRules' => [ // REQUIRED
                [
                    'AllowedHeaders' => ['Authorization'],
                    'AllowedMethods' => ['POST', 'GET', 'PUT'], // REQUIRED
                    'AllowedOrigins' => ['*'], // REQUIRED
                    'ExposeHeaders' => [],
                    'MaxAgeSeconds' => 3000
                ],
            ],
        ]
    ]);
    var_dump($result);
} catch (AwsException $e) {
    // output error message if fails
    error_log($e->getMessage());
}
```

# 搭配第 3 版使用 Amazon S3 分段上傳 適用於 PHP 的 AWS SDK
<a name="s3-multipart-upload"></a>

透過單次 `PutObject` 操作，您最多可上傳大小 5 GB 的物件。不過，如果使用分段上傳方法 (例如，`CreateMultipartUpload`、`UploadPart`、`CompleteMultipartUpload`、`AbortMultipartUpload`)，您可以上傳大小從 5 MB 到 5 TB 的物件。

下列範例將說明：
+ 使用 [ObjectUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectUploader.html) 將物件上傳至 Amazon S3。
+ 使用 [MultipartUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.MultipartUploader.html) 為 Amazon S3 物件建立分段上傳。
+ 使用 [ObjectCopier](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectCopier.html) 將物件從一個 Amazon S3 位置複製到另一個位置。

您可以在 GitHub 上 適用於 PHP 的 AWS SDK 取得 的所有範例程式碼。 [ GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)

## 憑證
<a name="examplecredentials"></a>

在執行範例程式碼之前，請先設定您的 AWS 登入資料，如中所述[AWS 使用第 3 適用於 PHP 的 AWS SDK 版向 驗證](credentials.md)。然後匯入 適用於 PHP 的 AWS SDK，如 中所述[安裝第 3 適用於 PHP 的 AWS SDK 版](getting-started_installation.md)。

## 物件上傳程式
<a name="object-uploader"></a>

如果您不確定 `PutObject`或 `MultipartUploader` 是否最適合任務，請使用 `ObjectUploader`。 會根據承載大小`MultipartUploader`，使用 `PutObject`或 將大型檔案`ObjectUploader`上傳至 Amazon S3。

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\ObjectUploader;
use Aws\S3\S3Client;
```

 **範例程式碼** 

```
// Create an S3Client.
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-east-2',
    'version' => '2006-03-01'
]);

$bucket = 'your-bucket';
$key = 'my-file.zip';

// Use a stream instead of a file path.
$source = fopen('/path/to/large/file.zip', 'rb');

$uploader = new ObjectUploader(
    $s3Client,
    $bucket,
    $key,
    $source
);

do {
    try {
        $result = $uploader->upload();
        if ($result["@metadata"]["statusCode"] == '200') {
            print('<p>File successfully uploaded to ' . $result["ObjectURL"] . '.</p>');
        }
        print($result);
        // If the SDK chooses a multipart upload, try again if there is an exception.
        // Unlike PutObject calls, multipart upload calls are not automatically retried.
    } catch (MultipartUploadException $e) {
        rewind($source);
        $uploader = new MultipartUploader($s3Client, $source, [
            'state' => $e->getState(),
        ]);
    }
} while (!isset($result));

fclose($source);
```

### Configuration
<a name="object-uploader-configuration"></a>

`ObjectUploader` 物件建構函式接受下列引數：

**`$client`**  
用來執行傳輸的 `Aws\ClientInterface` 物件。這應該是 `Aws\S3\S3Client` 的執行個體。

**`$bucket`**  
(`string`，*必要*) 做為物件上傳目的地的儲存貯體的名稱。

**`$key`**  
(`string`，*必要*) 待上傳的物件所要使用的金鑰。

**`$body`**  
(`mixed`，*必要*) 要上傳的物件資料。可以是 `StreamInterface`、PHP 串流資源或要上傳的資料字串。

**`$acl`**  
(`string`) 針對待上傳的物件，所要設定的存取控制清單 (ACL)。物件預設為私有。

**`$options`**  
分段上傳的組態選項的關聯式陣列。下列組態選項為有效：    
**`add_content_md5`**  
(`bool`) 設為 true 可自動計算上傳的 MD5 檢查總和。  
**`mup_threshold`**  
(`int`，*預設*：`int(16777216)`) 檔案大小的位元組數。如果檔案大小超過此限制，則會使用分段上傳。  
**`before_complete`**  
(`callable`) 要在 `CompleteMultipartUpload` 操作之前呼叫的回呼函式。回呼應具有類似 的函數簽章：`function (Aws\Command $command) {...}`。如需可新增至`CommandInterface`物件的參數，請參閱 [CompleteMultipartUpload API 參考](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#completemultipartupload)。  
**`before_initiate`**  
(`callable`) 要在 `CreateMultipartUpload` 操作之前呼叫的回呼函式。回呼應具有類似 的函數簽章：`function (Aws\Command $command) {...}`。如果檔案大小超過 `mup_threshold`值，軟體開發套件會叫用此回呼。如需可新增至`CommandInterface`物件的參數，請參閱 [CreateMultipartUpload API 參考](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#createmultipartupload)。  
**`before_upload`**  
(`callable`) 回呼在 `PutObject`或 `UploadPart`操作之前叫用。回呼應具有類似 的函數簽章：`function (Aws\Command $command) {...}`。如果檔案大小小於或等於`mup_threshold`值，軟體開發套件會叫用此回呼。如需可套用至`PutObject`請求的參數，請參閱 [PutObject API 參考](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject)。如需套用至`UploadPart`請求的參數，請參閱 [UploadPart API 參考](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#uploadpart)。SDK 會忽略任何不適用於`CommandInterface`物件所代表之操作的參數。  
**`concurrency`**  
(`int`，*預設*：`int(3)`) 分段上傳期間所允許的並行 `UploadPart` 操作的數目上限。  
**`part_size`**  
(`int`，*預設*：`int(5242880)`) 進行分段上傳時所使用的分段大小 (位元組)。該值必須介於 5 MB 到 5 GB 之間。  
**`state`**  
(`Aws\Multipart\UploadState`) 代表分段上傳狀態的物件，用來恢復先前的上傳作業。提供此選項時，會忽略 `$bucket`和 `$key`引數和 `part_size`選項。  
**`params`**  
關聯陣列，提供每個子命令的組態選項。例如：  

```
new ObjectUploader($bucket, $key, $body, $acl, ['params' => ['CacheControl' => <some_value>])
```

## MultipartUploader
<a name="multipartuploader"></a>

分段上傳是專為改善較大型物件上傳的體驗所設計。這些方法可讓您以任意順序，個別同時上傳物件的各部分。

建議 Amazon S3 客戶針對大於 100 MB 的物件使用分段上傳。

## MultipartUploader 物件
<a name="multipartuploader-object"></a>

軟體開發套件具有特殊的 `MultipartUploader` 物件，可簡化分段上傳的流程。

 **匯入** 

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **範例程式碼** 

```
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

// Use multipart upload
$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

try {
    $result = $uploader->upload();
    echo "Upload complete: {$result['ObjectURL']}\n";
} catch (MultipartUploadException $e) {
    echo $e->getMessage() . "\n";
}
```

上傳程式會根據隨附的原始碼和組態，建立分段資料的產生器，並嘗試上傳所有部分。如果某些部分上傳失敗，上傳程式會持續上傳之後的部分，直到讀取完整個原始碼的資料。之後，上傳工具會嘗試上傳失敗的部分，或擲出包含與無法上傳之部分相關資訊的例外狀況。

## 自訂分段上傳
<a name="customizing-a-multipart-upload"></a>

您可以透過將回呼函式傳遞至其建構函式，來針對多段上傳程式所執行的 `CreateMultipartUpload`、`UploadPart` 與 `CompleteMultipartUpload` 操作，設定自訂選項。

 **匯入** 

```
require 'vendor/autoload.php';

use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **範例程式碼** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

// Customizing a multipart upload
$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
    'before_initiate' => function (Command $command) {
        // $command is a CreateMultipartUpload operation
        $command['CacheControl'] = 'max-age=3600';
    },
    'before_upload' => function (Command $command) {
        // $command is an UploadPart operation
        $command['RequestPayer'] = 'requester';
    },
    'before_complete' => function (Command $command) {
        // $command is a CompleteMultipartUpload operation
        $command['RequestPayer'] = 'requester';
    },
]);
```

### 部分上傳之間的手動垃圾回收
<a name="manual-garbage-collection-between-part-uploads"></a>

如果您達到大型上傳的記憶體限制，這可能是因為在達到記憶體限制時，[PHP 廢棄項目收集器](https://www.php.net/manual/en/features.gc.php)尚未收集軟體開發套件產生的循環參考。在操作之間手動叫用集合演算法會允許在達到該限制前收集循環。以下範例會在每次分段上傳前，使用回呼叫用集合演算法。請注意，叫用廢棄項目收集器不會伴隨效能成本，最佳使用方式將取決於您的使用案例和環境。

```
$uploader = new MultipartUploader($client, $source, [
   'bucket' => 'your-bucket',
   'key' => 'your-key',
   'before_upload' => function(\Aws\Command $command) {
      gc_collect_cycles();
   }
]);
```

## 從錯誤中復原
<a name="recovering-from-errors"></a>

在分段上傳過程中發生錯誤時，會丟出 `MultipartUploadException`。此例外狀況提供了對 `UploadState` 物件的存取，而此物件包含關於分段上傳進度的資訊。`UploadState` 可用來恢復無法完成的上傳作業。

 **匯入** 

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **範例程式碼** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

//Recover from errors
do {
    try {
        $result = $uploader->upload();
    } catch (MultipartUploadException $e) {
        $uploader = new MultipartUploader($s3Client, $source, [
            'state' => $e->getState(),
        ]);
    }
} while (!isset($result));

//Abort a multipart upload if failed
try {
    $result = $uploader->upload();
} catch (MultipartUploadException $e) {
    // State contains the "Bucket", "Key", and "UploadId"
    $params = $e->getState()->getId();
    $result = $s3Client->abortMultipartUpload($params);
}
```

透過 `UploadState` 恢復上傳的動作時，會嘗試上傳尚未上傳的部分。狀態物件會追蹤缺少的部分，即使這些部分並不連續。上傳程式會針對所提供的原始碼檔案，讀取或搜尋屬於仍需上傳部分的位元組範圍，

 `UploadState` 物件可序列化，因此您也可以在不同的程序中恢復上傳。即使不是在處理例外狀況時，您也可以透過呼叫 `$uploader->getState()`，來取得 `UploadState` 物件。

**重要**  
做為資源傳遞到 `MultipartUploader` 的串流，在上傳之前不會自動跳回開頭。如果您使用的是串流，而非類似於先前範例中迴圈內的檔案路徑，則請重設 `catch` 區塊中的 `$source` 變數。

 **匯入** 

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **範例程式碼** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

//Using stream instead of file path
$source = fopen('/path/to/large/file.zip', 'rb');
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

do {
    try {
        $result = $uploader->upload();
    } catch (MultipartUploadException $e) {
        rewind($source);
        $uploader = new MultipartUploader($s3Client, $source, [
            'state' => $e->getState(),
        ]);
    }
} while (!isset($result));
fclose($source);
```

### 中止分段上傳
<a name="aborting-a-multipart-upload"></a>

您可以擷取 `UploadState` 物件中包含的 `UploadId` ，並將它傳遞至 `abortMultipartUpload`，以中止分段上傳。

```
try {
    $result = $uploader->upload();
} catch (MultipartUploadException $e) {
    // State contains the "Bucket", "Key", and "UploadId"
    $params = $e->getState()->getId();
    $result = $s3Client->abortMultipartUpload($params);
}
```

## 非同步分段上傳
<a name="asynchronous-multipart-uploads"></a>

呼叫 `upload()` 的 `MultipartUploader` 是封鎖請求。如果是在非同步的情境中作業，您可以取得分段上傳的 [promise](guide_promises.md) 物件。

```
require 'vendor/autoload.php';

use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **範例程式碼** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

$promise = $uploader->promise();
```

### Configuration
<a name="asynchronous-multipart-uploads-configuration"></a>

`MultipartUploader` 物件建構函式接受下列引數：

** `$client` **  
用來執行傳輸的 `Aws\ClientInterface` 物件。這應該是 `Aws\S3\S3Client` 的執行個體。

** `$source` **  
正在上傳的原始碼資料。這可以是路徑或 URL (例如，`/path/to/file.jpg`)、資源控制代碼 (例如，`fopen('/path/to/file.jpg', 'r)`)，或是 [PSR-7 stream](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Psr.Http.Message.StreamInterface.html) 的執行個體。

** `$config` **  
分段上傳的組態選項的關聯式陣列。  
下列組態選項為有效：    
** `acl` **  
(`string`) 針對待上傳的物件，所要設定的存取控制清單 (ACL)。物件預設為私有。  
** `before_complete` **  
(`callable`) 要在 `CompleteMultipartUpload` 操作之前呼叫的回呼函式。回呼函式應具有像是 `function (Aws\Command $command) {...}` 的函式簽章。  
** `before_initiate` **  
(`callable`) 要在 `CreateMultipartUpload` 操作之前呼叫的回呼函式。回呼函式應具有像是 `function (Aws\Command $command) {...}` 的函式簽章。  
** `before_upload` **  
(`callable`) 要在任何 `UploadPart` 操作之前呼叫的回呼函式。回呼函式應具有像是 `function (Aws\Command $command) {...}` 的函式簽章。  
** `bucket` **  
(`string`，*必要*) 做為物件上傳目的地的儲存貯體的名稱。  
** `concurrency` **  
(`int`，*預設*：`int(5)`) 分段上傳期間所允許的並行 `UploadPart` 操作的數目上限。  
** `key` **  
(`string`，*必要*) 待上傳的物件所要使用的金鑰。  
** `part_size` **  
(`int`，*預設*：`int(5242880)`) 進行分段上傳時所使用的分段大小 (位元組)。這必須介於 5 MB 到 5 GB 之間 (含)。  
** `state` **  
(`Aws\Multipart\UploadState`) 代表分段上傳狀態的物件，用來恢復先前的上傳作業。提供此選項時，會略過 `bucket`、`key` 和 `part_size` 選項。  
**`add_content_md5`**  
(`boolean`) 設為 true 可自動計算上傳的 MD5 檢查總和。  
**`params`**  
關聯陣列，提供每個子命令的組態選項。例如：  

```
new MultipartUploader($client, $source, ['params' => ['CacheControl' => <some_value>]])
```

## 分段副本
<a name="multipart-copies"></a>

 適用於 PHP 的 AWS SDK 也包含物件`MultipartCopy`，其使用方式與 類似`MultipartUploader`，但設計用於複製 Amazon S3 內大小介於 5 GB 到 5 TB 之間的物件。

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartCopy;
use Aws\S3\S3Client;
```

 **範例程式碼** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

//Copy objects within S3
$copier = new MultipartCopy($s3Client, '/bucket/key?versionId=foo', [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

try {
    $result = $copier->copy();
    echo "Copy complete: {$result['ObjectURL']}\n";
} catch (MultipartUploadException $e) {
    echo $e->getMessage() . "\n";
}
```

# 使用第 3 版的 Amazon S3 預先簽章 URL 適用於 PHP 的 AWS SDK
<a name="s3-presigned-url"></a>

您可以將必要資訊當做查詢字串參數來傳遞，以驗證特定類型的要求，而不使用授權 HTTP 標頭。這有助於啟用直接第三方瀏覽器存取您的私有 Amazon S3 資料，而無需代理請求。其概念是建構「預先簽署」請求，並將其編碼為另一個使用者可以使用的 URL。此外，您可以透過指定過期時間，來限制預先簽章的要求。

## 為 HTTP GET 請求建立預先簽章的 URL
<a name="s3-presigned-url-get"></a>

下列程式碼範例示範如何使用適用於 PHP 的 開發套件，為 HTTP GET 請求建立預先簽章的 URL。

```
<?php

require 'vendor/autoload.php';

use Aws\S3\S3Client;

$s3Client = new S3Client([
    'region' => 'us-west-2',
]);

// Supply a CommandInterface object and an expires parameter to the `createPresignedRequest` method.
$request = $s3Client->createPresignedRequest(
    $s3Client->getCommand('GetObject', [
        'Bucket' => 'amzn-s3-demo-bucket',
        'Key' => 'demo-key',
    ]),
    '+1 hour'
);

// From the resulting RequestInterface object, you can get the URL.
$presignedUrl = (string) $request->getUri();

echo $presignedUrl;
```

方法[的 API 參考`createPresignedRequest`](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.S3Client.html#method_createPresignedRequest)提供更多詳細資訊。

其他人可以使用 `$presignedUrl`值，在下一個小時內擷取物件。例如，當提出 HTTP GET 請求時，它會向 S3 服務顯示呼叫來自建立預先簽章 URL 的使用者。

## 為 HTTP PUT 請求建立預先簽章的 URL
<a name="s3-presigned-url-put"></a>

下列程式碼範例示範如何使用適用於 PHP 的 開發套件，為 HTTP PUT 請求建立預先簽章的 URL。

```
<?php

require 'vendor/autoload.php';

use Aws\S3\S3Client;

$s3Client = new S3Client([
    'region' => 'us-west-2',
]);

$request = $s3Client->createPresignedRequest(
    $s3Client->getCommand('PutObject', [
        'Bucket' => 'amzn-s3-demo-bucket',
        'Key' => 'demo-key',
    ]),
    '+1 hour'
);

// From the resulting RequestInterface object, you can get the URL.
$presignedUrl = (string) $request->getUri();
```

其他人現在可以在 HTTP PUT 請求中使用預先簽章的 URL 來上傳檔案：

```
use GuzzleHttp\Psr7\Request;
use GuzzleHttp\Psr7\Response;

// ...

function uploadWithPresignedUrl($presignedUrl, $filePath, $s3Client): ?Response
{
    // Get the HTTP handler from the S3 client.
    $handler = $s3Client->getHandlerList()->resolve();
    
    // Create a stream from the file.
    $fileStream = new Stream(fopen($filePath, 'r'));
    
    // Create the request.
    $request = new Request(
        'PUT',
        $presignedUrl,
        [
            'Content-Type' => mime_content_type($filePath),
            'Content-Length' => filesize($filePath)
        ],
        $fileStream
    );
    
    // Send the request using the handler.
    try {
        $promise = $handler($request, []);
        $response = $promise->wait();
        return $response;
    } catch (Exception $e) {
        echo "Error uploading file: " . $e->getMessage() . "\n";
        return null;
    }
}
```

# 使用第 Amazon S3POSTs 適用於 PHP 的 AWS SDK
<a name="s3-presigned-post"></a>

與預先簽章URLs 類似，預先簽章POSTs 可讓您提供寫入存取權給使用者，而不需提供 AWS 登入資料。預先簽章的 POST 表單可以由 [AwsS3PostObjectV4](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.PostObjectV4.html) 的執行個體來協助建立。

下列範例示範如何：
+ 使用 [PostObjectV4](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.PostObjectV4.html) 取得 S3 物件 POST 上傳的資料。

您可以在 GitHub 上 適用於 PHP 的 AWS SDK 取得 的所有範例程式碼。 [ GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)

## 登入資料
<a name="examplecredentials"></a>

**注意**  
`PostObjectV4` 不適用於來自 的登入資料 AWS IAM Identity Center。

在執行範例程式碼之前，請先設定您的 AWS 登入資料，如中所述[AWS 使用第 3 適用於 PHP 的 AWS SDK 版向 驗證](credentials.md)。然後匯入 適用於 PHP 的 AWS SDK，如 中所述[安裝第 3 適用於 PHP 的 AWS SDK 版](getting-started_installation.md)。

## 建立 PostObjectV4
<a name="create-postobjectv4"></a>

要建立 `PostObjectV4` 執行個體，您必須提供下列項目：
+ `Aws\S3\S3Client` 執行個體 
+ 儲存貯體
+ 表單輸入欄位的關聯陣列
+ 政策條件陣列 （請參閱《Amazon Simple Storage Service 使用者指南》中的[政策建構](https://docs.aws.amazon.com/AmazonS3/latest/dev/HTTPPOSTForms.html))
+ 政策的過期時間字串 (選擇性，預設為一小時)。

 **匯入** 

```
require '../vendor/autoload.php';

use Aws\S3\PostObjectV4;
use Aws\S3\S3Client;
```

 **範例程式碼** 

```
require '../vendor/autoload.php';

use Aws\S3\PostObjectV4;
use Aws\S3\S3Client;

$client = new S3Client([
    'profile' => 'default',
    'region' => 'us-east-1',
]);
$bucket = 'amzn-s3-demo-bucket10';
$starts_with = 'user/eric/';
$client->listBuckets();

// Set defaults for form input fields.
$formInputs = ['acl' => 'public-read'];

// Construct an array of conditions for policy.
$options = [
    ['acl' => 'public-read'],
    ['bucket' => $bucket],
    ['starts-with', '$key', $starts_with],
];

// Set an expiration time (optional).
$expires = '+2 hours';

$postObject = new PostObjectV4(
    $client,
    $bucket,
    $formInputs,
    $options,
    $expires
);

// Get attributes for the HTML form, for example, action, method, enctype.
$formAttributes = $postObject->getFormAttributes();

// Get attributes for the HTML form values.
$formInputs = $postObject->getFormInputs();
?>
<!DOCTYPE html>
<html lang="en">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
    <title>PHP</title>
</head>
<body>
<form action="<?php echo $formAttributes['action'] ?>" method="<?php echo $formAttributes['method'] ?>"
      enctype="<?php echo $formAttributes['enctype'] ?>">
    <label id="key">
        <input hidden type="text" name="key" value="<?php echo $starts_with ?><?php echo $formInputs['key'] ?>"/>
    </label>
    <h3>$formInputs:</h3>
    acl: <label id="acl">
        <input readonly type="text" name="acl" value="<?php echo $formInputs['acl'] ?>"/>
    </label><br/>
    X-Amz-Credential: <label id="credential">
        <input readonly type="text" name="X-Amz-Credential" value="<?php echo $formInputs['X-Amz-Credential'] ?>"/>
    </label><br/>
    X-Amz-Algorithm: <label id="algorithm">
        <input readonly type="text" name="X-Amz-Algorithm" value="<?php echo $formInputs['X-Amz-Algorithm'] ?>"/>
    </label><br/>
    X-Amz-Date: <label id="date">
        <input readonly type="text" name="X-Amz-Date" value="<?php echo $formInputs['X-Amz-Date'] ?>"/>
    </label><br/><br/><br/>
    Policy: <label id="policy">
        <input readonly type="text" name="Policy" value="<?php echo $formInputs['Policy'] ?>"/>
    </label><br/>
    X-Amz-Signature: <label id="signature">
        <input readonly type="text" name="X-Amz-Signature" value="<?php echo $formInputs['X-Amz-Signature'] ?>"/>
    </label><br/><br/>
    <h3>Choose file:</h3>
    <input type="file" name="file"/> <br/><br/>
    <h3>Upload file:</h3>
    <input type="submit" name="submit" value="Upload to Amazon S3"/>
</form>
</body>
</html>
```

# 透過第 3 版使用 Amazon S3 儲存貯體做為靜態 Web 主機 適用於 PHP 的 AWS SDK
<a name="s3-examples-static-web-host"></a>

您可以在 Amazon S3 上託管靜態網站。若要進一步了解，請參閱[在 Amazon S3 上託管靜態網站](https://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html)。

下列範例將說明：
+ 使用 [GetBucketWebsite](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getbucketwebsite) 取得儲存貯體的網站組態。
+ 使用 [PutBucketWebsite](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putbucketwebsite) 設定儲存貯體的網站組態。
+ 使用 [DeleteBucketWebsite](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#deletebucketwebsite) 從儲存貯體移除網站組態。

第 3 適用於 PHP 的 AWS SDK 版的所有範例程式碼都可在 [ GitHub 上取得](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)。

## 登入資料
<a name="credentials-s3-examples-static-web-host"></a>

在執行範例程式碼之前，請設定您的 AWS 登入資料。請參閱第 [3 適用於 PHP 的 AWS SDK 版的登入](guide_credentials.md)資料。

## 取得、設定和刪除儲存貯體的網站組態
<a name="get-set-and-delete-the-website-configuration-for-a-bucket"></a>

 **匯入** 

```
require 'vendor/autoload.php';

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

 **範例程式碼** 

```
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

// Retrieving the Bucket Website Configuration
$bucket = 'amzn-s3-demo-bucket';
try {
    $resp = $s3Client->getBucketWebsite([
        'Bucket' => $bucket
    ]);
    echo "Succeed in retrieving website configuration for bucket: " . $bucket . "\n";
} catch (AwsException $e) {
    // output error message if fails
    echo $e->getMessage();
    echo "\n";
}

// Setting a Bucket Website Configuration
$params = [
    'Bucket' => $bucket,
    'WebsiteConfiguration' => [
        'ErrorDocument' => [
            'Key' => 'foo',
        ],
        'IndexDocument' => [
            'Suffix' => 'bar',
        ],
    ]
];

try {
    $resp = $s3Client->putBucketWebsite($params);
    echo "Succeed in setting bucket website configuration.\n";
} catch (AwsException $e) {
    // Display error message
    echo $e->getMessage();
    echo "\n";
}

// Deleting a Bucket Website Configuration
try {
    $resp = $s3Client->deleteBucketWebsite([
        'Bucket' => $bucket
    ]);
    echo "Succeed in deleting policy for bucket: " . $bucket . "\n";
} catch (AwsException $e) {
    // output error message if fails
    echo $e->getMessage();
    echo "\n";
}
```

# 使用第 3 版的 Amazon S3 儲存貯體政策 適用於 PHP 的 AWS SDK
<a name="s3-examples-bucket-policies"></a>

您可以使用儲存貯體政策將許可授予 Amazon S3 資源。如需進一步了解，請參閱[使用儲存貯體政策和使用者政策](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-iam-policies.html)。

下列範例將說明：
+ 使用 [GetBucketPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getbucketpolicy) 傳回所指定儲存貯體的政策。
+ 使用 [PutBucketPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putbucketpolicy) 取代儲存貯體的政策。
+ 使用 [DeleteBucketPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#deletebucketpolicy) 從儲存貯體刪除政策。

您可以在 GitHub 適用於 PHP 的 AWS SDK 上取得 的所有範例程式碼。 [ GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)

## 登入資料
<a name="examplecredentials"></a>

在執行範例程式碼之前，請先設定您的 AWS 登入資料，如中所述[AWS 使用第 3 適用於 PHP 的 AWS SDK 版向 驗證](credentials.md)。然後匯入 適用於 PHP 的 AWS SDK，如 中所述[安裝第 3 適用於 PHP 的 AWS SDK 版](getting-started_installation.md)。

## 取得、刪除和取代儲存貯體上的政策
<a name="get-delete-and-replace-a-policy-on-a-bucket"></a>

 **匯入** 

```
require "vendor/autoload.php";

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

 **範例程式碼** 

```
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

$bucket = 'amzn-s3-demo-bucket';

// Get the policy of a specific bucket
try {
    $resp = $s3Client->getBucketPolicy([
        'Bucket' => $bucket
    ]);
    echo "Succeed in receiving bucket policy:\n";
    echo $resp->get('Policy');
    echo "\n";
} catch (AwsException $e) {
    // Display error message
    echo $e->getMessage();
    echo "\n";
}

// Deletes the policy from the bucket
try {
    $resp = $s3Client->deleteBucketPolicy([
        'Bucket' => $bucket
    ]);
    echo "Succeed in deleting policy of bucket: " . $bucket . "\n";
} catch (AwsException $e) {
    // Display error message
    echo $e->getMessage();
    echo "\n";
}

// Replaces a policy on the bucket
try {
    $resp = $s3Client->putBucketPolicy([
        'Bucket' => $bucket,
        'Policy' => 'foo policy',
    ]);
    echo "Succeed in put a policy on bucket: " . $bucket . "\n";
} catch (AwsException $e) {
    // Display error message
    echo $e->getMessage();
    echo "\n";
}
```

# 使用 S3 存取點 ARNs 第 3 適用於 PHP 的 AWS SDK 版
<a name="s3-examples-access-point-arn"></a>

S3 導入存取點，這是一種與 S3 儲存貯體互動的新方式。存取點可以套用唯一的政策和組態，而不是直接套用至儲存貯體。 適用於 PHP 的 AWS SDK 可讓您將儲存貯體欄位中ARNs 用於 API 操作，而不是明確指定儲存貯體名稱。如需 S3 存取點和 ARNs運作方式的詳細資訊，請參閱[此處](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-access-points.html)。下列範例示範如何：
+ 將 [GetObject](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getobject) 與存取點 ARN 搭配使用，從儲存貯體擷取物件。
+ 將 [PuTOObject](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject) 與存取點 ARN 搭配使用，將物件新增至儲存貯體。
+ 將 S3 用戶端設定為使用 ARN 區域，而不是用戶端區域。

您可以在 GitHub 上 適用於 PHP 的 AWS SDK 取得 的所有範例程式碼。 [ GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)

## 登入資料
<a name="examplecredentials"></a>

在執行範例程式碼之前，請先設定您的 AWS 登入資料，如中所述[AWS 使用第 3 適用於 PHP 的 AWS SDK 版向 驗證](credentials.md)。然後匯入 適用於 PHP 的 AWS SDK，如 中所述[安裝第 3 適用於 PHP 的 AWS SDK 版](getting-started_installation.md)。

 **匯入** 

```
require 'vendor/autoload.php';

use Aws\S3\S3Client;
```

## 取得物件
<a name="get-object"></a>

首先建立指定 AWS 區域和版本的 AWS.S3 用戶端服務。然後使用您的金鑰和 `Bucket` 欄位中的 S3 存取點 ARN 呼叫該 `getObject` 方法，該方法將從與該存取點關聯的儲存貯體中獲取物件。

 **範例程式碼** 

```
$s3 = new S3Client([
    'version'     => 'latest',
    'region'      => 'us-west-2',
]);
$result = $s3->getObject([
    'Bucket' => 'arn:aws:s3:us-west-2:123456789012:accesspoint:endpoint-name',
    'Key' => 'MyKey'
]);
```

## 將物件放入儲存貯體
<a name="put-an-object-in-a-bucket"></a>

首先建立指定 AWS 區域和版本的 AWS.S3 用戶端服務。然後使 `putObject` 用所需的金鑰、主體或來源檔案和 `Bucket` 欄位中的 S3 存取點 ARN 呼叫該方法，這會將物件放入與該存取點關聯的儲存貯體中。

 **範例程式碼** 

```
$s3 = new S3Client([
    'version'     => 'latest',
    'region'      => 'us-west-2',
]);
$result = $s3->putObject([
    'Bucket' => 'arn:aws:s3:us-west-2:123456789012:accesspoint:endpoint-name',
    'Key' => 'MyKey',
    'Body' => 'MyBody'
]);
```

## 將 S3 用戶端設定為使用 ARN 區域而不是用戶端區域
<a name="configure-the-s3-client-to-use-the-arn-region-instead-of-the-client-region"></a>

在 S3 用戶端操作中使用 S3 存取點 ARN 時，預設情況下，用戶端將確保 ARN 區域與用戶端區域相符，如果不相符，則擲回例外狀況。您可以將 `use_arn_region` 組態選項設定為 `true`，將此行為變更為透過用戶端區域接受 ARN 區域。依預設，選項會設定為 `false`。

 **範例程式碼** 

```
$s3 = new S3Client([
    'version'        => 'latest',
    'region'         => 'us-west-2',
    'use_arn_region' => true
]);
```

用戶端還將按照以下優先順序檢查環境變數和組態檔案選項：

1. 用戶端選項 `use_arn_region`，如上例所示。

1. 環境變數 `AWS_S3_USE_ARN_REGION` 

```
export AWS_S3_USE_ARN_REGION=true
```

1.  AWS 共用組態檔案中`s3_use_arn_region`的組態變數 （預設為 )`~/.aws/config`。

```
[default]
s3_use_arn_region = true
```

# 搭配第 3 版使用 Amazon S3 多區域存取點 適用於 PHP 的 AWS SDK
<a name="s3-multi-region-access-points"></a>

[Amazon Simple Storage Service (S3) 多區域存取點](https://docs.aws.amazon.com//AmazonS3/latest/userguide/MultiRegionAccessPoints.html)提供全域端點，可在其中路由 Amazon S3 請求流量 AWS 區域。

您可以使用[適用於 PHP 的 SDK](https://docs.aws.amazon.com//aws-sdk-php/v3/api/api-s3control-2018-08-20.html#createmultiregionaccesspoint)、另一個 AWS SDK、[S3 主控台或 AWS CLI ](https://docs.aws.amazon.com//AmazonS3/latest/userguide/multi-region-access-point-create-examples.html)來建立多區域存取點，

**重要**  
若要搭配適用於 PHP 的 SDK 使用多區域存取點，您的 PHP 環境必須安裝[AWS 通用執行期 (AWS CRT) 延伸](guide_crt.md)模組。

當您建立多區域存取點時，Amazon S3 會產生格式如下的 Amazon Resource Name (ARN)：

`arn:aws:s3::account-id:accesspoint/MultiRegionAccessPoint_alias`

您可以使用產生的 ARN 取代 `[getObject()](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getobject)`和 `[putObject()](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject)`方法的儲存貯體名稱。

```
<?php
require './vendor/autoload.php';

use Aws\S3\S3Client;

// Assign the Multi-Region Access Point to a variable and use it place of a bucket name.
$mrap = 'arn:aws:s3::123456789012:accesspoint/mfzwi23gnjvgw.mrap';
$key = 'my-key';

$s3Client = new S3Client([
    'region' => 'us-east-1'
]);

$s3Client->putObject([
    'Bucket' => $mrap,
    'Key' => $key,
    'Body' => 'Hello World!'
]);

$result = $s3Client->getObject([
    'Bucket' => $mrap,
    'Key' => $key
]);

echo $result['Body'] . "\n";

// Clean up.
$result = $s3Client->deleteObject([
    'Bucket' => $mrap,
    'Key' => $key
]);

$s3Client->waitUntil('ObjectNotExists', ['Bucket' => $mrap, 'Key' => $key]);

echo "Object deleted\n";
```