开放文件存储使用指南

 

1. 小米开放文件存储(FDS)简介

1.1 FDS综述

小米开放文件存储(File Storage Service, 简称FDS),是小米开放平台(http://dev.xiaomi.com)所提供的众多云服务之中的一种。FDS向开发者提供了简洁直观的Restful API,开发者可以直接通过标准Http协议来调用FDS的API,同时,为了方便广大开发者,FDS目前提供了Java、PHP和Android平台的SDK,开发者可以根据自己的应用需求选用合适的SDK。

1.2 FDS的优势

FDS专注于提供使用简便、可靠的文件存储服务,下面是FDS服务的一些优势:

  • 简单的数据模型:FDS采用了Bucket/Object数据模型,跟业内主流系统保持一致,方便开发者理解,降低使用门槛;
  • 直观易用的API:FDS提供了简洁的Restful API, 开发者可以通过标准Http协议直接访问;
  • 完善的认证与授权机制:FDS支持各种身份认证机制(包括签名、OAuth2.0和小米SSO认证),FDS还支持了完备的授权管理机制,最大程度的保护用户数据的安全;
  • 弹性高可用的服务质量:FDS架构上支持良好的水平扩展性,对用户提供7×24高可用的服务;
  • 灵活的应用场景: 支持的文件大小不受限制,能很好地适应更种应用场景;
  • 低廉的存储成本: 支持Reed-Solomon编码,在保证数据可靠性的前提下,能够最大程度地节约存储成本。

1.3 FDS的基本概念

  • 桶(Bucket):  Bucket是存储Object的容器,在同一个Region内,Bucket是全局唯一的。每个Object都存在于某一个Bucket中,一个Bucket里面可以包含很多个Object。
  • 对象(Object):  Object是用户实际存储在FDS中的数据,包括用户存储的文件内容和文件相关的元信息,它们合在一起,统称为Object。
  • 区域(Region): Region是物理上数据中心的划分,一个数据中心的FDS称之为一个Region。同一个Region内的Bucket在该Region内是全局唯一的。

2. 用户身份认证

2.1 签名认证

本部分介绍FDS中用到的签名认证的基本原理。

2.1.1 基本概念

使用FDS服务的签名算法,需要了解以下基本概念:

  • App Access Key: 开发者在小米开放平台申请的App Access Key, 用于标识开发者的App;
  • App Secret Key: 开发者在小米开放平台申请App Access Key时颁发的App Secret Key, 这个由用户自己保存,是用来做签名时的密钥;
  • Signature: 根据Access Key,Secret Key和用户请求计算出的数字签名,用于验证用户身份。

2.1.2 基于签名的认证过程

用户要使用签名来认证身份,通常需要按下面的步骤来进行:

  • 构建准备发往FDS的Http请求;
  • 使用App Secret Key和构建好的请求内容,计算签名;
  • 将计算好的签名和App Access Key组合起来,置于Http请求的“authorization” Header中,将请求发往FDS;
  • FDS收到请求,从”authorization” Header中解析中App Access Key和对应的签名;
  • FDS用解析出的App Access Key获取到对应的App Secret Key;
  • FDS用App Secret Key和请求内容进行签名,得到服务端签名;
  • FDS对比服务端签名和用户请求解析出来签名,如果一致刚认证通过,否则认证不通过。

注意:  App Secret Key不会在上述请求过程中传输。

2.1.3 签名算法

签名算法是签名认证的核心,以下是签名算法的详细介绍:

  • 签名在Http头中的格式:“authorization: Galaxy-V2“ + “ “ + App Access Key + “:“ + Signature ;
  • 签名计算:Signature = Base64(Hmac-Sha1(AppAccessSecret, StringToSign));
  • 签名字符串(StringToSign)的构造:
    StringToSign = HttpMethod + “\n” +
    content-md5 + “\n” +
    content-type + “\n” +
    date + “\n” +
    CanonicalizedHeaders +
    CanonicalizedResource;
  • CanonicalizedHeaders构造:

用户可以通过“x-xiaomi-“的方式,向FDS传自定义的Header,  CanonicalizedHeaders指的是规范化过之后的用户自定义的Headers,规范化的过程如下:

  1. 所有的Header都要转成全小写;
  2. 将Header按Key进行字典序排序;
  3. 将具有相关Key的Headers合并,多个值之间用”,”分隔;
  4. 将上述字符串连接起来即是CanonicalizedHeaders。
  • CanonicalizedResource构造: CannonicalizedResource是由用户请求的Uri的相对路径加上FDS预定义的SubResource(Acl等)相关的参数组成的。

2.1.4 签名库

FDS目前提供了C++/Java/PHP版本的签名库,详细的签名算法可以参见具体的签名库的实现。

3. Bucket操作REST API指南

3.1 列所有Bucket

  • 语义:
    列出当前用户所拥有的所有Buckets
  • 语法:
    GET /HTTP/1.1
    Host: files.fds.api.xiaomi.com
    Date: date
    Authorization: authorization_string
  • 请求参数:
  • 请求头:

    字段 取值 是否必须 描述
    Date 字符串,需符合Http协议定义 请求的当前时间
    Authorization 身份认证字符串,跟选用的认证机制有关,具体格式为:1. 签名认证: “Galaxy_V2” + “ “ + AppAccessKey + “:“ + Signature2. OAuth2.0认证: “OAuth”3. 小米SSO认证: “SSO” 目前支持Signature/OAuth2.0/小米SSO三种方式的认证,选择合适的使用

3.2 创建新Bucket

  • 语义:
    创建指定名字的Bucket
  • 语法:
    PUT /bucket_name HTTP/1.1
    Host: files.fds.api.xiaomi.com
    Date: date
    Content-Length: content_length
    Authorization: authorization_string
  • 请求参数:
    参数 取值 是否必须 描述
    acl 正常创建Bucket时不需要,如果要修改Bucket的ACL信息,需要指定该参数
  • 请求头:
    字段 取值 是否必须 描述
    Date 字符串,需符合Http协议定义 请求的当前时间
    Authorization 身份认证字符串,跟选用的认证机制有关,具体格式为:1. 签名认证: “Galaxy_V2” + “ “ + AppAccessKey + “:“ + Signature2. OAuth2.0认证: “OAuth”3. 小米SSO认证: “SSO” 目前支持Signature/OAuth2.0/小米SSO三种方式的认证,选择合适的使用
    Content-Length 整数值, body的长度 创建Bucket时,Body长度为0;修改Bucket ACL时,Body长度为对应的JSON string的长度

3.3 列Bucket下面的Object

  • 语义:
    列出指定Bucket下面所有的Objects
  • 语法:
    GET /bucket_name HTTP/1.1
    Host: files.fds.api.xiaomi.com
    Date: date
    Authorization: authorization_string
  • 请求参数:
    参数 取值 是否必须 描述
    acl 用于获取指定Bucket的ACL信息
    uploads 用于获取指定Bucket下正在进行的Multipart Upload
    prefix 字符串 列指定前缀的所有Objects
    delimiter 字符,缺省为’/’ Object名字中的分隔符,用来生成Common Prefix
    marker 字符串 当一个Bucket下面的Object数量大于maxKeys时,会分批次返回,marker表示当前批次的起始Object名字(字典序)
    maxKeys 在(0, 1000]范围内的整数,缺省为1000 当一个Bucket下面有比较多的Object数量的时候,需要分批次返回结果,maxKeys表示每个批次可返回Object数的最大值
  • 请求头:

    字段 取值 是否必须 描述
    Date 字符串,需符合Http协议定义 请求的当前时间
    Authorization 身份认证字符串,跟选用的认证机制有关,具体格式为:1. 签名认证: “Galaxy_V2” + “ “ + AppAccessKey + “:“ + Signature2. OAuth2.0认证: “OAuth”3. 小米SSO认证: “SSO” 目前支持Signature/OAuth2.0/小米SSO三种方式的认证,选择合适的使用

3.4 删除Bucket

  • 语义:
    删除指定名字的Bucket
  • 语法:
    DELETE /bucket_name HTTP/1.1
    Host: files.fds.api.xiaomi.com
    Date: date
    Authorization: authorization_string
  • 请求参数:
  • 请求头:

    字段 取值 是否必须 描述
    Date 字符串,需符合Http协议定义 请求的当前时间
    Authorization 身份认证字符串,跟选用的认证机制有关,具体格式为:1. 签名认证: “Galaxy_V2” + “ “ + AppAccessKey + “:“ + Signature
    2. OAuth2.0认证: “OAuth”
    3. 小米SSO认证: “SSO”
    目前支持Signature/OAuth2.0/小米SSO三种方式的认证,选择合适的使用

3.5 判断Bucket存在性

  • 语义:
    判断指定的Bucket是否存在
  • 语法:
    HEAD /bucket_name HTTP/1.1
    Host: files.fds.api.xiaomi.com
    Date: date
    Authorization: authorization_string
  • 请求参数:
  • 请求头:

    字段 取值 是否必须 描述
    Date 字符串,需符合Http协议定义 请求的当前时间
    Authorization 身份认证字符串,跟选用的认证机制有关,具体格式为:1. 签名认证: “Galaxy_V2” + “ “ + AppAccessKey + “:“ + Signature
    2. OAuth2.0认证: “OAuth”
    3. 小米SSO认证: “SSO”
    目前支持Signature/OAuth2.0/小米SSO三种方式的认证,选择合适的使用

4. Object操作REST API指南

4.1 上传Object (PUT)

  • 语义:
    上传指定名字的Object到指定的Bucket下,同名Object为覆盖语义
  • 语法:
    PUT /bucket_name/object_nameHTTP/1.1
    Host: files.fds.api.xiaomi.com
    Date: date
    Authorization: authorization_string
    body
  • 请求参数:
    参数 取值 是否必须 描述
    uploads Multipart Upload开关,传该参数,就表示当前的Upload是一个Multipart Upload
    partNumber 整数 Multipart Upload的part序号,用于表示当前上传的是第多少个part
    renameTo 字符串 用来对Object进行重命名,值是重命名后的Object名字
    acl ACL开关,传该参数,表示给当前的Object设置ACL
    expires 整数,毫秒 上传成功返回的Pre-signed URI的过期时间,不传的话,默认为30天
  • 请求头:

    字段 取值 是否必须 描述
    Date 字符串,需符合Http协议定义 请求的当前时间
    Authorization 身份认证字符串,跟选用的认证机制有关,具体格式为:1. 签名认证: “Galaxy_V2” + “ “ + AppAccessKey + “:“ + Signature2. OAuth2.0认证: “OAuth”3. 小米SSO认证: “SSO” 目前支持Signature/OAuth2.0/小米SSO三种方式的认证,选择合适的使用
    Content-Length 整数值, body长度 body内容的字节长度
    Content-Type 字符串, body类型 body内容的类型,缺省会根据文件名后缀进行自动识别,不能识别的缺省为置为binary/octet-stream
    Content-MD5 字符串, Base64(body MD5) 用于检验body内容正确性
    Cache-Control 字符串,需符合Http协议定义 用来控制对当前Object的缓存策略
    Content-Encoding 字符串,需符合Http协议定义 用来指定Object内容的编码方式
    Last-Modified 字符串,需符合Http协议定义 用来指定Object最后一次更新时间
    x-xiaomi-meta- 字符串,用户自定义的的元信息 以x-xiaomi-meta-为前缀,用户可以定义个性化的元信息

4.2 上传Object (POST)

  • 语义:
    从指定的Bucket下载指定的Object
  • 语法:
    GET /bucket_name/object_nameHTTP/1.1
    Host: files.fds.api.xiaomi.com
    Date: date
    Authorization: authorization_string
  • 请求参数:
    参数 取值 是否必须 描述
    acl 获取Object ACL信息的开关,打开时,GET的结果是对应Object的ACL信息
    metadata  获取Object元数据的开关,打开时,GET的结果是对应Object的元数据
  • 请求头:

    字段 取值 是否必须 描述
    Date 字符串,需符合Http协议定义 请求的当前时间
    Authorization 身份认证字符串,跟选用的认证机制有关,具体格式为:1. 签名认证: “Galaxy_V2” + “ “ + AppAccessKey + “:“ + Signature
    2. OAuth2.0认证: “OAuth”
    3. 小米SSO认证: “SSO”
    目前支持Signature/OAuth2.0/小米SSO三种方式的认证,选择合适的使用

4.3 删除Object

  • 语义:
     从指定的Bucket下删除指定的Object
  • 语法:
    DELETE /bucket_name/object_nameHTTP/1.1
    Host: files.fds.api.xiaomi.com
    Date: date
    Authorization: authorization_string
  • 请求参数:
    参数 取值 是否必须 描述
    uploadId 字符串 删除一个指定的Multipart Upload
  • 请求头:

    字段 取值 是否必须 描述
    Date 字符串,需符合Http协议定义 请求的当前时间
    Authorization 身份认证字符串,跟选用的认证机制有关,具体格式为:1. 签名认证: “Galaxy_V2” + “ “ + AppAccessKey + “:“ + Signature2. OAuth2.0认证: “OAuth”3. 小米SSO认证: “SSO” 目前支持Signature/OAuth2.0/小米SSO三种方式的认证,选择合适的使用

4.4 判断Object存在性

  • 语义:
    删除指定名字的Bucket
  • 语法:
    DELETE /bucket_name HTTP/1.1
    Host: files.fds.api.xiaomi.com
    Date: date
    Authorization: authorization_string
  • 请求参数:
  • 请求头:

    字段 取值 是否必须 描述
    Date 字符串,需符合Http协议定义 请求的当前时间
    Authorization 身份认证字符串,跟选用的认证机制有关,具体格式为:1. 签名认证: “Galaxy_V2” + “ “ + AppAccessKey + “:“ + Signature
    2. OAuth2.0认证: “OAuth”
    3. 小米SSO认证: “SSO”
    目前支持Signature/OAuth2.0/小米SSO三种方式的认证,选择合适的使用

3.5 判断Bucket存在性

  • 语义:
    判断指定Bucket下是否存在指定的Object
  • 语法:
    HEAD /bucket_name/object_nameHTTP/1.1
    Host: files.fds.api.xiaomi.com
    Date: date
    Authorization: authorization_string
  • 请求参数:
  • 请求头:

    字段 取值 是否必须 描述
    Date 字符串,需符合Http协议定义 请求的当前时间
    Authorization 身份认证字符串,跟选用的认证机制有关,具体格式为:1. 签名认证: “Galaxy_V2” + “ “ + AppAccessKey + “:“ + Signature2. OAuth2.0认证: “OAuth”3. 小米SSO认证: “SSO” 目前支持Signature/OAuth2.0/小米SSO三种方式的认证,选择合适的使用

4.5 Pre-signed URI

Pre-signed URI是FDS提供的一种灵活的共享资源的方式。Object的拥有者使用自己的App Secret Key预先对Object的访问链接进行签名,生成出带一定有效期的Pre-signed URI。Object拥有者将该Pre-signed URI发给其它用户,其它用户在上述有效期内可以用该Pre-signed URI对指定的Object,执行指定的操作。

  • Pre-signed URI的格式如下:
    http://files.fds.api.xiaomi.com/bucket_name/object_name?Expires=expires&GalaxyAccessKeyId=app_access_key&Signature=signature
  • 参数说明:
    参数 取值 是否必须 描述
    Expires 整数,毫秒 Pre-signed URI过期时间
    GalaxyAccessKeyId 字符串 签发Pre-signed URI者的App Access Key
    Signature 字符串 Base64编码过的签名串

 

5. FDS错误码参考

错误码 描述 Http状态码
Success 请求处理成功 200, OK
BucketAccessDenied 访问Bucket权限不够 403, Forbidden
BucketAlreadyExists 创建Bucket时Bucket已经存在 409, Conflict
BucketNotFound 访问的Bucket不存在 404, Not Found
ObjectAccessDenied 访问Object权限不够 403, Forbidden
ObjectAlreadyExists Post方式创建Object时Object已经存在 409, Conflict
ObjectNotFound 访问的Object不存在 404, Not Found
RequestTimeout 请求处理超时 401, Bad Request
InvalidRequest 非法的请求 401, Bad Request
SignatureDoesNotMatch 客户端跟服务端的签名不一致 403, Forbidden
RequestTimeTooSkewed 请求的时间戳超过15分钟的限制 403, Forbidden
RequestExpired 请求已过期 403, Forbidden
InvalidOAuthParameters OAuth认证的参数不合法 401, Bad Request
VerifyOAuthAccessTokenError 验证OAuth的Acess Token失败 403, Forbidden
QuotaExceeded 分配的Quota超过限制 401, Bad Request
RequestNotSupported 不支持的请求类型 501, Not Implemented
InvalidRequestRange 请求头中Range参数的值不合法 416, Requested Range Not Satisfiable
AuthenticationFailed 用户身份认证失败 403, Forbidden
InternalServerError 服务器内部出错,联系管理员 500, Internal Server Error

 

6. 其它

6.1 使用缩略图服务

FDS支持对JPEG/PNG/GIF三种类型的图片进行缩略,用户可以自行指定缩略的长、宽,具体用法是在请求的URL后面加下列参数:

参数 取值 是否必须 描述
thumb 1 缩略图开关,值为1表示开启缩略
w 整数值 缩略图的宽度,单位为像素
h 整数值 缩略图的高度,单位为像素

6.2 使用Https进行安全访问

FDS支持通过Https进行访问,将正常访问的URL中的scheme由Http替换为Https即可。对于比较敏感的用户信息,请尽量使用Https进行上传、下载。

6.3 使用CDN加速下载请求

FDS支持通过CDN加速下载请求,对于下载请求量比较大的应用,请尽量使用CDN来进行下载。CDN服务的地址为:

http://cdn.fds.api.xiaomi.com
https://cdns.fds.api.xiaomi.com

 

7. 文档修订历史

2014/10/23, 完成初始版本。