# 通过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` 文件，使其包含以下内容： ```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` 来修改此行为。 ### HTTP 长连接 HTTP 长连接（也称为HTTP Keep-Alive），是一个使用单个tcp连接来发送和接收多个http请求/响应，而不是每次请求/响应对应一个新连接的想法。 长连接的主要优点包括： * **减少延迟**：减少了因频繁请求导致的延迟。 * **节省资源**：通过减少连接数和重复请求，降低了服务器和客户端的资源消耗。 * **实时性**：能够迅速传递最新数据。 然而，长连接也有一些缺点，例如： * **服务器压力大**：大量保持打开的连接会增加服务器的内存和CPU负担。 * **超时问题**：需要处理长期无响应的情况，确保连接超时机制的有效性。 总的来说，HTTP 长连接是一种有效的技术，适用于对实时性要求较高但同时希望节省资源的场景。 要启用 S3 API 的 HTTP 长连接保持，您需要修改 `conf/alluxio-site.properties` 文件，使其包含以下内容： ```properties alluxio.worker.s3.connection.keep.alive.enabled=true # 当连接空闲时间超过这项配置，连接将被关闭。0 表示关闭此功能。 alluxio.worker.s3.connection.idle.max.time=0sec ``` ### 性能 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 操作 | 支持的标头 | 支持的查询参数 | | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | [AbortMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html) | N/A | N/A | | [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) | N/A | N/A | | [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html) | | N/A | | [CreateMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.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 | | [ListMultipartUploads](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.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 | | [ListParts](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html) | N/A | N/A | | [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 | | [UploadPart](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html) | | N/A | ## 使用示例 请参考 [S3 API 使用](https://documentation.alluxio.io/ee-ai-cn/ai-3.6/reference/s3-api-usage)。