# 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 使用](/ee-ai-cn/ai-3.3/reference/s3-api-usage.md)。 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.alluxio.io/ee-ai-cn/ai-3.3/api/s3-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.