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

# 使用 适用于 PHP 的 AWS SDK 版本 3 的 Amazon S3 示例
<a name="s3-examples"></a>

Amazon Simple Storage Service (Amazon S3) 是提供高度可扩展的云存储的 Web 服务。Amazon S3 提供易于使用的对象存储，具有简单的 Web 服务接口，可用于从 Web 上的任何位置存储和检索任意规模的数据。

的所有示例代码都可以在[此 适用于 PHP 的 AWS SDK 处找到 GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)。

## 凭据
<a name="examplecredentials"></a>

在运行示例代码之前，请配置您的 AWS 证书，如中所述[AWS 使用 适用于 PHP 的 AWS SDK 版本 3 进行身份验证](credentials.md)。然后导入 适用于 PHP 的 AWS SDK，如中所述[安装 适用于 PHP 的 AWS SDK 版本 3](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 预签名 POST](s3-presigned-post.md)
+ [使用 Amazon S3 存储桶作为静态 Web 主机](s3-examples-static-web-host.md)
+ [使用 Amazon S3 存储桶策略](s3-examples-bucket-policies.md)
+ [使用 S3 接入点 ARN](s3-examples-access-point-arn.md)
+ [使用多区域接入点](s3-multi-region-access-points.md)

# 使用 适用于 PHP 的 AWS SDK 版本 3 来创建和使用 Amazon S3 存储桶
<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) 向存储桶添加对象。

适用于 PHP 的 AWS SDKGitHub[ 上提供了](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)的所有示例代码。

## 凭证
<a name="examplecredentials"></a>

运行示例代码之前，请配置您的 AWS 凭证，如 [AWS 使用 适用于 PHP 的 AWS SDK 版本 3 进行身份验证](credentials.md) 中所述。然后导入 适用于 PHP 的 AWS SDK，如 [安装 适用于 PHP 的 AWS SDK 版本 3](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";
}
```

# 使用 适用于 PHP 的 AWS SDK 版本 3 来管理 Amazon S3 存储桶访问权限
<a name="s3-examples-access-permissions"></a>

访问控制列表 (ACL) 是基于资源的访问策略选项之一，可用来管理对存储桶和对象的访问。可以使用 ACL 来向其他 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 设置存储桶权限。

适用于 PHP 的 AWS SDKGitHub[ 上提供了](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)的所有示例代码。

## 凭证
<a name="examplecredentials"></a>

运行示例代码之前，请配置您的 AWS 凭证，如 [AWS 使用 适用于 PHP 的 AWS SDK 版本 3 进行身份验证](credentials.md) 中所述。然后导入 适用于 PHP 的 AWS SDK，如 [安装 适用于 PHP 的 AWS SDK 版本 3](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";
}
```

# 使用 适用于 PHP 的 AWS SDK 版本 3 来配置 Amazon S3 存储桶
<a name="s3-examples-configuring-a-bucket"></a>

跨源资源共享 (CORS) 定义了在一个域中加载的客户端 Web 应用程序与另一个域中的资源交互的方式。借助 Amazon S3 中的 CORS 支持，您可以使用 Amazon S3 来构建各种富客户端 Web 应用程序，并选择性地允许跨源访问您的 Amazon S3 资源。

有关将 CORS 配置用于 Amazon S3 存储桶的更多信息，请参阅[跨源资源共享 (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 配置。

适用于 PHP 的 AWS SDKGitHub[ 上提供了](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)的所有示例代码。

## 凭证
<a name="examplecredentials"></a>

运行示例代码之前，请配置您的 AWS 凭证，如 [AWS 使用 适用于 PHP 的 AWS SDK 版本 3 进行身份验证](credentials.md) 中所述。然后导入 适用于 PHP 的 AWS SDK，如 [安装 适用于 PHP 的 AWS SDK 版本 3](getting-started_installation.md) 中所述。

## 获取 CORS 配置
<a name="get-the-cors-configuration"></a>

使用以下代码创建 PHP 文件。首先创建一个 AWS.S3 客户端服务，然后调用 `getBucketCors` 方法并指定使用所需 CORS 配置的存储桶。

需要的唯一参数是所选存储桶的名称。如果存储桶当前具有 CORS 配置，该配置将作为 [CORSRules 对象](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#shape-corsrule)由 Amazon S3 返回。

 **导入**。

```
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 配置的存储桶，并将 CORS 配置设置为 [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 之间。

以下示例演示如何：
+ 使用将对象上传到 Amazon S3 [ObjectUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectUploader.html)。
+ 使用[MultipartUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.MultipartUploader.html)为 Amazon S3 对象创建分段上传。
+ 使用将对象从一个 Amazon S3 位置复制到另一个位置[ObjectCopier](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectCopier.html)。

的所有示例代码都可以在[此 适用于 PHP 的 AWS SDK 处找到 GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)。

## 凭据
<a name="examplecredentials"></a>

在运行示例代码之前，请配置您的 AWS 证书，如中所述[AWS 使用 适用于 PHP 的 AWS SDK 版本 3 进行身份验证](credentials.md)。然后导入 适用于 PHP 的 AWS SDK，如中所述[安装 适用于 PHP 的 AWS SDK 版本 3](getting-started_installation.md)。

## 对象上传程序
<a name="object-uploader"></a>

如果您不确定是 `PutObject` 还是 `MultipartUploader` 最适合该任务，请使用 `ObjectUploader`。`ObjectUploader` 是使用 `PutObject` 还是 `MultipartUploader` 将大型文件上传到 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);
```

### 配置
<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` 值，SDK 会调用此回调。有关可以添加到`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` 值，SDK 会调用此回调。有关您可以应用于`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();
```

### 配置
<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 流](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";
}
```

# 适用于 PHP 的 AWS SDK 版本 3 的亚马逊 S3 预签名网址
<a name="s3-presigned-url"></a>

您可以通过传递请求信息作为查询字符串参数，而不是使用授权 HTTP 标头来验证特定类型的请求。这在允许第三方浏览器直接访问您的私有 Amazon S3 数据，而无需代理请求时非常有用。其概念是构造一个“预签名”的请求并将其编码为另一个用户可以使用的 URL。此外，您还可以通过指定过期时间来限制预签名请求。

## 为 HTTP GET 请求创建预签名 URL
<a name="s3-presigned-url-get"></a>

以下代码示例演示了如何使用适用于 PHP 的 SDK 为 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;
```

[`createPresignedRequest` 方法的 API 参考](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 的 SDK 为 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;
    }
}
```

# 使用 适用于 PHP 的 AWS SDK 版本 3 的 Amazon S3 预签名 POST
<a name="s3-presigned-post"></a>

与预签名 URL 极其相似，预签名 POST 使您无需向用户提供 AWS 凭证便可向其授予写入访问权限。可以在 [AwsS3PostObjectV4](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.PostObjectV4.html) 实例的帮助下创建预签名 POST 表单。

以下示例演示如何：
+ 使用 [PostObjectV4](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.PostObjectV4.html) 获取 S3 Object POST 上传的数据。

适用于 PHP 的 AWS SDKGitHub[ 上提供了](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)的所有示例代码。

## 凭证
<a name="examplecredentials"></a>

**注意**  
`PostObjectV4` 不能使用来自 AWS IAM Identity Center 的凭证。

运行示例代码之前，请配置您的 AWS 凭证，如 [AWS 使用 适用于 PHP 的 AWS SDK 版本 3 进行身份验证](credentials.md) 中所述。然后导入 适用于 PHP 的 AWS SDK，如 [安装 适用于 PHP 的 AWS SDK 版本 3](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)）
+ 策略的过期时间字符串（可选，默认为 1 小时）。

 **导入**。

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

# 使用 Amazon S3 存储桶作为具有 适用于 PHP 的 AWS SDK 版本 3 的静态 Web 主机
<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) 从存储桶中删除网站配置。

[GitHub 上](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)提供了 适用于 PHP 的 AWS SDK 版本 3 的所有示例代码。

## 凭证
<a name="credentials-s3-examples-static-web-host"></a>

运行示例代码之前，请配置您的 AWS 凭证。请参阅 [适用于 PHP 的 AWS SDK 版本 3 的凭证](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";
}
```

# 结合使用 Amazon S3 存储桶策略与 适用于 PHP 的 AWS SDK 版本 3
<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) 从存储桶中删除策略。

适用于 PHP 的 AWS SDKGitHub[ 上提供了](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)的所有示例代码。

## 凭证
<a name="examplecredentials"></a>

运行示例代码之前，请配置您的 AWS 凭证，如 [AWS 使用 适用于 PHP 的 AWS SDK 版本 3 进行身份验证](credentials.md) 中所述。然后导入 适用于 PHP 的 AWS SDK，如 [安装 适用于 PHP 的 AWS SDK 版本 3](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 接入点 ARN 与 适用于 PHP 的 AWS SDK 版本 3
<a name="s3-examples-access-point-arn"></a>

S3 引入了接入点，这是与 S3 存储桶交互的一种新方式。接入点上可以应用唯一的策略和配置，而不是直接应用到存储桶。通过 适用于 PHP 的 AWS SDK，您可以在存储桶字段中使用接入点 ARN 进行 API 操作，而不是明确指定存储桶名称。有关 S3 接入点和 ARN 工作原理的更多详细信息，可在[此处](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 一起使用，从存储桶中提取对象。
+ 将 [PutoBject](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject) 与接入点 ARN 一起使用，将对象添加到存储桶中。
+ 将 S3 客户端配置为使用 ARN 区域而不是客户端区域。

适用于 PHP 的 AWS SDKGitHub[ 上提供了](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code)的所有示例代码。

## 凭证
<a name="examplecredentials"></a>

运行示例代码之前，请配置您的 AWS 凭证，如 [AWS 使用 适用于 PHP 的 AWS SDK 版本 3 进行身份验证](credentials.md) 中所述。然后导入 适用于 PHP 的 AWS SDK，如 [安装 适用于 PHP 的 AWS SDK 版本 3](getting-started_installation.md) 中所述。

 **导入**。

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

use Aws\S3\S3Client;
```

## 获取对象
<a name="get-object"></a>

首先创建用于指定 AWS 区域和版本的 AWS.S3 客户端服务。然后 `getObject` 使用您的密钥并在 `Bucket` 字段中使用 S3 接入点 ARN 调用该方法，以从与该接入点关联的存储桶中获取对象。

 **示例代码** 

```
$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` 字段中使用 S3 接入点 ARN 调用 `Bucket` 方法，这会将对象放入与该接入点关联的存储桶中。

 **示例代码** 

```
$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 共享配置文件（默认情况下位于 `~/.aws/config` 中）中的配置变量 `s3_use_arn_region`。

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

# 将 Amazon S3 多区域接入点与 适用于 PHP 的 AWS SDK 版本 3 配合使用
<a name="s3-multi-region-access-points"></a>

[Amazon Simple Storage Service（S3）多区域接入点](https://docs.aws.amazon.com//AmazonS3/latest/userguide/MultiRegionAccessPoints.html)提供了一个全局端点，用于在 AWS 区域之间路由 Amazon S3 请求流量。

您可以使用适用于 [PHP 的 SDK、另一个 AWS SDK、S3 控制台或 AWS CLI 来](https://docs.aws.amazon.com//aws-sdk-php/v3/api/api-s3control-2018-08-20.html#createmultiregionaccesspoint)[创建多区域接入点，](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 资源名称（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";
```