S3 API

Alluxio 支持与 Amazon[S3 API (http://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html)] 基本操作兼容的 RESTful API。

Alluxio S3 API 应用于与类似 S3 的存储交互的应用程序使用，并且可以从 Alluxio 提供的其他功能中受益，例如数据缓存、 与基于文件系统的应用程序共享数据以及存储系统抽象化（如使用 Ceph 代替 S3 作为后端存储）。 例如，一个下载分析任务生成报告的简单应用就可以使用 S3 API，而非更复杂的文件系统 API。

先决条件

要在 worker 进程中使用提供的 S3 API，您需要修改 conf/alluxio-site.properties 文件，使其包含以下内容：

alluxio.worker.s3.api.enabled=true

我们建议设置一个负载均衡器（load balancer），以便将API调用在所有 worker 节点之间分摊。 您可以考虑使用不同的负载均衡解决方案，如 DNS、Nginx 或 LVS。

限制和免责声明

Alluxio 文件系统限制

S3 API 只将最顶层的 Alluxio 目录视为存储桶。 因此，Alluxio 文件系统的根目录不会被视为 S3 存储桶。 任何根级对象（例如：alluxio://file）都将无法通过 Alluxio S3 API 访问。

Alluxio 使用 / 作为保留的分隔符。 因此，任何包含名为/ 的对象或文件夹的 S3 路径（例如 s3://example-bucket//）将导致未定义的行为。

另外，请注意，Alluxio 文件系统无法处理以下特殊字符和模式：

• 问号 ('?')

• 带有句号的格式 (./ and ../)

• 反斜杠 ('\')

不支持存储桶虚拟主机

Alluxio S3 API 不支持 存储桶虚拟主机。 因此，S3 client 必须使用路径式请求 (即：http://s3.amazonaws.com/{bucket}/{object}) ，而非 http://{bucket}.s3.amazonaws.com/{object}。

S3 写入隐式覆盖

正如 AWS S3 的PutObject 文档中所述：

Amazon S3 是一个分布式系统。如果同时收到多个针对同一对象的写入请求，除了最后写入的对象外，其他对象都会被覆盖。 Amazon S3 不提供对象锁定功能；如需要，请确保在应用层中内置锁定功能或使用版本控制功能。

• 请注意，Alluxio S3 API 目前不支持对象版本控制。

Alluxio S3 将覆盖现有键和临时目录以进行多部分上传。

ListObjects(V2) 中的文件夹

在 Alluxio 中，所有子目录在调用 ListObjects(V2) 方法时会以 0 字节文件夹的形式返回。 这种行为类似于在 AWS S3 console 上为每个对象创建所有父文件夹的操作。

标签和元数据限制

要支持 S3 API 中的标签功能，需修改 conf/alluxio-site.properties 以包含以下内容：

alluxio.underfs.xattr.change.enabled=true

用户定义的存储桶和对象标签数量限制为10，且遵守S3 标签限制。

• 设置属性键 alluxio.proxy.s3.tagging.restrictions.enabled=false 来禁用此行为。

根据S3 对象元数据限制，在 PUT 请求中，用户定义的元数据最大大小默认为2KB。

• 设置属性键 alluxio.proxy.s3.header.metadata.max.size 来修改此行为。

性能

S3 API由于它采用了重定向机制和数据零拷贝，因此只有支持 HTTP 重定向的 client 才能访问它。

全局请求标头

标头	内容	描述
Authorization	AWS4-HMAC-SHA256 Credential={user}/..., SignedHeaders=..., Signature=...	目前 Alluxio S3 API 不支持access key和secret key 唯一支持的身份验证方式是 SIMPLE 身份验证类型。 默认情况下，执行任何操作的用户即是启动 Alluxio 进程时使用的用户。 因此，此标头仅用于指定执行操作的 Alluxio ACL 用户名。 为了与其他 S3 client 保持兼容性，该标头仍应遵循 AWS Signature Version 4 的格式。 当向 S3 client 提供访问密钥时，请输入要使用的 Alluxio ACL 用户名。 私钥未使用，因此您可以使用任何虚拟值。

支持的 S3 API 操作

下表描述了当前 S3 API 操作 的支持情况：

S3 API 操作	支持的标头	支持的查询参数
CopyObject	Content-Type, x-amz-copy-source, x-amz-metadata-directive, x-amz-tagging-directive, x-amz-tagging	N/A
CreateBucket	N/A	N/A
DeleteBucket	N/A	N/A
DeleteBucketTagging	N/A	N/A
DeleteObject	N/A	N/A
DeleteObjects	N/A	N/A
DeleteObjectTagging	N/A	N/A
GetBucketTagging	N/A	N/A
GetObject	Range	N/A
GetObjectTagging	N/A	N/A
HeadBucket	N/A	N/A
HeadObject	N/A	N/A
ListBuckets	N/A	N/A
ListObjects	N/A	delimiter, encoding-type, marker, max-keys, prefix
ListObjectsV2	N/A	continuation-token, delimiter, encoding-type, max-keys, prefix, start-after
PutBucketTagging	N/A	N/A
PutObject	Content-Length, Content-MD5, Content-Type, x-amz-tagging	N/A
PutObjectTagging	N/A	N/A

使用示例

请参考 S3 API 使用。