OSS兼容的S3 API（含S3 Vectors）及与S3的差异有哪些

通用Bucket兼容的S3 API

通用Bucket对S3 Bucket、Object以及Multipart操作兼容的API如下：

通用Bucket与S3的差异

通用Bucket与S3的差异如下：

• 请求风格

  S3支持路径（Path）请求风格和虚拟托管（Virtual Hosted）请求风格。路径风格将Bucket名称放在URL路径中，而虚拟托管风格将Bucket名称作为子域名。基于安全考虑，OSS仅支持虚拟托管访问方式，即Bucket名称必须作为子域名使用。因此，在S3迁移至OSS后，客户端应用和S3工具都需要进行相应设置，确保所有请求采用虚拟托管风格，否则可能导致OSS报错，并禁止访问。

• ACL权限定义

  OSS对ACL权限的定义与S3不完全一致，二者的主要区别如下：

  级别	权限	S3	OSS
  Bucket	READ	拥有Bucket的list权限。	对于Bucket下的所有Object，如果某Object没有设置Object权限，则该Object可读。
  	WRITE	Bucket下的Object可写入或覆盖。	对于Bucket下不存在的Object，可写入。 对于Bucket下存在的Object，如果该Object没有设置Object权限，则该Object可被覆盖。 可以初始化分片上传（InitiateMultipartUpload）。
  	READ_ACP	读取Bucket ACL	读取Bucket ACL，仅Bucket owner和授权子账号拥有此权限。
  	WRITE_ACP	设置Bucket ACL。	设置Bucket ACL，仅Bucket owner和授权子账号拥有此权限。
  Object	READ	Object可读。	Object可读。
  	WRITE	N/A	Object可以被覆盖。
  	READ_ACP	读取Object ACL。	读取Object ACL，仅Bucket owner和授权RAM用户拥有此权限。
  	WRITE_ACP	设置Object ACL。	设置Object ACL，仅Bucket owner和授权RAM用户拥有此权限。

  重要

  OSS仅支持S3中的私有、公共读和公共读写三种ACL模式。

• 存储类型

  OSS与Amazon S3的存储类型并非一一对应。OSS共有5种存储类型，S3共有7种主要类型，且在最低存储时长、读取方式等能力上存在差异。您可根据需要转换OSS Object的存储类型。主要对应关系及差异如下：

  OSS存储类型	对应的S3存储类型	关键差异
  标准存储（Standard）	STANDARD	最低存储时长：OSS与S3均无要求。 读取方式：两者均为实时读取。
  低频访问存储（Infrequent Access）	STANDARD_IA ONEZONE_IA	对应关系：OSS同城冗余IA对应STANDARD_IA，本地冗余IA对应ONEZONE_IA。 最低存储时长：均为30天。 读取方式：两者均为实时读取，有取回费。
  归档存储（Archive）	GLACIER_IR GLACIER（Flexible）	最低存储时长：OSS为60天，S3为90天。 读取方式：OSS需解冻（约1分钟），或开启归档直读实现实时访问；S3 GLACIER_IR为毫秒级实时读取，GLACIER（Flexible）需Restore（Expedited 1~5分钟、Standard 3~5小时、Bulk 5~12小时）。
  冷归档存储（Cold Archive）	DEEP_ARCHIVE	最低存储时长：均为180天。 读取方式：双方均需解冻。OSS解冻高优先约1小时、标准2~5小时、批量5~12小时；S3 仅 GLACIER（Flexible）类型达到该解冻时长，DEEP_ARCHIVE为Standard ≤12小时（Batch 9~12小时）、Bulk ≤48小时。
  深度冷归档存储（Deep Cold Archive）	无对应档	OSS提供的极深冷存储类型，AWS没有比DEEP_ARCHIVE更冷的存储类型（S3无对应档）。 最低存储时长：OSS为180天（S3无对应档）。 读取方式：OSS需解冻，高优先约12小时、标准约48小时（S3 仅 DEEP_ARCHIVE 类型达到该解冻时长）。

  说明

  此外，S3提供独立的INTELLIGENT_TIERING（智能分层）存储类型，可根据访问频率在多个访问层之间自动转换；OSS没有独立的智能分层存储类型，需通过生命周期规则实现类似的自动转储。

  如果未开启归档直读，归档存储类型的Object在读取之前，需先使用Restore请求进行解冻。与S3不同，OSS会忽略S3 API的解冻天数设置，解冻状态默认持续1天，用户可延长到最多7天，之后Object复归初始的冷冻状态。

• ETag

  • 对于PUT方式上传的Object，OSS Object的ETag与Amazon S3在大小写上有区别。OSS为大写，而S3为小写。如果客户端有关于ETag的校验，请忽略大小写。

  • 对于分片上传的Object，OSS的ETag计算方式与S3不同。

向量Bucket兼容的S3 Vectors API

OSS Vectors的向量Bucket兼容Amazon S3 Vectors协议。您无需改写业务代码，只需将AWS SDK中S3 Vectors客户端的Endpoint指向向量Bucket的访问域名，即可完成向量Bucket、向量索引和向量数据的管理与检索。关于OSS Vectors的功能说明，请参见OSS Vectors 概述；关于OSS Vectors原生API，请参见关于 OSS Vectors 操作。

使用AWS SDK访问向量Bucket时，按以下方式配置客户端：

• 服务名（service name）：s3vectors。签名算法为AWS Signature Version 4，由SDK自动完成，无需额外配置。

• 公网访问域名：https://$bucketname-$uid.$regionID.oss-vectors.aliyuncs.com

• 内网访问域名：https://$bucketname-$uid.$regionID-internal.oss-vectors.aliyuncs.com

• 地域（region）：向量Bucket所在地域的ID，例如cn-hangzhou。

向量Bucket兼容的S3 Vectors API及其对应的OSS Vectors API如下：

以下S3 Vectors API暂不支持，调用时返回405 MethodNotAllowed：UpdateIndexMode、PutVectorBucketDefaultIndexMode、TagResource、UntagResource、ListTagsForResource。

以下示例展示如何使用Python（Boto3）通过S3 Vectors接口创建向量索引、写入向量数据并执行向量检索。使用前请先安装包含S3 Vectors客户端的Boto3版本（pip install -U boto3），并将AccessKey配置到环境变量中。

import os
import boto3

# 向量Bucket的访问域名，格式为https://$bucketname-$uid.$regionID.oss-vectors.aliyuncs.com
client = boto3.client(
    "s3vectors",
    region_name="cn-hangzhou",
    endpoint_url="https://examplebucket-123***456.cn-hangzhou.oss-vectors.aliyuncs.com",
    aws_access_key_id=os.environ.get("OSS_ACCESS_KEY_ID"),
    aws_secret_access_key=os.environ.get("OSS_ACCESS_KEY_SECRET"),
)

# 创建向量索引。索引名称只允许字母和数字，且必须以字母开头
client.create_index(
    vectorBucketName="examplebucket",
    indexName="exampleindex",
    dataType="float32",
    dimension=4,
    distanceMetric="cosine",
)

# 写入向量数据
client.put_vectors(
    vectorBucketName="examplebucket",
    indexName="exampleindex",
    vectors=[
        {
            "key": "key1",
            "data": {"float32": [0.1, 0.2, 0.3, 0.4]},
            "metadata": {"genre": "doc"},
        }
    ],
)

# 检索向量数据
response = client.query_vectors(
    vectorBucketName="examplebucket",
    indexName="exampleindex",
    queryVector={"float32": [0.1, 0.2, 0.3, 0.4]},
    topK=3,
    returnDistance=True,
    returnMetadata=True,
)
print(response["vectors"])

向量Bucket与S3 Vectors的差异

从S3 Vectors切换到OSS Vectors时，请注意以下差异：

• 资源定位方式

  S3 Vectors使用固定的服务域名，向量Bucket通过请求体中的vectorBucketName或vectorBucketArn指定。OSS Vectors从三级域名中解析向量Bucket，并会校验请求体与域名的一致性：如果请求体中的vectorBucketName或vectorBucketArn与域名中的向量Bucket不一致，则返回400 ValidationException。

• ARN格式

  OSS Vectors沿用阿里云资源标识格式，向量Bucket的ARN为acs:ossvector:$regionID:$uid:$bucketname，向量索引的ARN为acs:ossvector:$regionID:$uid:$bucketname/$indexname，不支持arn:aws:s3vectors:*格式。请求中的ARN参数均为可选参数，建议直接使用名称（vectorBucketName、indexName）寻址资源。

• 命名规则

  向量Bucket名称长度为3~32个字符（S3 Vectors为3~63个字符），只允许小写字母、数字和短横线（-），且不能以短横线开头或结尾。向量索引名称长度为1~63个字符，只允许字母和数字，且必须以字母开头；S3 Vectors的索引名称长度为3~63个字符，允许使用小写字母、数字、短横线（-）和点（.）。因此，从S3 Vectors切换过来时，名称中包含短横线、下划线或点的向量索引需要重新命名。

• 服务端加密

  OSS Vectors暂不支持服务端加密。CreateVectorBucket和CreateIndex请求中的encryptionConfiguration参数会被解析但不生效（不报错），GetVectorBucket和GetIndex的响应中也不返回该参数。

• 资源标签

  OSS Vectors暂不支持资源标签。CreateVectorBucket请求中的tags参数会被解析但不生效，TagResource、UntagResource和ListTagsForResource接口返回405 MethodNotAllowed。

• 不支持Enhanced Mode（元数据前置过滤）

  S3 Vectors新增了ENHANCED索引模式（元数据前置过滤），并将原有模式更名为CLASSIC。OSS Vectors暂不支持该模式，相关接口和参数的表现如下：

  • UpdateIndexMode和PutVectorBucketDefaultIndexMode这两个接口不支持，调用时返回405 MethodNotAllowed。

  • QueryVectors不支持queryMode参数。该参数在S3 Vectors中为可选参数，取值为CLASSIC或ENHANCED时均返回400 ValidationException，错误消息为Unknown field: queryMode in request.。省略该参数即可正常检索。

  • ENHANCED模式专用的$startsWith过滤操作符不支持，使用时返回400 ValidationException，错误消息为Invalid filter operation: $startsWith.。

  • GetIndex响应中不返回indexMode，GetVectorBucket响应中不返回defaultIndexMode。

  如果需要元数据前置过滤或混合检索能力，可以使用OSS Vectors的Fusion Mode索引，详情请参见OSS Vectors 概述。

• S3 Vectors无对应接口的能力

  向量Bucket的访问日志转存（PutVectorBucketLogging、GetVectorBucketLogging、DeleteVectorBucketLogging）、Fusion Mode索引及其混合检索能力（PutVectorIndexFusion、QueryVectorsFusion）在S3 Vectors中没有对应接口，需要使用OSS Vectors原生API调用。通过S3 Vectors接口的CreateIndex创建的是Standard Mode索引。

• 错误响应

  S3兼容请求以JSON格式返回错误信息，并通过x-amzn-errortype响应头返回异常类型。常见异常类型如下：

  HTTP状态码	异常类型	典型原因
  400	ValidationException	请求参数不合法，例如ARN格式错误、索引名称不符合命名规则、请求体中的向量Bucket与域名不一致。
  400	SerializationException	请求体不符合规范定义或不是一个JSON请求体，例如请求体不是合法的JSON格式。错误消息为Failed to parse request.
  403	AccessDeniedException	AccessKey ID不存在、签名校验失败或没有操作权限。
  404	NotFoundException	指定的向量Bucket或向量索引不存在。
  405	MethodNotAllowed	调用了OSS Vectors暂不支持的接口，例如资源标签相关接口。
  409	ConflictException	向量Bucket或向量索引名称已存在，或删除非空的向量Bucket。