阿里云 OSS_API_20121008

2017-03-27

30803

,目录前言 ..................................................... 3 1. 阿里云存储服务简介........

前言 ..................................................... 3 1. 阿里云存储服务简介...................................... 4 2. 基本概念 ............................................... 5

2.1

2.2

2.3

2.4 Object ..................................................................................................... 5 Bucket .................................................................................................... 5 Access Key ID、Access Key Secret.................................................... 5 Service . ................................................................................................... 6 3. OSS 功能简介............................................ 7

3.1

3.2

3.3 OSS 基本功能 . ...................................................................................... 7 Object 外链地址的构成规则............................................................... 7 OSS 防盗链 ........................................................................................... 8 4. 访问控制 ............................................... 9

4.1

4.2

4.3

4.4 用户签名验证（Authentication ） ...................................................... 9 在Head 中包含签名 ............................................................................ 9 在URL 中包含签名 . .......................................................................... 14 Bucket 权限控制 . ................................................................................ 15 5. 开放接口规范 ...........................................17

5.1 公共HTTP 头定义 . ............................................................................ 18

5.1.1

5.1.2

5.2 公共请求头（Common Request Headers） . ..................... 18 公共响应头（Common Response Headers） ................... 19 关于Service 的操作 . .......................................................................... 20

5.2.1 GetService (ListBucket) . ...................................................... 20

5.3 关于Bucket 的操作 ........................................................................... 23

5.3.1

5.3.2

5.3.3

5.3.4

5.3.5 Delete Bucket . ....................................................................... 23 Get Bucket (List Object) ...................................................... 25 Get Bucket Acl . ..................................................................... 33 Put Bucket ............................................................................. 35 Put Bucket Acl ...................................................................... 37

5.4 关于Object 操作 ................................................................................ 39

5.4.1

5.4.2

5.4.3

5.4.4

5.4.5

5.4.6 Copy Object .......................................................................... 39 Delete Object......................................................................... 42 Delete Multiple Objects........................................................ 43 Get Object ............................................................................. 47 Head Object . .......................................................................... 51 Put Object . ............................................................................. 53

5.5 关于Multipart Upload的操作 .......................................................... 56

5.5.1

5.5.2

5.5.3

5.5.4

5.5.5

5.5.6 Initiate Multipart Upload . ..................................................... 56 Upload Part............................................................................ 59 Complete Multipart Upload ................................................. 61 Abort Multipart Upload . ....................................................... 65 List Multipart Uploads ......................................................... 66 List Parts . ............................................................................... 70

6. OSS 的错误响应 . .........................................74

6.1.

6.2.

6.3.

6.4.

6.5.

OSS 的错误响应格式 ........................................................................ 74 OSS 的错误码 . .................................................................................... 75 OSS 不支持分块传输编码 ................................................................ 77 OSS 不支持的操作............................................................................. 78 OSS 操作支持但参数不支持的操作 ............................................... 80

前言

本文档是阿里云存储服务（OSS ）的开发帮助指南，描述了OSS 中的基本概念、提供的服务以及可用的API 。

1. 阿里云存储服务简介

阿里云存储服务（OpenStorageService ，简称OSS ），是阿里云对外提供的海量，安全，低成本，高可靠的云存储服务。用户可以通过简单的REST 接口，在任何时间、任何地点、任何互联网设备上进行上传和下载数据，也可以使用WEB 页面对数据进行管理。同时，OSS 提供Java 、 Python 、 PHP 、C#语言的SDK ，简化用户的编程。基于OSS ，用户可以搭建出各种多媒体分享网站、网盘、个人和企业数据备份等基于大规模数据的服务。

公网的OSS 访问地址： http://oss.aliyuncs.com

阿里云主机的内网OSS 访问地址1：http://oss-internal.aliyuncs.com

OSS 的web 控制台地址：

1 阿里云主机通过内网域名访问OSS ，会拥有比访问公网域名更快的响应时间、更高的传输速度；同时，上传、下载流量都是免费的。

2. 基本概念

2.1 Object

在OSS 中，用户操作的基本数据单元是Object 。单个Object 最大允许存储5TB 的数据。Object 包含key 、meta 和data 。其中，key 是Object 的名字；meta 是用户对该object 的描述，由一系列name-value 对组成；data 是Object 的数据。

⏹ Object 命名规范

使用UTF-8编码

长度必须在1-1023字节之间

不能以“/”或者“”字符开头

2.2 Bucket

Bucket 是OSS 上的命名空间，也是计费、权限控制、日志记录等高级功能的管理实体；Bucket 名称在整个OSS 服务中具有全局唯一性，且不能修改；存储在OSS 上的每个Object 必须都包含在某个Bucket 中。一个应用，例如图片分享网站，可以对应一个或多个Bucket 。一个用户最多可创建10个Bucket ，但每个Bucket 中存放的Object 的数量和大小总和没有限制，用户不需要考虑数据的可扩展性。

⏹ Bucket 命名规范

只能包括小写字母，数字，短横线（-）

必须以小写字母或者数字开头

长度必须在3-63字节之间

2.3 Access Key ID、Access Key Secret

用户注册OSS 时，系统会给用户分配一对Access Key ID 和Access Key Secret ，

称为ID 对，用于标识用户，为访问OSS 做签名验证。

2.4 Service

OSS 提供给用户的虚拟存储空间，在这个虚拟空间中，每个用户可拥有一个到多个Bucket 。

3. OSS 功能简介

3.1 OSS 基本功能

OSS 为用户提供数据存储服务，用户可以通过以下操作来处理OSS 上的数据： ⏹ 创建、查看、罗列、删除 Bucket

⏹ 修改、获取Bucket 的访问权限

⏹ 上传、查看、罗列、删除、批量删除Object

⏹ 对于大文件支持分片上传（Multi-Part Upload）

⏹ 访问时支持If-Modified-Since 和If-Match 等HTTP 参数

3.2 Object 外链地址的构成规则

如果一个bucket 设置成公开读权限（详见下一章：访问控制），意味着你允许其他用户来访问属于你的object 。你的object 的外链地址构成规则如下：

例如，在一个名为oss-example 的bucket 中，有一个名为"aliyun-log.png" 的object （content-type 为image/png

）。那么这个object 的外链URL 为：

构成规则的示意图如下：

用户可以直接该URL 链接放入HTML 中使用：

3.3 OSS 防盗链

OSS 是按使用收费的服务，为了防止用户在OSS 上的数据被其他人盗链，OSS 支持基于HTTP header 中表头字段referer 的防盗链方法。目前，只有通过OSS 的控制台（http://oss.aliyun.com）可以对一个bucket 设置referer 字段的白名单和是否允许referer 字段为空的请求访问。例如，对于一个名为oss-example 的bucket ，设置其referer 白名单为http://www.aliyun.com。则所有referer 为http://www.aliyun.com的请求才能访问oss-example 这个bucket 中的Object 。

细节分析：

1) 用户只有通过URL 签名或者匿名访问Object 时，才会做防盗链验证。请求

的Header 中有“Authorization ”字段的，不会做防盗链验证。

2) 一个bucket 可以支持多个referer 参数，这些参数之间由“，”号分隔。

3) Referer 参数支持通配符“*”和“？”。

4) 用户可以设置是否允许referer 字段为空的请求访问。

5) 白名单为空时，不会检查referer 字段是否为空（不然所有的请求都会被拒绝）。

6) 白名单不为空，且设置了不允许referer 字段为空的规则；则只有referer 属于

白名单的请求被允许，其他请求（包括referer 为空的请求）会被拒绝。

7) 如果白名单不为空，但设置了允许referer 字段为空的规则；则referer 为空的

请求和符合白名单的请求会被允许；其他请求都会被拒绝。

8) Bucket 的三种权限（private ，public-read ，public-read-write ）都会检查referer

字段。

注意：OSS 更多的防盗链的规则正在开发中。

4. 访问控制

4.1 用户签名验证（Authentication ）

OSS 通过使用Access Key ID/ Access Key Secret对称加密的方法来验证某个请求的发送者身份。Access Key ID用于标示用户，Access Key Secret是用户用于加密签名字符串和OSS 用来验证签名字符串的密钥，其中Access Key Secret 必须保密，只有用户和OSS 知道。每个ACCESS Key对（Access Key ID和Access Key Secret）都有active/inactive两种状态。

⏹ active 表明用户可以用此ID 对签名验证请求

⏹ inactive 表明用户暂停此ID 对签名验证的功能

一个用户可以同时拥有0至2个active 或者inactive 的ID 对。用户可以登录http://oss.aliyun.com/，在OSS 管理控制台申请新增或删除ID 对。

当用户想以个人身份向OSS 发送请求时，需要首先将发送的请求按照OSS 指定的格式生成签名字符串；然后使用Access Key Secret对签名字符串进行加密产生验证码。 OSS 收到请求以后，会通过Access Key ID找到对应的Access Key Secret ，以同样的方法提取签名字符串和验证码，如果计算出来的验证码和提供的一样即认为该请求是有效的；否则，OSS 将拒绝处理这次请求，并返回HTTP 403错误。

4.2 在Head 中包含签名

用户可以在HTTP 请求中增加Authorization （授权）的Head 来包含签名(Signature)信息，表明这个消息已被授权。

Authorization 字段计算方法如下：

相关推荐