AWS S3 兼容

为了使众多基于 AWS S3 开发的应用程序、SDK、及第三方服务在不修改代码的前提下,更容易的接入到 QingStor,QingStor 兼容了 AWS S3 的接口。

由于 QingStor 和 AWS S3 所提供的功能有部分差异,且两者所依托的基础架构和账号体系也不尽相同,所以并没有做到完全兼容 AWS S3接口。但重要的功能已都兼容。每个接口的兼容程度将在下文列出。

AWS S3 兼容接口的设计目标,是为了尽可能的方便那些曾基于 AWS S3 而开发的遗产应用接入到 QingStor。如果你的应用刚刚着手开发,或者比较容易修改,强烈建议你基于 QingStor 的原生接口进行开发,因为原生接口更加简洁易用,且能在第一时间体验到 QingStor 最新、最完整的功能。

注解

更多 AWS S3 接口使用指南可查阅 AWS 官方文档

注解

AWS S3 兼容接口暂不支持自定义域名访问。

访问方式

和 QingStor 原生接口一样,AWS S3 兼容接口也支持两种形式的访问地址。

Style URL Format Example
Path s3.<zone>.qingstor.com/<bucket>/<object> https://s3.pek3a.qingstor.com/mybucket/mykey
Virtual-host <bucket>.s3.<zone>.qingstor.com/<object> https://mybucket.s3.pek3a.qingstor.com/mykey

这里的”访问地址”在 AWS S3 语境里被称为 Endpoint。 当你的请求地址定为以上任何一种风格时,你将开始使用 AWS S3 接口访问 QingStor 服务。

注解

除了请求 Host 不同,所有请求头、请求正文、签名方式都应该符合 AWS S3 的规范。你的应用看到的仿佛是 AWS S3 服务,但实际上操作的是 QingStor

使用示例

大多数基于 AWS S3 开发的工具都有自定义访问地址的方法,下面以一些常用工具为例,说明如何对接 QingStor

AWS SDK for Python

  1. 安装 Boto 类库:

    $ pip install boto
    
  2. 编写程序:

    $ cat boto-to-qingstor.py
    import boto
    conn = boto.connect_s3(
        aws_access_key_id='PLLZOBTTZXGBNOWUFHZZ',
        aws_secret_access_key='MnIjI58zC8AX07xotHXcm6grwFgOXhaJQHkTCX2X',
        host='s3.pek3a.qingstor.com'
    )
    bucket = conn.get_bucket('mybucket')
    key = bucket.get_key("mykey")
    

AWS CLI

  1. 安装 AWS CLI 工具:

    pip install awscli
    
  2. 编辑配置文件:

    $ cat ~/.aws/config
    [profile qingstor]
    region = pek3a
    output = json
    s3 =
        signature_version = s3v4
    
  3. 设置访问密钥:

    $ cat ~/.aws/credentials
    [qingstor]
    aws_access_key_id = PLLZOBTTZXGBNOWUFHZZ
    aws_secret_access_key = MnIjI58zC8AX07xotHXcm6grwFgOXhaJQHkTCX2X
    
  4. 命令行执行:

    $ aws s3api put-object --bucket mybucket --key puppy.jpg --body ~/Pictures/puppy.jpg --endpoint-url 'https://s3.pek3a.qingstor.com' --profile qingstor
    {
        "ETag": "\"c3872b49cb244269aad8cd4275a41c4a\""
    }
    

s3fs

  1. 按照文档的步骤编译并安装 s3fs:

    https://github.com/s3fs-fuse/s3fs-fuse/blob/master/README.md
    
  2. 设置访问密钥(注意需要设置密钥文件的权限为 600):

    # cat <<EOF > /root/.s3fs/credentials
    PLLZOBTTZXGBNOWUFHZZ:MnIjI58zC8AX07xotHXcm6grwFgOXhaJQHkTCX2X
    EOF
    
    # chmod 600 /root/.s3fs/credentials
    
    注:假定 ACCESS_KEY_ID 为 PLLZOBTTZXGBNOWUFHZZ, ACCESS_KEY_SECRET 为

    MnIjI58zC8AX07xotHXcm6grwFgOXhaJQHkTCX2X

  3. 挂载 bucket 到本地目录:

    # mkdir -p /mnt/mybucket
    
    # s3fs mybucket /mnt/mybucket -o passwd_file=/root/.s3fs/credentials -o url=http://s3.pek3a.qingstor.com
    
    # df -T | grep s3fs
    s3fs           fuse.s3fs 274877906944        0 274877906944   0% /mnt/mybucket
    
  4. 测试文件系统操作:

    # echo 'hello world' > /tmp/hello.txt
    
    # cp -v /tmp/hello.txt /mnt/mybucket/
    ‘/tmp/hello.txt’ -> ‘/mnt/mybucket/hello.txt’
    
    # ls -l /mnt/mybucket/hello.txt
    ---------- 1 root root 4635 Aug 11 23:26 /mnt/mybucket/hello.txt
    
    # cat /mnt/mybucket/hello.txt
    hello world
    

兼容签名验证

AWS S3 兼容接口同时支持签名方法 AWS Signature Version 2 和 AWS Signature Version 4。 AWS Signature V2 签名方法请查阅 Signing and Authenticating REST Requests, AWS Signature V4 签名方法请查阅 Authenticating Requests (AWS Signature Version 4)

注解

在签名过程中,使用 QingCloud 密钥对 (QingCloud Access Key) 代替 AWS 密钥对 (AWS Access Key)。Signature V4 版本中,使用 QingCloud Zone 代替 AWS Region

兼容接口

Service API

AWS S3 接口 请求兼容描述 响应兼容描述
GET Service 兼容 兼容

注解

更多请参考 AWS S3 文档 Service API

Bucket API

AWS S3 接口 请求兼容描述 响应兼容描述
GET Bucket 未支持请求参数 encoding-type 当响应体中的 NextMarker 元素属于 common prefix 时,与 S3 接口返回不同,但使用此 NextMarker 作为下次请求的 marker 参数可以得到正确的结果
PUT Bucket 未支持请求头 x-amz-acl, x-amz-grant-* 兼容
DELETE Bucket 兼容 兼容
HEAD Bucket 兼容 兼容
GET Bucket acl 兼容 兼容
PUT Bucket ACL 未支持请求头 x-amz-grant-read-acp, x-amz-grant-write-acp;请求头 x-amz-acl 未支持设置 authenticated-read;请求体 CanonicalUser 未支持 type AmazonCustomerByEmail,且未支持 Authenticated Users group 和 Log Delivery group 兼容

注解

更多请参考 AWS S3 文档 Bucket API

Object API

AWS S3 接口 请求兼容描述 响应兼容描述
PUT Object 未支持请求头 Cache-Control, Content-Disposition, Content-Encoding, Expires, x-amz-meta-, x-amz-storage-class, x-amz-website​-redirect-location, x-amz-acl, x-amz-grant-, x-amz-server-side​-encryption-* 兼容
PUT Object - Copy 兼容 兼容
GET Object 兼容 兼容
DELETE Object 未支持请求头 x-amz-mfa 兼容
DELETE Multiple Objects 未支持请求头 x-amz-mfa 兼容
HEAD Object 未支持请求头 x-amz-server-side​-encryption​-customer-* 兼容
Initiate Multipart Upload 未支持请求头 Cache-Control, Content-​Disposition, Content-Encoding, Expires, x-amz-meta-, x-amz-storage-​class, x-amz-website​-redirect-location, x-amz-acl, x-amz-grant-, x-amz-server-side​-encryption-* 兼容
Upload Part 未支持 x-amz-server-side​-encryption​-customer-* 兼容
List Parts 未支持请求参数 encoding-type, 兼容
Complete Multipart Upload 兼容 兼容
Abort Multipart Upload 兼容 兼容

注解

更多请参考 AWS S3 文档 Object API

警告

所有请求参数的默认值,将与原生接口保持一致,而非遵守 AWS S3 接口的规定

兼容公共头

公共请求头

AWS S3 请求头 兼容描述
Authorization 兼容
Content-Length 兼容
Content-Type 兼容
Content-MD5 兼容
Date 兼容
Expect 兼容
Host 兼容
x-amz-content-sha256 未兼容,但可以用于 signature v4 签名
x-amz-date 兼容
x-amz-security-token 未兼容

注解

更多请参考 AWS S3 文档 Common Request Headers

公共响应头

AWS S3 响应头 兼容描述
Content-Length 兼容
Content-Type 兼容
Connection 兼容
Date 兼容
ETag 兼容
Server 将设置为 QingStor
x-amz-delete-marker 未兼容
x-amz-id-2 将设置与响应头 x-amz-request-id 相同
x-amz-request-id 将设置与原生响应头 X-QS-Request-ID 相同
x-amz-version-id 未兼容

注解

更多请参考 AWS S3 文档 Common Response Headers

兼容工具

理论上所有基于 AWS S3 API 开发的客户端,只要涉及的接口实现了兼容,都可以直接对接 QingStor。

实际测试中,我们已经证实可以兼容的工具包括:

AWS SDK for Python / PHP / Java / Ruby
AWS Command Line Interface (CLI)
s3fs
Hadoop s3a / distcp
ownCloud external storage
Transmit for iOS / macOS
Commvault
CloudBerry Drive
Synology DSM