# S3 API Alluxio 支持与 Amazon\[S3 API ()] 基本操作兼容的 RESTful API。 Alluxio S3 API 应用于与类似 S3 的存储交互的应用程序使用，并且可以从 Alluxio 提供的其他功能中受益，例如数据缓存、 与基于文件系统的应用程序共享数据以及存储系统抽象化（如使用 Ceph 代替 S3 作为后端存储）。 例如，一个下载分析任务生成报告的简单应用就可以使用 S3 API，而非更复杂的文件系统 API。 ## 先决条件 要在 worker 进程中使用提供的 S3 API，您需要修改 `conf/alluxio-site.properties` 文件，使其包含以下内容： ```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 不支持 [存储桶虚拟主机](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html)。 因此，S3 client 必须使用[路径式请求](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#path-style-access) (即：`http://s3.amazonaws.com/{bucket}/{object}`) ，而非 `http://{bucket}.s3.amazonaws.com/{object}`。 ### S3 写入隐式覆盖 正如 AWS S3 的[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) 文档中所述： > *Amazon S3 是一个分布式系统。如果同时收到多个针对同一对象的写入请求，除了最后写入的对象外，其他对象都会被覆盖。* *Amazon S3 不提供对象锁定功能；如需要，请确保在应用层中内置锁定功能或使用版本控制功能。* * 请注意，Alluxio S3 API 目前不支持对象版本控制。 Alluxio S3 将覆盖现有键和临时目录以进行多部分上传。 ### ListObjects(V2) 中的文件夹 在 Alluxio 中，所有子目录在调用 ListObjects(V2) 方法时会以 0 字节文件夹的形式返回。 这种行为类似于在 AWS S3 console 上为每个对象创建所有父文件夹的操作。 ### 标签和元数据限制 要支持 S3 API 中的标签功能，需修改 `conf/alluxio-site.properties` 以包含以下内容： ```properties alluxio.underfs.xattr.change.enabled=true ``` 用户定义的存储桶和对象标签数量限制为10，且遵守[S3 标签限制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-tagging.html)。 * 设置属性键 `alluxio.proxy.s3.tagging.restrictions.enabled=false` 来禁用此行为。 根据[S3 对象元数据限制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)，在 PUT 请求中，用户定义的元数据最大大小默认为2KB。 * 设置属性键 `alluxio.proxy.s3.header.metadata.max.size` 来修改此行为。 ### 性能 S3 API由于它采用了重定向机制和数据零拷贝，因此只有支持 HTTP 重定向的 client 才能访问它。 ## 全局请求标头 | 标头 | 内容 | 描述 | | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Authorization](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-auth-using-authorization-header.html) | 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 操作](https://docs.aws.amazon.com/AmazonS3/latest/API/API_Operations.html) 的支持情况： | S3 API 操作 | 支持的标头 | 支持的查询参数 | | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html) | | N/A | | [CreateBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html) | N/A | N/A | | [DeleteBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html) | N/A | N/A | | [DeleteBucketTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketTagging.html) | N/A | N/A | | [DeleteObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html) | N/A | N/A | | [DeleteObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) | N/A | N/A | | [DeleteObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjectTagging.html) | N/A | N/A | | [GetBucketTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketTagging.html) | N/A | N/A | | [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) | Range | N/A | | [GetObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectTagging.html) | N/A | N/A | | [HeadBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html) | N/A | N/A | | [HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) | N/A | N/A | | [ListBuckets](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html) | N/A | N/A | | [ListObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html) | N/A | delimiter, encoding-type, marker, max-keys, prefix | | [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) | N/A | continuation-token, delimiter, encoding-type, max-keys, prefix, start-after | | [PutBucketTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketTagging.html) | N/A | N/A | | [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) | | N/A | | [PutObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectTagging.html) | N/A | N/A | ## 使用示例 请参考 [S3 API 使用](https://documentation.alluxio.io/ee-ai-cn/ai-3.3/reference/s3-api-usage)。