

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

# 目录操作

S3 传输管理器可以处理整个目录传输。

## 上传目录
<a name="upload-directory"></a>

S3 传输管理器可以将整个目录上传到 S3 存储桶。 {{<Are the key values the filenames when uploaded?>}}

```php
<?php

use Aws\S3\S3Transfer\Models\UploadDirectoryRequest;
use Aws\S3\S3Transfer\S3TransferManager;

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


$transferManager = new S3TransferManager(null, [
    'default_region' => 'us-west-2'
]);

$uploadDirPromise = $transferManager->uploadDirectory(
    new UploadDirectoryRequest(
        '/path/to/local/directory',
        'amzn-s3-demo-bucket',
        [
            // Additional `putObject` parameters that apply to all files.
            'ACL'          => 'public-read',
            'CacheControl' => 'max-age=3600',
        ],
        [
            // Configuration options.
            'recursive'                      => true,
            'follow_symbolic_links'          => false,
            's3_prefix'                      => 'uploads/2023/',
            's3_delimiter'                   => '/',
            'track_progress'                 => true,
            'filter'                         => function ($file) {
                // Upload only .jpg files.
                return pathinfo($file, PATHINFO_EXTENSION) === 'jpg';
            },
            'upload_object_request_modifier' => function ($args) {
                // Customize request arguments for each file.
                $args['ContentType'] = 'image/jpeg';
            },
        ]
    )
);

// Wait for the upload process to complete.
$result = $uploadDirPromise->wait();

$uploaded = $result->getObjectsUploaded();
$failed = $result->getObjectsFailed();
echo "Uploaded {$uploaded} files. Failed: {$failed}\n";
```

### `uploadDirectory` 方法参数
<a name="upload-directory-parameters"></a>

该`uploadDirectory`方法接受的实例`UploadDirectoryRequest`{{<add link>}}作为参数。

#### `UploadDirectoryRequest` 参数
<a name="upload-directory-request-parameters"></a>


| 参数 | Type | 必需 | 描述 | 
| --- | --- | --- | --- | 
| `$sourceDirectory` | 字符串 | 是 | 要上传的本地目录的路径。 | 
| `$targetBucket` | 字符串 | 是 | 目标 S3 存储桶名称。 | 
| `$uploadRequestArgs` | array | 否 | 所有文件的其他上传对象请求参数。 | 
| `$config` | array | 否 | 目录上传的配置选项。有关配置选项的更多信息，请参阅[以下部分](#upload-directory-config-parameters)。 | 
| `$listeners` | array | 否 | `TransferListener` 对象数组。SDK 会对`TransferListener`每个文件进行克隆。 | 
| `$max_depth` | 布尔 | -1 “运行时默认值” | 要表示递归文件的最大深度，请三步走。 | 
| `$progressTracker` | `TransferListener` | 否 | 所有上传的进度跟踪器。 | 

##### `$config`的选项 `UploadDirectoryRequest`
<a name="upload-directory-config-parameters"></a>


| Option | Type | 默认值 | 说明 | 
| --- | --- | --- | --- | 
| `recursive` | 布尔 | `false` | 是否递归上传子目录。 | 
| `follow_symbolic_links` | 布尔 | `false` | 是否关注符号链接。 | 
| `s3_prefix` | 字符串 | '' | 要添加到所有对象密钥的前缀。 | 
| `s3_delimiter` | 字符串 | '/' | 在 S3 对象键中使用的分隔符。 | 
| track\_progress | 布尔 | false | 是否跟踪进度。 | 
| `max_concurrency` | int | 100 | 并发上传的最大数量。 | 
| `filter` | 可调用 | null | 筛选要上传哪些文件的函数。 | 
| `upload_object_request_modifier` | 可调用 | null | 用于自定义每个上传请求的函数。 | 
| `failure_policy` | 可调用 | null | 处理上传失败的函数。 | 

##### 可调用的选项类型 `$config`
<a name="upload-directory-config-callables"></a>



| 选项名称 | 参数名 | 参数类型 | 参数信息 | 
| --- | --- | --- | --- | 
| filter | $file | SplFileInfo\|字符串 | 如果转换为字符串，则为文件路径。否则，它就是一个实例`SplFileInfo`。 | 
| upload\_object\_request\_modifier | $requestArgs | array | 每个单独上传请求的请求参数。有关数组选项的更多信息，请参阅 [PutoBject](https://docs.amazonaws.cn/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject) 方法的参数语法部分。 | 
| failure\_policy | $uploadRequestArgs | array | 每个单独上传请求的请求参数。有关数组选项的更多信息，请参阅数组选项的 [PutoBject](https://docs.amazonaws.cn/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject) 方法的参数语法部分。 | 
|  | $uploadDirectoryArgs | array | 包含源目录和上传目录操作的目标存储桶的数组。 | 
|  | $reason | Throwable\|字符串 | 包含有关导致失败的原因的信息的异常持有者。 | 
|  | $uploadDirectoryResult | UploadDirectoryResult | 包含成功上传的对象数量和失败的对象数量的对象。 | 

当该`uploadDirectory`方法成功运行时，它将返回`UploadDirectoryResult`{{<add link>}}。

## 下载目录
<a name="download-directory"></a>

您可以从 S3 存储桶下载目录。 {{<Are the filenames the key values when downloaded? If there is no extension in the key, is there also no extension on the file?>}}

```php
<?php

use Aws\S3\S3Transfer\Models\DownloadDirectoryRequest;
use Aws\S3\S3Transfer\S3TransferManager;

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


$transferManager = new S3TransferManager(null, [
    'default_region' => 'us-west-2'
]);

$downloadDirPromise = $transferManager->downloadDirectory(
    new DownloadDirectoryRequest(
        'amzn-s3-demo-bucket',
        '/path/to/local/directory',
        [
            // Additional `getObject` parameters that apply to all files.
        ],
        [
            // Configuration options.
            's3_prefix'                        => 'uploads/2023/',
            's3_delimiter'                     => '/',
            'track_progress'                   => true,
            'filter'                           => function ($key) {
                // Download only .jpg files.
                return pathinfo($key, PATHINFO_EXTENSION) === 'jpg';
            },
            'download_object_request_modifier' => function ($args) {
                // Customize request arguments for each file.
                $args['ResponseContentType'] = 'image/jpeg';
            },
            'list_objects_v2_args'              => [
                'MaxKeys' => 1000,
                'Prefix'  => 'uploads/2023/',
            ],
            'fails_when_destination_exists'    => true,
        ]
    )
);

// Wait for the download process to complete.
$result = $downloadDirPromise->wait();

$downloaded = $result->getObjectsDownloaded();
$failed = $result->getObjectsFailed();
echo "Downloaded {$downloaded} files. Failed: {$failed}\n";
```

### `downloadDirectory` 方法参数
<a name="download-directory-parameters"></a>

该`downloadDirectory`方法接受的实例`DownloadDirectoryRequest`{{<add link>}}作为参数。

#### `DownloadDirectoryRequest` 参数
<a name="download-directory-request-parameters"></a>


| 参数 | Type | 必需 | 描述 | 
| --- | --- | --- | --- | 
| `$sourceBucket` | 字符串 | 是 | 从中下载对象的源 S3 存储桶名称。 | 
| `$destinationDirectory` | 字符串 | 是 | 要将文件下载到的本地目录。 | 
| `$downloadRequestArgs` | array | 否 | 所有文件的其他下载对象请求参数。 | 
| `$config` | array | 否 | 目录下载的配置选项。有关配置选项的更多信息，请参阅[以下部分](#download-directory-config-parameters)。 | 
| `$listeners` | array | 否 | `TransferListener` 对象数组。SDK 会对`TransferListener`每个文件进行克隆。 | 
| `$progressTracker` | `TransferListener` | 否 | 所有下载的进度跟踪器。 | 

##### `$config`的选项 `DownloadDirectoryRequest`
<a name="download-directory-config-parameters"></a>


| Option | Type | 默认值 | 说明 | 
| --- | --- | --- | --- | 
| `s3_prefix` | 字符串 | '' | 筛选前缀（如果不在`list_objects_v2_args`）。 | 
| `track_progress` | 布尔 | `false` | 是否跟踪进度。 | 
| `filter` | 可调用 | `null` | 筛选要下载的 S3 对象的函数。 | 
| `download_object_request_modifier` | 可调用 | `null` | 自定义每个下载请求的功能。 | 
| `list_objects_v2_args` | array | [] | [`ListObjectsV2`](https://docs.amazonaws.cn/aws-sdk-php/v3/api/api-s3-2006-03-01.html#listobjectsv2)操作的参数。此操作获取要下载的对象的元数据。 | 
| `fails_when_destination_exists` | 布尔 | false | 当对象目标文件路径已经存在时是否失败。 | 
| `failure_policy` | 可调用 | null | 处理下载失败的函数。 | 
| `max_concurrency` | int | 100 | 并发下载的最大数量。 | 
| `target_part_size_bytes` | int | 变化 | 当分段下载类型设定范围时，分段下载的分段大小。 | 

##### 可调用的选项类型 `$config`
<a name="download-dir-callable-options"></a>



| 选项名称 | 参数名 | 参数类型 | 参数信息 | 
| --- | --- | --- | --- | 
| filter | $objectKey | 字符串 | 存储桶中的对象密钥名称。 | 
| download\_object\_request\_modifier | $requestArgs | array | 每个单独下载请求的请求参数。有关数组选项的更多信息，请参阅 [getObject](https://docs.amazonaws.cn/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getobject) 方法的参数语法部分。 | 
| failure\_policy | $downloadObjectRequestArgs | array | 每个单独下载请求的请求参数。有关数组选项的更多信息，请参阅 [getObject](https://docs.amazonaws.cn/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getobject) 方法的*参数语法*部分。 | 
|  | $downloadDirectoryRequest | array | 包含源存储桶和下载目录操作的目标目录的数组。 | 
|  | $reason | Throwable | 包含有关导致失败的原因的信息的异常持有者。 | 
|  | $downloadDirectoryResult | DownloadDirectoryResult {{<add link>}} | 包含成功下载的对象数量和失败的对象数量的对象。 | 

## 目录操作的工作原理
<a name="directory-operations-behavior"></a>

本节介绍 S3 传输管理器在目录操作期间如何处理文件路径和对象密钥。

### 上传路径处理
<a name="upload-path-handling"></a>

上传目录时，SDK 会根据文件路径构造 S3 对象密钥：

1. 计算每个文件相对于源目录的路径

1. 如果指定，则在`s3_prefix`值前面加上（自动添加尾部斜杠）

1. 将 OS 目录分隔符替换为`s3_delimiter`（默认`/`）

该`recursive`选项控制是否包含子目录。`false`（默认）时，仅上传顶级文件。当`true`上传子目录中的所有文件时，在对象密钥中保留目录结构。

**注意**  
S3 中每个上传文件的密钥将是提供的 s3 前缀，默认情况下为空，再加上文件从指定源目录开始的相对路径。此外，我们将解析的密钥名称中的目录分隔符替换为提供的 s3 分隔符，默认情况下它将是/。  
**示例 1**  

```php
$sourceDirectory = "/opt/my-upload-directory";
$s3Prefix = "important/";
$s3Delimiter = "/"; // Default value
```
目录结构  

```php
/opt/my-upload-directory/
-- my-file1.txt
-- my-file-2.txt
-- sub-dir/
---- my-another-file1.txt
---- my-another-file2.txt
```
每个文件的密钥将是：  

```php
$s3Prefix + $fileRelativePath;
```

```php
- important/my-file1.txt
- important/my-file-2.txt
- important/sub-dir/my-another-file1.txt
- important/sub-dir/my-another-file2.txt
```
**示例 2**  

```php
$sourceDirectory = "/opt/my-docs";
$s3Prefix = ''; // No provided and it will defaulted to empty string
$s3Delimiter = "/"; // Default value
```
目录结构  

```php
/opt/my-docs/
-- my-file1.txt
-- my-file-2.txt
-- sub-dir/
---- my-another-file1.txt
---- my-another-file2.txt
```
每个文件的密钥将是：  

```php
$s3Prefix + $fileRelativePath;
```

```php
- my-file1.txt
- my-file-2.txt
- sub-dir/my-another-file1.txt
- sub-dir/my-another-file2.txt
```

**Example 上传目录路径处理**  

```php
<?php
// Source directory: /home/user/photos/
//   fla/beach.jpg
//   fla/sunset.jpg
//   fla/pool/party.jpg
// With s3_prefix: '2023' and recursive: true
// Results:
//   2023/fla/beach.jpg
//   2023/fla/sunset.jpg
//   2023/fla/pool/party.jpg
```

### 下载路径处理
<a name="download-path-handling"></a>

下载目录时，SDK 会根据 S3 对象密钥构造本地文件路径：

1. 如果指定，则`s3_prefix`从对象密钥中移除

1. 将 S3 分隔符 (`/`) 替换为操作系统目录分隔符

1. 将结果追加到目标目录

下载总是递归的。SDK 会检索指定前缀下的所有对象，并根据需要创建子目录。为了安全起见，它会验证路径不会解析到目标目录之外的路径。

**Example 下载目录路径处理**  

```php
<?php
// S3 objects:
//   2023/fla/beach.jpg
//   2023/fla/sunset.jpg
//   2023/fla/pool/party.jpg
// With s3_prefix: '2023' and destination: /home/user/downloads
// Results:
//   /home/user/downloads/fla/beach.jpg
//   /home/user/downloads/fla/sunset.jpg
//   /home/user/downloads/fla/pool/party.jpg
```

**注意**  
下载对象的文件路径将按如下方式解析：  
s3 前缀（如果提供）将从对象密钥中删除。
如果 s3Delimiter 与操作系统目录分隔符不同，则 s3 分隔符将替换为操作系统目录分隔符。
**示例 1**  

```php
$s3Prefix = "my-prefix";
$s3Objects = [
    "my-prefix/file-1.txt", 
    "my-prefix/file-2.txt", 
    "my-prefix/subdir/file-1.txt"
];
$targetDirectory = "/opt/bucket/downloads/";
```
下载完这些对象后，将按如下方式放置：  

```php
/opt/bucket/downloads/
-- file-1.txt
-- file-2.txt
-- subdir/
---- file-1.txt
```
如我们所见，该前缀已从对象的最终文件路径中删除。  
**示例 2-没有 s3 前缀**  

```php
$s3Prefix = ""; // No provided
$s3Objects = [
    "README.md",
    "my-docs/file-1.txt", 
    "my-docs/file-2.txt", 
    "my-docs/statements/file-1.txt"
];
$targetDirectory = "/opt/bucket/downloads/";
```
下载完这些对象后，将按如下方式放置：  

```php
/opt/bucket/downloads/
-- README.md
-- my-docs/
---- file-1.txt
---- file-2.txt
---- statements/
------ file-1.txt
```