# 在 AWS CLI 中使用 Amazon S3
<a name="cli-services-s3"></a>


| Amazon Simple Storage Service (Amazon S3) 简介 | 
| --- | 
|    | 

您可以使用 AWS Command Line Interface (AWS CLI) 访问 Amazon Simple Storage Service (Amazon S3) 的功能。Amazon S3 是一种高度可扩展的持久对象存储服务。Amazon S3 旨在提供几乎无限的存储容量，使其成为满足各种数据存储和管理需求的理想解决方案。

借助 Amazon S3，您能够以对象的形式存储和检索从小文件到大型数据集的任意数量的数据。每个对象都存储在名为存储桶的容器中，可以通过 AWS 管理控制台或 AWS SDK、工具和 AWS CLI 以编程方式访问和管理存储桶。

除基本存储之外，Amazon S3 还提供一系列功能，包括生命周期管理、版本控制、可扩展性和安全性。这些功能可与其他 AWS 服务集成，使您能够构建可根据需要扩展的云端解决方案。

AWS CLI 提供两个层级的命令来访问 Amazon S3：
+ **s3** – 自定义专门针对 AWS CLI 执行的高级命令，以简化常见任务，比如创建、操作、删除和同步对象及存储桶。
+ **s3api** – 提供对所有 Amazon S3 API 操作的直接访问，使您能够执行高级操作。

**Topics**
+ [在 AWS CLI 中使用高级（s3）命令](cli-services-s3-commands.md)
+ [在 AWS CLI 中使用 API 级 (s3api) 命令](cli-services-s3-apicommands.md)
+ [AWS CLI 中的 Amazon S3 存储桶生命周期脚本示例](cli-services-s3-lifecycle-example.md)

# 在 AWS CLI 中使用高级（s3）命令
<a name="cli-services-s3-commands"></a>

本主题介绍一些命令，可用于在 AWS CLI 中通过 [https://docs.aws.amazon.com/cli/latest/reference/s3/index.html](https://docs.aws.amazon.com/cli/latest/reference/s3/index.html) 命令管理 Amazon S3 存储桶和对象。有关本主题未涵盖的命令和其他命令示例，请参阅**《AWS CLI 参考》中的 [https://docs.aws.amazon.com/cli/latest/reference/s3/index.html](https://docs.aws.amazon.com/cli/latest/reference/s3/index.html) 命令。

高级别 `aws s3` 命令简化了 Amazon S3 对象管理。使用这些命令，您能够在 Amazon S3 自身中管理其内容以及使用本地目录管理这些内容。

**Topics**
+ [先决条件](#using-s3-commands-prereqs)
+ [开始之前](#using-s3-commands-before)
+ [创建存储桶](#using-s3-commands-managing-buckets-creating)
+ [列出存储桶和对象](#using-s3-commands-listing-buckets)
+ [删除存储桶](#using-s3-commands-delete-buckets)
+ [删除对象](#using-s3-commands-delete-objects)
+ [移动对象](#using-s3-commands-managing-objects-move)
+ [复制对象](#using-s3-commands-managing-objects-copy)
+ [同步对象](#using-s3-commands-managing-objects-sync)
+ [s3 命令的常用选项](#using-s3-commands-managing-objects-param)
+ [资源](#using-s3-commands-managing-buckets-references)

## 先决条件
<a name="using-s3-commands-prereqs"></a>

要运行 `s3` 命令，您需要：
+ 安装和配置 AWS CLI。有关更多信息，请参阅 [安装或更新最新版本的 AWS CLI](getting-started-install.md) 和 [AWS CLI 身份验证和访问凭证](cli-chap-authentication.md)。
+ 您使用的配置文件必须具有允许示例代码执行AWS操作的权限。
+ 需了解如下 Amazon S3 术语：
  + **存储桶** – 顶级 Amazon S3 文件夹。
  + **前缀 ** – 存储桶中的 Amazon S3 文件夹。
  + **对象** – 托管在 Amazon S3 存储桶中的任何项。

## 开始之前
<a name="using-s3-commands-before"></a>

本节介绍在使用 `aws s3` 命令之前需要注意的一些事项。

### 大型对象上载
<a name="using-s3-commands-before-large"></a>

当您使用 `aws s3` 命令将大型对象上传到 Amazon S3 存储桶时，AWS CLI 会自动执行分段上传。使用这些 `aws s3` 命令时，您无法恢复失败的上传操作。

如果分段上传由于超时而失败，或者您在 AWS CLI 中手动取消该操作，则 AWS CLI 会停止上传并清除已创建的任何文件。此过程可能耗时数分钟。

如果使用 kill 命令或者由于系统故障而取消了分段上传或清理过程，则创建的文件将保留在 Amazon S3 存储桶中。要清除分段上传，请使用 [s3api abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html) 命令。

### 分段复制中的文件属性和标签
<a name="using-s3-commands-before-tags"></a>

当您使用 `aws s3` 命名空间中的 AWS CLI 版本 1 版本命令将文件从一个 Amazon S3 存储桶位置复制到另一个 Amazon S3 存储桶位置，并且该操作使用[分段复制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CopyingObjctsMPUapi.html)时，源对象中的文件属性不会被复制到目标对象。

原定设置情况下，`s3` 命名空间中执行分段复制的 AWS CLI 版本 2 命令会将所有标签和以下属性集从源副本传输到目标副本：`content-type`、`content-language`、`content-encoding`、`content-disposition`、`cache-control`、`expires` 和 `metadata`。

这可能会导致对 Amazon S3 端点进行其他 AWS API 调用，而在使用 AWS CLI 版本 1 时，将不会进行这些调用。这些调用可能包括：`HeadObject`、`GetObjectTagging` 和 `PutObjectTagging`。

如果需要在 AWS CLI 版本 2 命令中更改此默认行为，请使用 `--copy-props` 参数指定以下选项之一：
+ **default** – 默认值。指定该复制包含附加到源对象的所有标签以及用于非分段复制的 `--metadata-directive` 参数所包含的属性：`content-type`、`content-language`、`content-encoding`、`content-disposition`、`cache-control`、`expires` 和 `metadata`。
+ **metadata-directive** – 指定该复制仅包含用于非分段复制的 `--metadata-directive` 参数所包含的属性。它不会复制任何标签。
+ **none** – 指定该复制不包含源对象中的任何属性。

## 创建存储桶
<a name="using-s3-commands-managing-buckets-creating"></a>

使用 [https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html](https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html) 命令创建存储桶。存储桶名称必须是***全局*** 唯一的（在所有 Amazon S3 存储桶中都是唯一的），并且应符合 DNS 标准。

存储桶名称可以包含小写字母、数字、连字符和点号。存储桶名称只能以字母或数字开头和结尾，连字符或点号后不能跟点号。

**语法**

```
$ aws s3 mb <target> [--options]
```

### s3 mb 示例
<a name="using-s3-commands-managing-buckets-creating-examples"></a>

以下示例将创建 `s3://amzn-s3-demo-bucket` 存储桶。

```
$ aws s3 mb s3://amzn-s3-demo-bucket
```

## 列出存储桶和对象
<a name="using-s3-commands-listing-buckets"></a>

要列出存储桶、文件夹或对象，请使用 [https://docs.aws.amazon.com/cli/latest/reference/s3/ls.html](https://docs.aws.amazon.com/cli/latest/reference/s3/ls.html) 命令。使用不带目标或选项的命令时，将会列出所有存储桶。

**语法**

```
$ aws s3 ls <target> [--options]
```

有关与此命令一起使用的一些常见选项以及相关示例，请参阅 [s3 命令的常用选项](#using-s3-commands-managing-objects-param)。有关可用选项的完整列表，请参阅*《AWS CLI 命令参考》*中的 [https://docs.aws.amazon.com/cli/latest/reference/s3/ls.html](https://docs.aws.amazon.com/cli/latest/reference/s3/ls.html)。

### s3 ls 示例
<a name="using-s3-commands-managing-objects-list-examples"></a>

以下示例列出您的所有 Amazon S3 存储桶。

```
$ aws s3 ls
2018-12-11 17:08:50 amzn-s3-demo-bucket1
2018-12-14 14:55:44 amzn-s3-demo-bucket2
```

下面的命令列出一个存储桶中的所有对象和前缀。在本示例输出中，前缀 `example/` 有一个名为 `MyFile1.txt` 的文件。

```
$ aws s3 ls s3://amzn-s3-demo-bucket
                           PRE example/
2018-12-04 19:05:48          3 MyFile1.txt
```

您可以通过在命令中包含特定前缀将输出筛选到此前缀。下面的命令列出 *bucket-name/example/* 中的对象（即 *bucket-name* 中按前缀 *example/* 筛选出的对象）。

```
$ aws s3 ls s3://amzn-s3-demo-bucket/example/
2018-12-06 18:59:32          3 MyFile1.txt
```

要仅显示特定区域内的存储桶和对象，请使用 `--region` 选项

```
$ aws s3 ls --region us-east-2
2018-12-06 18:59:32          3 MyFile1.txt
```

如果您的存储桶和对象列表比较大，可以使用 `--max-items` 或 `--page-size` 选项对结果进行分页。`--max-items` 选项可限制调用中返回的存储桶和对象的总数，`--page-size` 选项可限制页面上列出的存储桶和对象的数量。

```
$ aws s3 ls --max-items 100 --page-size 10
```

有关分页的更多信息，请参阅[如何使用 --page-size 参数](cli-usage-pagination.md#cli-usage-pagination-pagesize)和[如何使用 --max-items 参数](cli-usage-pagination.md#cli-usage-pagination-maxitems)。

## 删除存储桶
<a name="using-s3-commands-delete-buckets"></a>

要删除存储桶，请使用 [https://docs.aws.amazon.com/cli/latest/reference/s3/rb.html](https://docs.aws.amazon.com/cli/latest/reference/s3/rb.html) 命令。

**语法**

```
$ aws s3 rb <target> [--options]
```

### s3 rb 示例
<a name="using-s3-commands-removing-buckets-examples"></a>

以下示例删除 `s3://amzn-s3-demo-bucket` 存储桶。

```
$ aws s3 rb s3://amzn-s3-demo-bucket
```

默认情况下，存储桶必须为空，此操作才能成功。要删除不为空的存储桶，您必须包含 `--force` 选项。如果您使用的是受版本控制的存储桶，即其中包含以前删除“但仍保留”的对象，则此命令 *不* 允许您删除该存储桶。您必须先删除所有内容。

以下示例命令删除存储桶中的所有对象和前缀，然后删除存储桶本身。

```
$ aws s3 rb s3://amzn-s3-demo-bucket --force
```

## 删除对象
<a name="using-s3-commands-delete-objects"></a>

要删除存储桶或本地目录中的对象，请使用 [https://docs.aws.amazon.com/cli/latest/reference/s3/rm.html](https://docs.aws.amazon.com/cli/latest/reference/s3/rm.html) 命令。

**语法**

```
$ aws s3 rm  <target> [--options]
```

有关与此命令一起使用的一些常见选项以及相关示例，请参阅 [s3 命令的常用选项](#using-s3-commands-managing-objects-param)。有关选项的完整列表，请参阅**《AWS CLI 命令参考》中的 [https://docs.aws.amazon.com/cli/latest/reference/s3/rm.html](https://docs.aws.amazon.com/cli/latest/reference/s3/rm.html)。

### s3 rm 示例
<a name="using-s3-commands-delete-objects-examples"></a>

以下示例将从 `filename.txt` 删除 `s3://amzn-s3-demo-bucket/example`。

```
$ aws s3 rm s3://amzn-s3-demo-bucket/example/filename.txt
```

以下示例使用 `s3://amzn-s3-demo-bucket/example` 选项从 `--recursive` 删除所有对象。

```
$ aws s3 rm s3://amzn-s3-demo-bucket/example --recursive
```

## 移动对象
<a name="using-s3-commands-managing-objects-move"></a>

使用 [https://docs.aws.amazon.com/cli/latest/reference/s3/mv.html](https://docs.aws.amazon.com/cli/latest/reference/s3/mv.html) 命令可从存储桶或本地目录中移动对象。`s3 mv` 命令将源对象或文件复制到指定目标，然后删除源对象或文件。

**语法**

```
$ aws s3 mv <source> <target> [--options]
```

有关与此命令一起使用的一些常见选项以及相关示例，请参阅 [s3 命令的常用选项](#using-s3-commands-managing-objects-param)。有关可用选项的完整列表，请参阅*《AWS CLI 命令参考》*中的 [https://docs.aws.amazon.com/cli/latest/reference/s3/mv.html](https://docs.aws.amazon.com/cli/latest/reference/s3/mv.html)。

**警告**  
如果您在 Amazon S3 源或目标 URI 中使用任何类型的接入点 ARN 或接入点别名，则必须格外注意源和目标 Amazon S3 URI 解析到不同的底层存储桶。如果源存储桶和目标存储桶相同，则可以将源文件或对象移到其自身上，这可能会导致源文件或对象被意外删除。要验证源存储桶和目标存储桶是否不同，请使用 `--validate-same-s3-paths` 参数或将环境变量 ``AWS_CLI_S3_MV_VALIDATE_SAME_S3_PATHS`` 设置为 `true`。

### s3 mv 示例
<a name="using-s3-commands-managing-objects-move-examples"></a>

以下示例将所有对象从 `s3://amzn-s3-demo-bucket/example` 移动到 `s3://amzn-s3-demo-bucket/`。

```
$ aws s3 mv s3://amzn-s3-demo-bucket/example s3://amzn-s3-demo-bucket/
```

以下示例使用 `s3 mv` 命令，将本地文件从当前工作目录移动到 Amazon S3 存储桶。

```
$ aws s3 mv filename.txt s3://amzn-s3-demo-bucket
```

以下示例将文件从 Amazon S3 存储桶移动到当前工作目录，其中 `./` 指定当前的工作目录。

```
$ aws s3 mv s3://amzn-s3-demo-bucket/filename.txt ./
```

## 复制对象
<a name="using-s3-commands-managing-objects-copy"></a>

使用 [https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html) 命令可从存储桶或本地目录复制对象。

**语法**

```
$ aws s3 cp <source> <target> [--options]
```

您可以使用短划线参数，将文件流式传输到标准输入（`stdin`）或标准输出（`stdout`）。

**警告**  
如果您使用的是 PowerShell，则 Shell 可能会更改 CRLF 编码，或者将 CRLF 添加到管道输入或输出或重定向的输出中。

`s3 cp` 命令使用以下语法，将文件流从 `stdin` 上传到指定的存储桶。

**语法**

```
$ aws s3 cp - <target> [--options]
```

`s3 cp` 命令使用以下语法下载 `stdout` 的 Amazon S3 文件流。

**语法**

```
$ aws s3 cp <target> [--options] -
```

有关与此命令一起使用的一些常见选项以及相关示例，请参阅 [s3 命令的常用选项](#using-s3-commands-managing-objects-param)。有关选项的完整列表，请参阅**《AWS CLI 命令参考》中的 [https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html)。

### `s3 cp` 示例
<a name="using-s3-commands-managing-objects-copy-examples"></a>

以下示例将所有对象从 `s3://amzn-s3-demo-bucket/example` 复制到 `s3://amzn-s3-demo-bucket/`。

```
$ aws s3 cp s3://amzn-s3-demo-bucket/example s3://amzn-s3-demo-bucket/
```

以下示例使用 `s3 cp` 命令，将本地文件从当前工作目录复制到 Amazon S3 存储桶。

```
$ aws s3 cp filename.txt s3://amzn-s3-demo-bucket
```

以下示例将文件从 Amazon S3 存储桶复制到当前工作目录，其中 `./` 指定当前的工作目录。

```
$ aws s3 cp s3://amzn-s3-demo-bucket/filename.txt ./
```

以下示例使用 echo 将文本“hello world”流式传输到 `s3://bucket-name/filename.txt` 文件。

```
$ echo "hello world" | aws s3 cp - s3://amzn-s3-demo-bucket/filename.txt
```

以下示例将 `s3://amzn-s3-demo-bucket/filename.txt` 文件流式传输到 `stdout`，并将内容输出到控制台。

```
$ aws s3 cp s3://amzn-s3-demo-bucket/filename.txt -
hello world
```

以下示例将 `s3://bucket-name/pre` 的内容流式传输到 `stdout`，使用 `bzip2` 命令压缩文件，并将名为 `key.bz2` 的新压缩文件上传到 `s3://bucket-name`。

```
$ aws s3 cp s3://amzn-s3-demo-bucket/pre - | bzip2 --best | aws s3 cp - s3://amzn-s3-demo-bucket/key.bz2
```

## 同步对象
<a name="using-s3-commands-managing-objects-sync"></a>

[https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html) 命令同步一个存储桶与一个目录中的内容，或者同步两个存储桶中的内容。通常，`s3 sync` 在源和目标之间复制缺失或过时的文件或对象。不过，您还可以提供 `--delete` 选项来从目标中删除源中不存在的文件或对象。

**语法**

```
$ aws s3 sync <source> <target> [--options]
```

有关与此命令一起使用的一些常见选项以及相关示例，请参阅 [s3 命令的常用选项](#using-s3-commands-managing-objects-param)。有关选项的完整列表，请参阅**《AWS CLI 命令参考》中的 [https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html)。

### s3 sync 示例
<a name="using-s3-commands-managing-objects-sync-examples"></a>

下面的示例将名为 *amzn-s3-demo-bucket* 的存储桶中名为 *path* 的 Amazon S3 前缀中的内容与当前工作目录同步。

`s3 sync` 将更新与目标位置中同名文件的大小或修改时间不同的任何文件。输出显示在同步期间执行的特定操作。请注意，该操作将与 `MySubdirectory` 递归地同步子目录 `s3://amzn-s3-demo-bucket/path/MySubdirectory` 及其内容。

```
$ aws s3 sync . s3://amzn-s3-demo-bucket/path
upload: MySubdirectory\MyFile3.txt to s3://amzn-s3-demo-bucket/path/MySubdirectory/MyFile3.txt
upload: MyFile2.txt to s3://amzn-s3-demo-bucket/path/MyFile2.txt
upload: MyFile1.txt to s3://amzn-s3-demo-bucket/path/MyFile1.txt
```

下面的示例对上一示例进行了扩展，显示了如何使用 `--delete` 选项。

```
// Delete local file
$ rm ./MyFile1.txt

// Attempt sync without --delete option - nothing happens
$ aws s3 sync . s3://amzn-s3-demo-bucket/path

// Sync with deletion - object is deleted from bucket
$ aws s3 sync . s3://amzn-s3-demo-bucket/path --delete
delete: s3://amzn-s3-demo-bucket/path/MyFile1.txt

// Delete object from bucket
$ aws s3 rm s3://amzn-s3-demo-bucket/path/MySubdirectory/MyFile3.txt
delete: s3://amzn-s3-demo-bucket/path/MySubdirectory/MyFile3.txt

// Sync with deletion - local file is deleted
$ aws s3 sync s3://amzn-s3-demo-bucket/path . --delete
delete: MySubdirectory\MyFile3.txt

// Sync with Infrequent Access storage class
$ aws s3 sync . s3://amzn-s3-demo-bucket/path --storage-class STANDARD_IA
```

使用 `--delete` 选项时，`--exclude` 和 `--include` 选项可以筛选要在 `s3 sync` 操作过程中删除的文件或对象。在这种情况下，参数字符串必须指定要在目标目录或存储桶上下文中包含或排除在删除操作中的文件。下面是一个示例。

```
Assume local directory and s3://amzn-s3-demo-bucket/path currently in sync and each contains 3 files:
MyFile1.txt
MyFile2.rtf
MyFile88.txt
'''

// Sync with delete, excluding files that match a pattern. MyFile88.txt is deleted, while remote MyFile1.txt is not.
$ aws s3 sync . s3://amzn-s3-demo-bucket/path --delete --exclude "path/MyFile?.txt"
delete: s3://amzn-s3-demo-bucket/path/MyFile88.txt
'''

// Sync with delete, excluding MyFile2.rtf - local file is NOT deleted
$ aws s3 sync s3://amzn-s3-demo-bucket/path . --delete --exclude "./MyFile2.rtf"
download: s3://amzn-s3-demo-bucket/path/MyFile1.txt to MyFile1.txt
'''

// Sync with delete, local copy of MyFile2.rtf is deleted
$ aws s3 sync s3://amzn-s3-demo-bucket/path . --delete
delete: MyFile2.rtf
```

## s3 命令的常用选项
<a name="using-s3-commands-managing-objects-param"></a>

以下选项经常用于本主题中所述的命令。有关可在命令中使用的选项的完整列表，请参阅[《AWS CLI 版本 2 参考指南》](https://docs.aws.amazon.com/cli/latest/reference/index.html)中的特定命令。

**acl**  
`s3 sync` 和 `s3 cp` 可以使用 `--acl` 选项。这样您能够为复制到 Amazon S3 的文件设置访问权限。`--acl` 选项接受 `private`、`public-read` 和 `public-read-write` 值。有关更多信息，请参阅《Amazon S3 用户指南》**中的[标准 ACL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl)。  

```
$ aws s3 sync . s3://amzn-s3-demo-bucket/path --acl public-read
```

**exclude**  
使用 `s3 cp`、`s3 mv`、`s3 sync` 或 `s3 rm` 命令时，可以使用 `--exclude` 或 `--include` 选项筛选结果。`--exclude` 选项将规则设置为仅从命令中排除对象，并且系统将按照指定的顺序应用这些选项。如下例所示。  

```
Local directory contains 3 files:
MyFile1.txt
MyFile2.rtf
MyFile88.txt

// Exclude all .txt files, resulting in only MyFile2.rtf being copied
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --exclude "*.txt"

// Exclude all .txt files but include all files with the "MyFile*.txt" format, resulting in, MyFile1.txt, MyFile2.rtf, MyFile88.txt being copied
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --exclude "*.txt" --include "MyFile*.txt"

// Exclude all .txt files, but include all files with the "MyFile*.txt" format, but exclude all files with the "MyFile?.txt" format resulting in, MyFile2.rtf and MyFile88.txt being copied
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --exclude "*.txt" --include "MyFile*.txt" --exclude "MyFile?.txt"
```

**情况如：**  
使用 `s3 cp`、`s3 mv`、`s3 sync` 或 `s3 rm` 命令时，可以使用 `--exclude` 或 `--include` 选项筛选结果。`--include` 选项将规则设置为仅包括为命令指定的对象，并且系统将按照指定的顺序应用这些选项。如下例所示。  

```
Local directory contains 3 files:
MyFile1.txt
MyFile2.rtf
MyFile88.txt

// Include all .txt files, resulting in MyFile1.txt and MyFile88.txt being copied
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "*.txt"

// Include all .txt files but exclude all files with the "MyFile*.txt" format, resulting in no files being copied
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "*.txt" --exclude "MyFile*.txt"

// Include all .txt files, but exclude all files with the "MyFile*.txt" format, but include all files with the "MyFile?.txt" format resulting in MyFile1.txt being copied

$ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "*.txt" --exclude "MyFile*.txt" --include "MyFile?.txt"
```

**授予**  
`s3 cp`、`s3 mv` 和 `s3 sync` 命令包括一个 `--grants` 选项，可用来向指定的用户或组授予对对象的权限。使用以下语法对权限列表设置 `--grants` 选项。将 `Permission`、`Grantee_Type` 和 `Grantee_ID` 替换为您自己的值。  
**语法**  

```
--grants Permission=Grantee_Type=Grantee_ID
         [Permission=Grantee_Type=Grantee_ID ...]
```
每个值都包含以下元素：  
+ *权限* – 指定授予的权限。可以设置为 `read`、`readacl`、`writeacl` 或 `full`。
+ *Grantee\$1Type* – 指定如何标识被授权者。可以设置为 `uri`、`emailaddress` 或 `id`。
+ *Grantee\$1ID* – 根据 *Grantee\$1Type*.指定被授权者。
  + `uri` – 组 URI。有关更多信息，请参阅 [谁是授权者？](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ACLOverview.html#SpecifyingGrantee)
  + `emailaddress` – 账户的电子邮件地址。
  + `id` – 账户的规范 ID。
有关 Amazon S3 访问控制的更多信息，请参阅 [访问控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingAuthAccess.html)。  
下面的示例将一个对象复制到一个存储桶中。它授予所有人对对象的 `read` 权限，向 `full` 的关联账户授予 `read` 权限（`readacl`、`writeacl` 和 `user@example.com`）。  

```
$ aws s3 cp file.txt s3://amzn-s3-demo-bucket/ --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers full=emailaddress=user@example.com
```
还可以为上传到 Amazon S3 的对象指定非默认存储类（`REDUCED_REDUNDANCY` 或 `STANDARD_IA`）。为此，请使用 `--storage-class` 选项。  

```
$ aws s3 cp file.txt s3://amzn-s3-demo-bucket/ --storage-class REDUCED_REDUNDANCY
```

**no-overwrite**  
`s3 cp`、`s3 mv` 和 `s3 sync` 命令包含一个 `--no-overwrite` 选项，您可以使用该选项来防止覆盖目标中已存在的对象。  
以下示例仅当在本地目录中尚不存在对象时，才会将该对象从存储桶复制到本地目录。  

```
$ aws s3 cp --no-overwrite s3://amzn-s3-demo-bucket/file.txt file.txt
```
以下示例以递归方式将文件从本地目录复制到存储桶。它只会复制那些在存储桶中尚未存在的文件。  

```
$ aws s3 cp --recursive --no-overwrite /path/to/demo-files/ s3://amzn-s3-demo-bucket/demo-files/
```
以下示例仅当在存储桶目标位置中尚不存在对象时，才会将该对象从本地目录移动到存储桶。  

```
$ aws s3 mv --no-overwrite file.txt s3://amzn-s3-demo-bucket/file.txt
```
以下示例将文件从本地目录同步到存储桶。它只会同步目标存储桶中尚不存在的文件。  

```
$ aws s3 sync --no-overwrite /path/to/demo-files/ s3://amzn-s3-demo-bucket/demo-files/
```

**recursive**  
使用此选项时，系统针对所指定目录或前缀下的所有文件或对象执行该命令。以下示例删除 `s3://amzn-s3-demo-bucket/path` 及其所有内容。  

```
$ aws s3 rm s3://amzn-s3-demo-bucket/path --recursive
```

## 资源
<a name="using-s3-commands-managing-buckets-references"></a>

** AWS CLI《参考：**》
+ [https://docs.aws.amazon.com/cli/latest/reference/s3/index.html](https://docs.aws.amazon.com/cli/latest/reference/s3/index.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html](https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3/mv.html](https://docs.aws.amazon.com/cli/latest/reference/s3/mv.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3/ls.html](https://docs.aws.amazon.com/cli/latest/reference/s3/ls.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3/rb.html](https://docs.aws.amazon.com/cli/latest/reference/s3/rb.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3/rm.html](https://docs.aws.amazon.com/cli/latest/reference/s3/rm.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html)

**《服务参考：**》
+ 《Amazon S3 开发人员指南》**中的[使用 Amazon S3 存储桶](https://docs.aws.amazon.com//AmazonS3/latest/userguide/UsingBucket.html)
+ 《Amazon S3 用户指南》**中的[使用 Amazon S3 对象](https://docs.aws.amazon.com//AmazonS3/latest/userguide/UsingObjects.html)
+ 《Amazon S3 用户指南》**中的[使用前缀和分隔符按层次结构列出密钥](https://docs.aws.amazon.com//AmazonS3/latest/userguide/ListingKeysHierarchy.html)
+ 《Amazon S3 用户指南》**中的[使用 适用于 .NET 的 AWS SDK（低级别）中止到 S3 存储桶的分段上传](https://docs.aws.amazon.com//AmazonS3/latest/userguide/LLAbortMPUnet.html)

# 在 AWS CLI 中使用 API 级 (s3api) 命令
<a name="cli-services-s3-apicommands"></a>

API 级命令（包含在 `s3api` 命令集中）提供对 Amazon Simple Storage Service (Amazon S3) API 的直接访问，并且可以执行高级别 `s3` 命令中未公开的某些操作。这些命令等同于对服务功能提供 API 级访问的其他 AWS 服务的命令。有关 `s3` 命令的更多信息，请参阅 [在 AWS CLI 中使用高级（s3）命令](cli-services-s3-commands.md)。

本主题提供了若干示例，以演示如何使用映射到 Amazon S3 API 的低级别命令。此外，您可以在[《AWS CLI 版本 2 参考指南》](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html)的 `s3api` 部分中找到每个 S3 API 命令的示例。

**Topics**
+ [先决条件](#cli-services-s3-apicommands-prereqs)
+ [应用自定义 ACL](#cli-services-s3-apicommands-acls)
+ [配置日志记录策略](#cli-services-s3-apicommands-logpol)
+ [资源](#cli-services-s3-apicommands-resources)

## 先决条件
<a name="cli-services-s3-apicommands-prereqs"></a>

要运行 `s3api` 命令，您需要：
+ 安装和配置 AWS CLI。有关更多信息，请参阅 [安装或更新最新版本的 AWS CLI](getting-started-install.md) 和 [AWS CLI 身份验证和访问凭证](cli-chap-authentication.md)。
+ 您使用的配置文件必须具有允许示例代码执行AWS操作的权限。
+ 需了解如下 Amazon S3 术语：
  + **存储桶** – 顶级 Amazon S3 文件夹。
  + **前缀 ** – 存储桶中的 Amazon S3 文件夹。
  + **对象 ** – 托管在 Amazon S3 存储桶中的任何项。

## 应用自定义 ACL
<a name="cli-services-s3-apicommands-acls"></a>

对于高级别命令，您可以使用 `--acl` 选项对 Amazon S3 对象应用预定义的访问控制列表 (ACL)。但不能使用该命令设置存储桶范围的 ACL。不过，您可以通过使用 ```[put-bucket-acl](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-acl.html)` API 级命令来执行此操作。

下面的示例说明如何向两个 AWS 用户（*user1@example.com* 和 *user2@example.com*）授予完全控制权限，并向所有人授予读取权限。“everyone”的标识符来自作为参数传递的特殊 URI。

```
$ aws s3api put-bucket-acl --bucket amzn-s3-demo-bucket --grant-full-control 'emailaddress="user1@example.com",emailaddress="user2@example.com"' --grant-read 'uri="http://acs.amazonaws.com/groups/global/AllUsers"'
```

有关如何构建 ACL 的详细信息，请参阅 * Amazon Simple Storage Service API 参考*中的 [PUT Bucket acl](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTacl.html)。CLI 中的 `s3api` ACL 命令（如 `put-bucket-acl`）使用相同的 [简化参数表示法](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-shorthand.html)。

## 配置日志记录策略
<a name="cli-services-s3-apicommands-logpol"></a>

API 命令 `put-bucket-logging` 配置存储桶日志记录策略。

在下面的示例中，已向AWS用户 *user@example.com* 授予对日志文件的完全控制权限，而向所有用户授予了读取访问权限。请注意，还需要使用 `put-bucket-acl` 命令向 Amazon S3 的日志传输系统（由 URI 指定）授予必要的权限，以读取和向存储桶写入日志。

```
$ aws s3api put-bucket-acl --bucket amzn-s3-demo-bucket --grant-read-acp 'URI="http://acs.amazonaws.com/groups/s3/LogDelivery"' --grant-write 'URI="http://acs.amazonaws.com/groups/s3/LogDelivery"'
$ aws s3api put-bucket-logging --bucket amzn-s3-demo-bucket --bucket-logging-status file://logging.json
```

上一个命令中的 `logging.json` 文件具有以下内容。

```
{
  "LoggingEnabled": {
    "TargetBucket": "amzn-s3-demo-bucket",
    "TargetPrefix": "amzn-s3-demo-bucketLogs/",
    "TargetGrants": [
      {
        "Grantee": {
          "Type": "AmazonCustomerByEmail",
          "EmailAddress": "user@example.com"
        },
        "Permission": "FULL_CONTROL"
      },
      {
        "Grantee": {
          "Type": "Group",
          "URI": "http://acs.amazonaws.com/groups/global/AllUsers"
        },
        "Permission": "READ"
      }
    ]
  }
}
```

## 资源
<a name="cli-services-s3-apicommands-resources"></a>

《AWS CLI 参考：》****
+ [https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-acl.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-acl.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-logging.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-logging.html)

《服务参考：》****
+ 《Amazon S3 开发人员指南》**中的[使用 Amazon S3 存储桶](https://docs.aws.amazon.com//AmazonS3/latest/userguide/UsingBucket.html)
+ 《Amazon S3 用户指南》**中的[使用 Amazon S3 对象](https://docs.aws.amazon.com//AmazonS3/latest/userguide/UsingObjects.html)
+ 《Amazon S3 用户指南》**中的[使用前缀和分隔符按层次结构列出密钥](https://docs.aws.amazon.com//AmazonS3/latest/userguide/ListingKeysHierarchy.html)
+ 《Amazon S3 用户指南》**中的[使用 适用于 .NET 的 AWS SDK（低级别）中止到 S3 存储桶的分段上传](https://docs.aws.amazon.com//AmazonS3/latest/userguide/LLAbortMPUnet.html)

# AWS CLI 中的 Amazon S3 存储桶生命周期脚本示例
<a name="cli-services-s3-lifecycle-example"></a>

本主题介绍使用 AWS Command Line Interface (AWS CLI) 的 Amazon S3 存储桶生命周期操作的 bash 脚本示例。此脚本示例使用 [https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) 命令集。Shell 脚本是专用于在命令行界面中运行的程序。

**Topics**
+ [在您开始之前](#cli-services-s3-lifecycle-example-before)
+ [关于此示例](#cli-services-s3-lifecycle-example-about)
+ [文件](#cli-services-s3-lifecycle-example-files)
+ [引用](#cli-services-s3-lifecycle-example-references)

## 在您开始之前
<a name="cli-services-s3-lifecycle-example-before"></a>

您需要先满足以下条件，才能运行下文中的任何示例代码。
+ 安装和配置 AWS CLI。有关更多信息，请参阅 [安装或更新最新版本的 AWS CLI](getting-started-install.md) 和 [AWS CLI 身份验证和访问凭证](cli-chap-authentication.md)。
+ 您使用的配置文件必须具有允许示例代码执行AWS操作的权限。
+ 作为AWS的最佳实践，请授予此代码最低的权限，或者仅授予它执行任务所需的权限。有关更多信息，请参阅 *IAM 用户指南* 中的 [授予最低权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege)。
+ 此代码尚未在所有AWS区域中进行测试。有些 AWS 服务仅在特定区域中提供。有关更多信息，请参阅《AWS 一般参考指南》**中的[服务端点和配额](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html)。
+ 运行此代码可能会导致您的 AWS 账户产生相关费用。您有责任确保在使用完由此脚本创建的任何资源后删除这些资源。

Amazon S3 服务使用以下术语：
+ 存储桶 – 顶级 Amazon S3 文件夹。
+ 前缀 – 存储桶中的 Amazon S3 文件夹。
+ 对象 – Amazon S3 存储桶中托管的任何项。

## 关于此示例
<a name="cli-services-s3-lifecycle-example-about"></a>

此示例说明如何使用 shell 脚本文件中的一组函数与一些基本的 Amazon S3 操作进行交互。这些函数包含在名为 `bucket-operations.sh` 的 shell 脚本文件中。您可以在另一个文件中调用这些函数。每个脚本文件都包含了介绍每个函数的注释。

要查看每个步骤的中间结果，请使用 `-i` 参数运行脚本。您可以使用 Amazon S3 控制台查看存储桶或其内容的当前状态。仅当您在系统提示符处按 **Enter** 后，脚本才会继续执行下一步。

有关完整示例和可下载的脚本文件，请参阅 *GitHub* 上的 *AWS 代码示例存储库* 中的 [Amazon S3 存储桶生命周期操作](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/aws-cli/bash-linux/s3/bucket-lifecycle-operations)。

## 文件
<a name="cli-services-s3-lifecycle-example-files"></a>

此示例包含以下文件：

**bucket-operations.sh**  
此主脚本文件可以从另一个文件中调取。它包含了执行以下任务的函数：  
+ 创建存储桶并验证它是否存在
+ 将文件从本地电脑复制到存储桶
+ 将文件从一个存储桶位置复制到另一个存储桶位置
+ 列出存储桶中的内容
+ 从存储桶中删除文件
+ 删除存储桶
在 *GitHub* 上查看 `[bucket-operations.sh](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/aws-cli/bash-linux/s3/bucket-lifecycle-operations/bucket_operations.sh)` 的代码。

**test-bucket-operations.sh**  
shell 脚本文件 `test-bucket-operations.sh` 演示了如何调用这些函数，即调取 `bucket-operations.sh` 文件然后调用其中的每个函数。调用函数后，该测试脚本会删除它创建的所有资源。  
在 *GitHub* 上查看 `[test-bucket-operations.sh](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/aws-cli/bash-linux/s3/bucket-lifecycle-operations/test_bucket_operations.sh)` 的代码。

**awsdocs-general.sh**  
脚本文件 `awsdocs-general.sh` 中包含了在 AWS CLI 的高级代码示例中使用的通用函数。  
在 *GitHub* 上查看 `[awsdocs-general.sh](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/aws-cli/bash-linux/s3/bucket-lifecycle-operations/awsdocs_general.sh)` 的代码。

## 引用
<a name="cli-services-s3-lifecycle-example-references"></a>

**AWS CLI 参考：**
+ [https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3api/create-bucket.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/create-bucket.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-bucket.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-bucket.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3api/head-bucket.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/head-bucket.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3api/list-objects.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-objects.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html)

**其他参考资料：**
+ 《Amazon S3 开发人员指南》**中的[使用 Amazon S3 存储桶](https://docs.aws.amazon.com//AmazonS3/latest/userguide/UsingBucket.html)
+ 《Amazon S3 用户指南》**中的[使用 Amazon S3 对象](https://docs.aws.amazon.com//AmazonS3/latest/userguide/UsingObjects.html)
+ 要查看和贡献 AWS 开发工具包和 AWS CLI 代码示例，请参阅 *GitHub* 上的 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/)。