oss

目 錄

前 言

1.     阿里雲存儲服務簡介

2.     基本概念

2.1         Object

2.2         Bucket

2.3         Access Key ID、Access Key Secret

2.4         Service

3.     OSS功能簡介

3.1         OSS基本功能

3.2         Object外鏈地址的構成規則

3.3         OSS防盜鏈

3.4         自定義域名綁定（CNAME）

3.5         訪問日誌記錄(Server Access Logging)

4.     訪問控制

4.1         用戶簽名驗證（Authentication）

4.2         在Head中包含簽名

4.3         在URL中包含簽名

4.4         Bucket權限控制

5.     開放接口規範

5.1         公共HTTP頭定義

5.1.1             公共請求頭（Common Request Headers）

5.1.2             公共響應頭（Common Response Headers）

5.2         關於Service的操做

5.2.1             GetService (ListBucket)

5.3         關於Bucket的操做

5.3.1             Delete Bucket

5.3.2             Get Bucket (List Object)

5.3.3             Get Bucket Acl

5.3.4             Put Bucket

5.3.5             Put Bucket Acl

5.4         關於Object操做

5.4.1             Copy Object

5.4.2             Delete Object

5.4.3             Delete Multiple Objects

5.4.4             Get Object

5.4.5             Head Object

5.4.6             Put Object

5.5         關於Multipart Upload的操做

5.5.1             Initiate Multipart Upload

5.5.2             Upload Part

5.5.3             Complete Multipart Upload

5.5.4             Abort Multipart Upload

5.5.5             List Multipart Uploads

5.5.6             List Parts

6.     OSS的錯誤響應

6.1.        OSS的錯誤響應格式

6.2.        OSS的錯誤碼

6.3.        OSS不支持分塊傳輸編碼

6.4.        OSS不支持的操做

6.5.        OSS操做支持但參數不支持的操做

 

 

 

 

 

 

 

 

 

 

 

 

前 言

本文檔是阿里雲存儲服務（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控制檯地址：http://oss.aliyun.com/

 

 

 

2. 基本概念

2.1          Object

在OSS中，用戶操做的基本數據單元是Object。單個Object最大容許存儲5TB的數據。Object包含key、meta和data。其中，key是Object的名字；meta是用戶對該object的描述，由一系列name-value對組成；data是Object的數據。

n  Object命名規範

Ø  使用UTF-8編碼

Ø  長度必須在1-1023字節之間

Ø  不能以「/」或者「\」字符開頭

2.2          Bucket

Bucket是OSS上的命名空間，也是計費、權限控制、日誌記錄等高級功能的管理實體；Bucket名稱在整個OSS服務中具備全局惟一性，且不能修改；存儲在OSS上的每一個Object必須都包含在某個Bucket中。一個應用，例如圖片分享網站，能夠對應一個或多個Bucket。一個用戶最多可建立10個Bucket，但每一個Bucket中存放的Object的數量和大小總和沒有限制，用戶不須要考慮數據的可擴展性。

n  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上的數據：

n  建立、查看、羅列、刪除 Bucket

n  修改、獲取Bucket的訪問權限

n  上傳、查看、羅列、刪除、批量刪除Object

n  對於大文件支持分片上傳（Multi-Part Upload）

n  訪問時支持If-Modified-Since和If-Match等HTTP參數

 

3.2          Object外鏈地址的構成規則

若是一個bucket設置成公開讀權限（詳見下一章：訪問控制），意味着你容許其餘用戶來訪問屬於你的object。你的object的外鏈地址構成規則以下：

http:// <你的bucket名字>.oss.aliyuncs.com/<你的object名字>

例如，在一個名爲oss-example的bucket中，有一個名爲"aliyun-log.png"的object（content-type爲image/png）。那麼這個object的外鏈URL爲：

http://oss-example.oss.aliyuncs.com//image/aliyun-logo.png

構成規則的示意圖以下：

 用戶能夠直接該URL連接放入HTML中使用：

<img src="http://oss-example.oss.aliyuncs.com/aliyun-logo.png"/>

 

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更多的防盜鏈的規則正在開發中。

3.4          自定義域名綁定（CNAME）

OSS支持用戶將自定義的域名綁定在屬於本身的bucket上面，這個操做必須經過OSS控制檯（http://oss.aliyun.com）來實現。按照中國《互聯網管理條例》的要求，全部須要開通這項功能的用戶，必須提供阿里雲備案號，域名持有者身份證等有效資料，經由阿里雲審批經過後纔可使用。在開通CNAME功能後，OSS將自動處理對該域名的訪問請求。

 

CNAME應用場景例子：

Ø  用戶A擁有一個域名爲abc.com的網站；這個網站的全部圖片存儲在img.abc.com這個子域名下；

Ø  爲了應對日益增加的圖片流量壓力，用戶A在OSS上建立了一個名爲abc-img的bucket，並將全部圖片存在OSS上；

Ø  經過OSS控制檯，提交將img.abc.com CNAME成 abc-img.oss.aliyuncs.com的申請，並提供相應的材料

Ø  經過阿里雲審覈後，在本身的域名服務器上，添加一條CNAME規則，將img.abc.com映射成abc-img.oss.aliyuncs.com，這樣全部對img.abc.com的訪問都將變成訪問abc-img這個bucket。例如：一個對http://img.abc.com/logo.png的訪問，實際上訪問的是http://abc-img.oss.aliyuncs.com/logo.png。

 

3.5          訪問日誌記錄^[2](Server Access Logging)

OSS爲用戶提供自動保存訪問日誌記錄功能。Bucket的擁有者能夠經過OSS控制檯（http://oss.aliyun.com），爲其所擁有的bucket開啓訪問日誌記錄功能。當一個bucket（源Bucket，Source Bucket）開啓訪問日誌記錄功能後，OSS自動將訪問這個bucket的請求日誌，以小時爲單位，按照固定的命名規則，生成一個Object寫入用戶指定的bucket（目標Bucket，Target Bucket）。

 

存儲訪問日誌記錄的object命名規則：

<TargetPrefix><SourceBucket>-YYYY-mm-DD-HH-MM-SS-UniqueString

命名規則中，TargetPrefix由用戶指定；YYYY, mm, DD, HH, MM和SS分別是該Object被建立時的阿拉伯數字的年，月，日，小時，分鐘和秒（注意位數）；UniqueString爲OSS系統生成的字符串。一個實際的用於存儲OSS訪問日誌的Object名稱例子以下：

MyLog-oss-example-2012-09-10-04-00-00-0000

上例中，「MyLog-」是用戶指定的Object前綴；「oss-example」是源bucket的名稱；「2012-09-10-04-00-00」是該Object被建立時的北京時間；「0000」 是OSS系統生成的字符串。

 

LOG文件格式（從左至右，以空格分隔）：

名 稱	例 子	含 義
Remote IP	119.140.142.11	請求發起的IP地址（Proxy代理或用戶防火牆可能會屏蔽該字段）
Reserved	-	保留字段
Reserved	-	保留字段
Time	[02/May/2012:00:00:04 +0800]	OSS收到請求的時間
Request-URI	「GET /aliyun-logo.png HTTP/1.1「	用戶請求的URI(包括query-string)
HTTP Status	200	OSS返回的HTTP狀態碼
SentBytes	5576	用戶從OSS下載的流量
RequestTime (ms)	71	完成本次請求的時間（毫秒）
Referrer	http://oss.aliyun.com	請求的HTTP Referrer
User-Agent	curl/7.15.5	HTTP的User-Agent頭
HostName	oss-example.oss.aliyuncs.com	請求訪問域名
Request ID	505B01695037C2AF032593A4	用於惟一標示該請求的UUID
LoggingFlag	true	是否開啓了訪問日誌功能
Reserved	-	保留字段
Requester Aliyun ID	1657136103983691	請求者的阿里雲ID；匿名訪問爲「-」
Operation	GetObject	請求類型
Bucket	oss-example	請求訪問的Bucket名字
Key	/aliyun-logo.png	用戶請求的Key
ObjectSize	5576	Object大小
Server Cost Time (ms)	17	OSS服務器處理本次請求所花的時間（毫秒）
Error Code	NoSuchBucket	OSS返回的錯誤碼
UserID	1657136103983691	Bucket擁有者ID
Delta DataSize	280	Bucket大小的變化量；若沒有變化爲「-」

 

細節分析：

1)  源Bucket和目標Bucket必須屬於同一個用戶。

2)  「TargetPrefix」表示存儲訪問日誌記錄的object名字前綴，能夠爲空。

3)  源bucket和目標bucket能夠是同一個Bucket，也能夠是不一樣的Bucket；用戶也能夠將多個的源bucket的LOG都保存在同一個目標bucket內（建議指定不一樣的TargetPrefix）。

4)  OSS以小時爲單位生成bucket訪問的Log文件，但並不表示這個小時的全部請求都記錄在這個小時的LOG文件內，也有可能出如今上一個或者下一個LOG文件中。

5)  OSS生成的Log文件命名規則中的「UniqueString」僅僅是OSS爲其生成的UUID，用於惟一標識該文件。

6)  OSS生成一個bucket訪問的Log文件，算做一次PUT操做，並記錄其佔用的空間，但不會記錄產生的流量。LOG生成後，用戶能夠按照普通的Object來操做這些LOG文件。

7)  OSS會忽略掉全部以「x-」開頭的query-string參數，但這個query-string會被記錄在訪問LOG中。若是你想從海量的訪問日誌中，標示一個特殊的請求，能夠在URL中添加一個「x-」開頭的query-string參數。如：

http://oss-example.oss.aliyuncs.com/aliyun-logo.png http://oss-example.oss.aliyuncs.com/aliyun-logo.png?x-user=admin

OSS處理上面兩個請求，結果是同樣的。可是在訪問LOG中，你能夠經過搜索「x-user=admin」，很方便地定位出通過標記的這個請求。

8)  OSS的LOG中的任何一個字段，均可能出現「-」，用於表示未知數據或對於當前請求該字段無效。

9)  根據需求，OSS的LOG格式未來會在尾部添加一些字段，請開發者開發Log處理工具時考慮兼容性的問題。

 

 

 

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兩種狀態。

n  active代表用戶能夠用此ID對簽名驗證請求

n  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字段計算方法以下：

"Authorization: OSS " + Access Key ID + ":" + Signature   Signature = base64(hmac-sha1(VERB + "\n"                     + CONTENT-MD5 + "\n"                     + CONTENT-TYPE + "\n"                     + DATE + "\n"                     + CanonicalizedOSSHeaders                     + CanonicalizedResource))

n   CONTENT-MD5表示請求內容數據的MD5值

n   CONTENT-TYPE表示請求內容的類型

n   DATE表示這次操做的時間，且必須爲HTTP1.1中支持的GMT格式

n   CanonicalizedOSSHeaders表示 http中的object meta組合

n   CanonicalizedResource 表示用戶想要訪問的OSS資源

其中，DATE和CanonicalizedResource不能爲空；若是請求中的DATE時間和OSS服務器的時間差正負15分鐘以上，OSS服務器將拒絕該服務，並返回HTTP 403錯誤。

 

構建CanonicalizedOSSHeaders的方法：

全部以「x-oss-」爲前綴的HTTP Header被稱爲CanonicalizedOSSHeaders。它的構建方法以下：

1)         將全部以「x-oss-」爲前綴的HTTP請求頭的名字轉換成小寫字母。如’X-OSS-Meta-Name: TaoBao’轉換成’x-oss-meta-name: TaoBao’。 2)         將上一步獲得的全部HTTP請求頭按照字典序進行升序排列。 3)         若是有相同名字的請求頭，則根據標準RFC 2616, 4.2章進行合併（兩個值之間只用逗號分隔）。若有兩個名爲’x-oss-meta-name’的請求頭，對應的值分別爲’TaoBao’和’Alipay’，則合併後爲：’x-oss-meta-name:TaoBao,Alipay’。 4)         刪除請求頭和內容之間分隔符兩端出現的任何空格。如’x-oss-meta-name: TaoBao,Alipay’轉換成：’x-oss-meta-name:TaoBao,Alipay’。 5)         將全部的頭和內容用’\n’分隔符分隔拼成最後的CanonicalizedOSSHeader。

 

構建CanonicalizedResource的方法：

   用戶發送請求中想訪問的OSS目標資源被稱爲CanonicalizedResource。它的構建方法以下：

1)         將CanonicalizedResource置成空字符串（「」）； 2)         放入要訪問的OSS資源：「 /BucketName/ObjectName」（無ObjectName則不填） 3)         若是請求的資源包括子資源(sub-resource) href="#_ftn3" [3]，那麼將全部的子資源按照字典序，從小到大排列並以’&’爲分隔符生成子資源字符串。在CanonicalizedResource字符串尾添加「？」和子資源字符串。此時的CanonicalizedResource例子如：/BucketName/ObjectName?acl &uploadId=UploadId 4)         若是用戶請求在查詢字符串(query string)中指定了要重寫(override)返回請求的header href="#_ftn4" [4]，那麼將這些查詢字符串及其請求值按照字典序，從小到大排列，以’&’爲分隔符，按參數的字典序添加到CanonicalizedResource中。此時的CanonicalizedResource例子： /BucketName/ObjectName?acl&response-content-type=ContentType & uploadId =UploadId

 

例如：想簽名如下信息：

PUT /nelson HTTP/1.0 Content-Md5: c8fdb181845a4ca6b8fec737b3581d76 Content-Type: text/html Date: Thu, 17 Nov 2005 18:49:58 GMT Host: oss-example.oss.aliyuncs.com X-OSS-Meta-Author: foo@bar.com X-OSS-Magic: abracadabra

假如Access Key ID是： "44CF9590006BF252F707"

Access Key Secret是 "OtxrzxIsfpFjA7SwPzILwy8Bw21TLhquhboDYROV"，可用如下方法簽名(Signature):

python示例代碼：

import base64 import hmac import sha h = hmac.new("OtxrzxIsfpFjA7SwPzILwy8Bw21TLhquhboDYROV",              "PUT\nc8fdb181845a4ca6b8fec737b3581d76\ntext/html\nThu, 17 Nov 2005 18:49:58 GMT\nx-oss-magic:abracadabra\nx-oss-meta-author:foo@bar.com\n/oss-example/nelson", sha) base64.encodestring(h.digest()).strip()

簽名(Signature)計算結果應該爲」63mwfl+zYIOG6k95yxbgMruQ6QI=」， 而後加上Authorization頭來組成最後須要發送的消息：

PUT /nelson HTTP/1.0 Authorization: OSS 44CF9590006BF252F707: 63mwfl+zYIOG6k95yxbgMruQ6QI= Content-Md5: c8fdb181845a4ca6b8fec737b3581d76 Content-Type: text/html Date: Thu, 17 Nov 2005 18:49:58 GMT Host: oss-example.oss.aliyuncs.com X-OSS-Meta-Author: foo@bar.com X-OSS-Magic: abracadabra

   

在計算簽名頭的時候請遵循以下規則： 

1)  用來簽名的字符串必須爲UTF-8格式。含有中文字符的簽名字符串必須先進行UTF-8編碼，再與Access Key Secret計算最終簽名。

2)  簽名的方法用RFC 2104 (http://www.ietf.org/rfc/rfc2104.txt)中定義的HMAC-SHA1方法，其中Key爲Access Key Secret。

3)  content-type和content-md5在請求中不是必須的，可是若是請求須要簽名驗證，空值的話以換行符「\n」代替。

4)  在全部非HTTP標準定義的header中，只有以「x-oss-」開頭的header，須要加入簽名字符串；其餘非HTTP標準header將被OSS忽略（如上例中的x-oss-magic）。

5)  以「x-oss-」開頭的head在簽名驗證前須要符合如下規範：

Ø  head的名字須要變成小寫。

Ø  head按字典序自小到大排序。

Ø  分割head name和value的冒號先後不能有空格。

Ø  每一個Head以後都有一個換行符「\n」，若是沒有Head，CanonicalizedOSSHeaders就設置爲空。

 

細節分析：

1)  若是傳入的Access Key ID不存在或inactive，返回403 Forbidden。錯誤碼：InvalidAccessKeyId。

2)  若用戶請求頭中Authorization值的格式不對，返回400 Bad Request。錯誤碼：InvalidArgument。

3)  OSS全部的請求都必須使用HTTP 1.1協議規定的GMT時間格式。其中，日期的格式有三種：

date1 = 2DIGIT SP month SP 4DIGIT; day month year (e.g., 02 Jun 1982)

date2 = 2DIGIT "-" month "-" 2DIGIT; day-month-year (e.g., 02-Jun-82)

date3 = month SP ( 2DIGIT | ( SP 1DIGIT )); month day (e.g., Jun  2)  【注意「2」前面有兩個空格】

上述這三種日期格式中，「天」所佔位數都是「2 DIGIT」。所以，「Jun 2」、「2 Jun 1982」和「2-Jun-82」都是非法日期格式。

4)  若是簽名驗證的時候，頭中沒有傳入Date或者格式不正確，返回403 Forbidden錯誤。錯誤碼：AccessDenied。

5)  傳入請求的時間必須在OSS服務器當前時間以後的15分鐘之內，不然返回403 Forbidden。錯誤碼：RequestTimeTooSkewed。

6)  若是Access Key ID是active的，但OSS判斷用戶的請求發生簽名錯誤，則返回403 Forbidden，並在返回給用戶的response中告訴用戶正確的用於驗證加密的簽名字符串。用戶能夠根據OSS的response來檢查本身的簽名字符串是否正確。

返回示例：

<?xml version="1.0" encoding="UTF-8"?> <Error xmlns=」http://doc.oss.aliyuncs.com」> <Code>            SignatureDoesNotMatch </Code> <Message>            The request signature we calculated does not match the signature you provided. Check your key and signing method. </Message> <StringToSignBytes>            47 45 54 0a 0a 0a 57 65 64 2c 20 31 31 20 4d 61 79 20 32 30 31 31 20 30 37 3a 35 39 3a 32 35 20 47 4d 54 0a 2f 75 73 72 65 61 6c 74 65 73 74 3f 61 63 6c </StringToSignBytes> <RequestId>            1E446260FF9B10C2 </RequestId> <HostId>            oss.aliyuncs.com </HostId> <SignatureProvided>            y5H7yzPsA/tP4+0tH1HHvPEwUv8= </SignatureProvided> <StringToSign>            GET Wed, 11 May 2011 07:59:25 GMT /oss-example?acl </StringToSign> <OSSAccessKeyId>            AKIAIVAKMSMOY7VOMRWQ </OSSAccessKeyId> </Error>

 

4.3          在URL中包含簽名

除了使用Authorization Head，用戶還能夠在URL中加入簽名信息，這樣用戶就能夠把該URL轉給第三方實現受權訪問。

 

URL中包含簽名示例:

http://oss-example.oss.aliyuncs.com/oss-api.pdf?OSSAccessKeyId=44CF9590006BF252F707&Expires=1141889120&Signature=vjbyPxybdZaNmGa%2ByT272YEAiv4%3D

 

在URL中實現簽名，必須至少包含Signature，Expires，OSSAccessKeyId三個參數。Expires這個參數的值是一個UNIX時間（自UTC時間1970年1月1號開始的秒數，詳見wiki），用於標識該URL的超時時間。若是OSS接收到這個URL請求的時候晚於簽名中包含的Expires參數時，則返回請求超時的錯誤碼。例如：當前時間是1141889060，開發者但願建立一個60秒後自動失效的URL，則能夠設置Expires時間爲1141889120。

全部的OSS支持的請求和各類Head參數，在URL中進行簽名的方法和上節介紹的簽名算法基本同樣。主要區別以下：

1)        經過URL包含簽名時，以前的Date參數換成Expires參數。

2)        不支持同時在URL和Head中包含簽名。

3)        若是傳入的Signature，Expires，OSSAccessKeyId出現不止一次，以第一次爲準。

4)        請求先驗證請求時間是否晚於Expires時間，而後再驗證簽名。

 

URL中添加簽名的python示例代碼爲：

import base64 import hmac import sha import urllib h = hmac.new("OtxrzxIsfpFjA7SwPzILwy8Bw21TLhquhboDYROV",              "GET\n\n\n1141889120\n/oss-example/oss-api.pdf",              sha) urllib.quote_plus (base64.encodestring(h.digest()).strip())

 

細節分析：

1)        使用在URL中籤名的方式，會將你受權的數據在過時時間之內曝露在互聯網上，請預先評估使用風險。

2)        PUT和GET請求都支持在URL中籤名。

3)        在URL中添加簽名時，Signature，Expires，OSSAccessKeyId順序能夠交換，可是若是Signature，Expires，OSSAccessKeyId缺乏其中的一個或者多個，返回403 Forbidden。錯誤碼：AccessDenied。

4)        若是訪問的當前時間晚於請求中設定的Expires時間，返回403 Forbidden。錯誤碼：AccessDenied。

5)        若是傳入請求時間，必須在OSS服務器當前時間以後的15分鐘之內。不然返回403 Forbidden。錯誤碼：RequestTimeTooSkewed。

6)        若是Expires時間格式錯誤，返回403 Forbidden。錯誤碼：AccessDenied。

7)        若是URL中包含參數Signature，Expires，OSSAccessKeyId中的一個或者多個，而且Head中也包含簽名消息，返回消息400 Bad Request。錯誤碼：InvalidArgument。

8)        生成簽名字符串時，除Date被替換成Expires參數外，仍然包含content-type、content-md5等上節中定義的Header。（請求中雖然仍然有Data這個請求頭，但不須要將Data加入簽名字符串中）

 

4.4          Bucket權限控制

OSS提供Bucket級別的權限訪問控制，Bucket目前有三種訪問權限：public-read-write，public-read和private，它們的含義以下：

n  public-read-write：任何人（包括匿名訪問）均可以對該bucket中的object進行PUT，Get和Delete操做；全部這些操做產生的費用由該bucket的建立者承擔，請慎用該權限。

n  public-read：只有該bucket的建立者能夠對該bucket內的Object進行寫操做（包括Put和Delete Object）；任何人（包括匿名訪問）能夠對該bucket中的object進行讀操做（Get Object）。

n  private：只有該bucket的建立者能夠對該bucket內的Object進行讀寫操做（包括Put、Delete和Get Object）；其餘人沒法訪問該Bucket內的Object。

用戶新建立一個新Bucket時，若是不指定Bucket權限，OSS會自動爲該Bucket設置private權限。對於一個已經存在的Bucket，只有它的建立者能夠經過OSS的 Put Bucket Acl接口修改該Bucket的權限。

 

相關閱讀:

Ø  Put Bucket Acl

Ø  Get Bucket Acl

 

Ø   

5.  開放接口規範

本章主要介紹OSS的開放接口。開發者在發送請求給OSS時，既可使用帶簽名認證的請求，也可使用匿名訪問。當簽名驗證錯誤或者是訪問沒有權限的資源時，OSS返回的錯誤碼請參考下一章，本章就不在舉例了。

 

 

5.1          公共HTTP頭定義

5.1.1                公共請求頭（Common Request Headers）

OSS的RESTful接口中使用了一些公共請求頭。這些請求頭能夠被全部的OSS請求所使用，其詳細定義以下：

名稱	描述
Authorization	用於驗證請求合法性的認證信息。 類型：字符串 默認值：無 使用場景：非匿名請求
Content-Length	RFC 2616中定義的HTTP請求內容長度。 類型：字符串 默認值：無 使用場景：須要向OSS提交數據的請求
Content-Type	RFC 2616中定義的HTTP請求內容類型。 類型：字符串 默認值：無 使用場景：須要向OSS提交數據的請求
Date	HTTP 1.1協議中規定的GMT時間，例如：Wed, 05 Sep. 2012 23:00:00 GMT 類型：字符串 默認值：無
Host	訪問Host值，格式爲：<bucketname>.oss.aliyuncs.com。 類型：字符串 默認值：無

 

 

5.1.2                公共響應頭（Common Response Headers）

OSS的RESTful接口中使用了一些公共響應頭。這些響應頭能夠被全部的OSS請求所使用，其詳細定義以下：

名稱	描述
Content-Length	RFC 2616中定義的HTTP請求內容長度。 類型：字符串 默認值：無 使用場景：須要向OSS提交數據的請求
Connection	標明客戶端和OSS服務器之間的連接狀態。 類型：枚舉 有效值：open | close 默認值：無
Date	HTTP 1.1協議中規定的GMT時間，例如：Wed, 05 Sep. 2012 23:00:00 GMT 類型：字符串 默認值：無
ETag	ETag (entity tag) 在每一個Object生成的時候被建立，用於標示一個Object的內容。對於Put Object請求建立的Object，ETag值是其內容的MD5值；對於其餘方式建立的Object，ETag值是其內容的UUID。ETag值能夠用於檢查Object內容是否發生變化。 類型：字符串 默認值：無
Server	生成Response的服務器。 類型：字符串 默認值：AliyunOSS
x-oss-request-id	x-oss-request-id是由Aliyun OSS建立，並惟一標識這個response的UUID。若是在使用OSS服務時遇到問題，能夠憑藉該字段聯繫OSS工做人員，快速定位問題。 類型：字符串 默認值：無

 

 

5.2          關於Service的操做

5.2.1                GetService (ListBucket)

對於服務地址做Get請求能夠返回請求者擁有的全部Bucket，其中「/」表示根目錄。

 

請求語法：

GET / HTTP/1.1 Host: oss.aliyuncs.com Date: GMT Date Authorization: SignatureValue

 

響應元素(Response Elements)

名稱	描述
Bucket	保存bucket信息的容器. 類型：容器 子節點：Name, CreationDate 父節點：ListAllMyBucketsResult.Buckets
Buckets	保存多個Bucket信息的容器。 類型：容器 子節點：Bucket 父節點：ListAllMyBucketsResult
CreateDate	Bucket建立時間 類型：時間 (格式：yyyy-mm-ddThh:mm:ss.timezone, e.g., 2011-12-01T12:27:13.000Z) 父節點：ListAllMyBucketsResult.Buckets.Bucket
DisplayName	Bucket擁有者的名稱 (目前和ID一致)。 類型：字符串 父節點：ListAllMyBucketsResult.Owner
ID	Bucket擁有者的用戶ID。 類型：字符串 父節點：ListAllMyBucketsResult.Owner
ListAllMyBucketsResult	保存Get Service請求結果的容器。 類型：容器 子節點: Owner, Buckets 父節點：None
Name	Bucket名稱。 類型：字符串 父節點：ListAllMyBucketsResult.Buckets.Bucket
Owner	用於存放Bucket擁有者信息的容器。 類型：容器 父節點：ListAllMyBucketsResult

 

細節分析：

1)  GetService這個API只對驗證經過的用戶有效。

2)  若是請求中沒有用戶驗證信息（即匿名訪問），返回403 Forbidden。錯誤碼：AccessDenied。

 

請求示例：

GET / HTTP/1.1 Host: oss.aliyuncs.com Date: Fri, 24 Feb 2012 02:58:28 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:MiorP5BDFDhKAn44wDnkSSv2Z94=

返回示例：

HTTP/1.1 200 OK x-oss-request-id: 60633d3c-1293-0d72-7739-759423f02d36 Date: Fri, 24 Feb 2012 02:58:28 GMT Content-type: application/xml Content-Length: 685 Connection: close Server: AliyunOSS   <?xml version="1.0" encoding="UTF-8"?> <ListAllMyBucketsResult xmlns=」http://doc.oss.aliyuncs.com」>     <Owner>         <ID>00220120222</ID>         <DisplayName>oss_doc</DisplayName>     </Owner>     <Buckets>         <Bucket>             <Name>multipart_upload</Name>             <CreationDate>2012-02-22T08:25:07.000Z</CreationDate>         </Bucket>         <Bucket>             <Name>my_oss</Name>             <CreationDate>2012-02-24T02:53:26.000Z</CreationDate>         </Bucket>     </Buckets> </ListAllMyBucketsResult>

 

相關閱讀：

Ø  Get Bucket (List Object)

Ø  Get Object

 

 

5.3          關於Bucket的操做

5.3.1                Delete Bucket

Delete Bucket用於刪除某個Bucket。

 

請求語法：

DELETE / HTTP/1.1 Host: BucketName.oss.aliyuncs.com Date: GMT Date Authorization: SignatureValue

 

細節分析：

1)  若是Bucket不存在，返回404 no content錯誤。錯誤碼：NoSuchBucket。

2)  爲了防止誤刪除的發生，OSS不容許用戶刪除一個非空的Bucket。

3)  若是試圖刪除一個不爲空的Bucket，返回409 Conflict錯誤，錯誤碼：BucketNotEmpty。

4)  只有Bucket的擁有者才能刪除這個Bucket。若是試圖刪除一個沒有對應權限的Bucket，返回403 Forbidden錯誤。錯誤碼：AccessDenied。

 

請求示例：

DELETE / HTTP/1.1 Host: oss-example.oss.aliyuncs.com  Date: Fri, 24 Feb 2012 05:31:04 GMT  Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:ceOEyZavKY4QcjoUWYSpYbJ3naA=

返回示例：

HTTP/1.1 204 No Content x-oss-request-id: 7faf664d-0cad-852e-4b38-2ac2232e7e7f  Date: Fri, 24 Feb 2012 05:31:04 GMT Connection: close Content-Length: 0  Server: AliyunOSS

 

相關閱讀：

Ø  Put Bucket

Ø  Delete Object

5.3.2                Get Bucket (List Object)

Get Bucket操做可用來list Bucket中全部Object的信息。

 

請求語法：

GET / HTTP/1.1 Host: BucketName.oss.aliyuncs.com Date: GMT Date Authorization: SignatureValue

 

請求參數(Request Parameters)：

   GetBucket（ListObject）時，能夠經過prefix，marker，delimiter和max-keys對list作限定，返回部分結果。

名稱	描述
delimiter	是一個用於對Object名字進行分組的字符。全部名字包含指定的前綴且第一次出現delimiter字符之間的object做爲一組元素——CommonPrefixes。 數據類型：字符串 默認值：無
marker	設定結果從marker以後按字母排序的第一個開始返回。 數據類型：字符串 默認值：無
max-keys	限定這次返回object的最大數，若是不設定，默認爲1000，max-keys取值不能大於1000。 數據類型：字符串 默認值：100
prefix	限定返回的object key必須以prefix做爲前綴。注意使用prefix查詢時，返回的key中仍會包含prefix。 數據類型：字符串 默認值：無

 

響應元素(Response Elements)

名稱	描述
Contents	保存每一個返回Object meta的容器。 類型：容器 父節點：ListBucketResult
CommonPrefixes	若是請求中指定了delimiter參數，則在OSS返回的響應中包含CommonPrefixes元素。該元素標明那些以delimiter結尾，並有共同前綴的object名稱的集合。 類型：字符串 父節點：ListBucketResult
Delimiter	是一個用於對Object名字進行分組的字符。全部名字包含指定的前綴且第一次出現delimiter字符之間的object做爲一組元素——CommonPrefixes。 類型：字符串 父節點：ListBucketResult
DisplayName	Object 擁有者的名字。 類型：字符串 父節點：ListBucketResult.Contents.Owner
ETag	ETag (entity tag) 在每一個Object生成的時候被建立，用於標示一個Object的內容。對於Put Object請求建立的Object，ETag值是其內容的MD5值；對於其餘方式建立的Object，ETag值是其內容的UUID。ETag值能夠用於檢查Object內容是否發生變化。 類型：字符串 父節點：ListBucketResult.Contents
ID	Bucket擁有者的用戶ID。 類型：字符串 父節點：ListBucketResult.Contents.Owner
IsTruncated	指明是否全部的結果都已經返回；「true」標示全部結果都已經返回；「false」表示本次請求只返回了部分結果。 類型：枚舉字符串 有效值：true | false 父節點：ListBucketResult
Key	Object的Key. 類型：字符串 父節點：ListBucketResult.Contents
LastModified	Object最後被修改的時間。 類型：時間 父節點：ListBucketResult.Contents
ListBucketResult	保存Get Bucket請求結果的容器. 類型：容器 子節點：Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, Nextmarker, Contents 父節點：None
Marker	標明此次Get Bucket（List Object）的起點。 類型：字符串 父節點：ListBucketResult
MaxKeys	響應請求內返回結果的最大數目。 類型：字符串 父節點：ListBucketResult
Name	Bucket名字 類型：字符串 父節點：ListBucketResult
Owner	保存Bucket擁有者信息的容器。 類型：容器 子節點：DisplayName, ID 父節點：ListBucketResult
Prefix	本次查詢結果的開始前綴。 類型：字符串 父節點：ListBucketResult
Size	Object的字節數。 類型：字符串 父節點：ListBucketResult.Contents
StorageClass	Object的存儲類型，目前只能是「Standard」 類型：字符串 父節點：ListBucketResult.Contents

 

細節分析：

1)  Object中用戶自定義的meta，在GetBucket請求時不會返回。

2)  若是訪問的Bucket不存在，包括試圖訪問由於命名不規範沒法建立的Bucket，返回404 Not Found錯誤，錯誤碼：NoSuchBucket。

3)  若是沒有訪問該Bucket的權限，返回403 Forbidden錯誤，錯誤碼：AccessDenied。

4)  若是由於max-keys的設定沒法一次完成listing，返回結果會附加一個<NextMarker>，提示繼續listing能夠以此爲marker。NextMarker中的值仍在list結果之中。

5)  在作條件查詢時，即便marker實際在列表中不存在，返回也從符合marker字母排序的下一個開始打印。若是max-keys小於0或者大於1000，將返回400 Bad Request錯誤。錯誤碼：InvalidArgument。

6)  若prefix，marker，delimiter參數不符合長度要求，返回400 Bad Request。錯誤碼：InvalidArgument。

7)  prefix，marker用來實現分頁顯示效果，參數的長度必須小於1024字節。

8)  若是把prefix設爲某個文件夾名，就能夠羅列以此prefix開頭的文件，即該文件夾下遞歸的全部的文件和子文件夾。若是再把delimiter設置爲 / 時，返回值就只羅列該文件夾下的文件，該文件夾下的子文件名返回在CommonPrefixes部分，子文件夾下遞歸的文件和文件夾不被顯示。如一個bucket存在三個object :

fun/test.jpg， fun/movie/001.avi， fun/movie/007.avi。

若設定prefix爲」fun/」 ，則返回三個object；若是增長設定delimiter爲「/」，則返回文件」fun/test.jpg」和前綴」fun/movie/」；即實現了文件夾的邏輯。

 

舉例場景：

在bucket「my_oss」內有4個object，名字分別爲：

l  oss.jpg

l  fun/test.jpg

l  fun/movie/001.avi

l  fun/movie/007.avi

 

請求示例：

GET / HTTP/1.1 Host: oss-example.oss.aliyuncs.com Date: Fri, 24 Feb 2012 08:43:27 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykboO4M=

返回示例：

HTTP/1.1 200 OK x-oss-request-id: 248c6483-2a95-622e-3022-ebe65d8aad5f Date: Fri, 24 Feb 2012 08:43:27 GMT Content-Type: application/xml Content-Length: 1866 Connection: close Server: AliyunOSS   <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns=」http://doc.oss.aliyuncs.com」> <Name>oss-example</Name> <Prefix></Prefix> <Marker></Marker> <MaxKeys>100</MaxKeys> <Delimiter></Delimiter>     <IsTruncated>false</IsTruncated>     <Contents>         <Key>fun/movie/001.avi</Key>         <LastModified>2012-02-24T08:43:07.000Z</LastModified>         <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>         <Type>Normal</Type>         <Size>344606</Size>         <StorageClass>Standard</StorageClass>         <Owner>             <ID>00220120222</ID>             <DisplayName>user-example</DisplayName>         </Owner>     </Contents>     <Contents>         <Key>fun/movie/007.avi</Key>         <LastModified>2012-02-24T08:43:27.000Z</LastModified>         <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>         <Type>Normal</Type>         <Size>344606</Size>         <StorageClass>Standard</StorageClass>         <Owner>             <ID>00220120222</ID>             <DisplayName>user-example</DisplayName>         </Owner>     </Contents> <Contents>         <Key>fun/test.jpg</Key>         <LastModified>2012-02-24T08:42:32.000Z</LastModified>         <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>         <Type>Normal</Type>         <Size>344606</Size>         <StorageClass>Standard</StorageClass>         <Owner>             <ID>00220120222</ID>             <DisplayName>user-example</DisplayName>         </Owner>     </Contents>     <Contents>         <Key>oss.jpg</Key>         <LastModified>2012-02-24T06:07:48.000Z</LastModified>         <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>         <Type>Normal</Type>         <Size>344606</Size>         <StorageClass>Standard</StorageClass>         <Owner>             <ID>00220120222</ID>             <DisplayName>user-example</DisplayName>         </Owner>     </Contents> </ListBucketResult>

 

請求示例(含Prefix參數)：

GET /?prefix=fun HTTP/1.1 Host: oss-example.oss.aliyuncs.com Date: Fri, 24 Feb 2012 08:43:27 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykboO4M=

返回示例：

HTTP/1.1 200 OK x-oss-request-id: 25cb535f-1feb-1e90-2f22-12176bcb563e Date: Fri, 24 Feb 2012 08:43:27 GMT Content-Type: application/xml Content-Length: 1464 Connection: close Server: AliyunOSS   <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns=」http://doc.oss.aliyuncs.com」> <Name>oss-example</Name> <Prefix>fun</Prefix> <Marker></Marker> <MaxKeys>100</MaxKeys> <Delimiter></Delimiter>     <IsTruncated>false</IsTruncated>     <Contents>         <Key>fun/movie/001.avi</Key>         <LastModified>2012-02-24T08:43:07.000Z</LastModified>         <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>         <Type>Normal</Type>         <Size>344606</Size>         <StorageClass>Standard</StorageClass>         <Owner>             <ID>00220120222</ID>             <DisplayName>user_example</DisplayName>         </Owner>     </Contents>     <Contents>         <Key>fun/movie/007.avi</Key>         <LastModified>2012-02-24T08:43:27.000Z</LastModified>         <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>         <Type>Normal</Type>         <Size>344606</Size>         <StorageClass>Standard</StorageClass>         <Owner>             <ID>00220120222</ID>             <DisplayName>user_example</DisplayName>         </Owner>     </Contents>     <Contents>         <Key>fun/test.jpg</Key>         <LastModified>2012-02-24T08:42:32.000Z</LastModified>         <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>         <Type>Normal</Type>         <Size>344606</Size>         <StorageClass>Standard</StorageClass>         <Owner>             <ID>00220120222</ID>             <DisplayName>user_example</DisplayName>         </Owner>     </Contents> </ListBucketResult>

 

請求示例(含prefix和delimiter參數)：

GET /?prefix=fun/&delimiter=/ HTTP/1.1 Host: oss-example.oss.aliyuncs.com Date: Fri, 24 Feb 2012 08:43:27 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:DNrnx7xHk3sgysx7I8U9I9IY1vY=

返回示例：

HTTP/1.1 200 OK x-oss-request-id: 0b05f9b1-539e-a858-0a81-9ca13d8a8011 Date: Fri, 24 Feb 2012 08:43:27 GMT Content-Type: application/xml Content-Length: 712 Connection: close Server: AliyunOSS   <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns=」http://doc.oss.aliyuncs.com」> <Name>oss-example</Name> <Prefix>fun/</Prefix> <Marker></Marker> <MaxKeys>100</MaxKeys> <Delimiter>/</Delimiter>     <IsTruncated>false</IsTruncated>     <Contents>         <Key>fun/test.jpg</Key>         <LastModified>2012-02-24T08:42:32.000Z</LastModified>         <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>         <Type>Normal</Type>         <Size>344606</Size>         <StorageClass>Standard</StorageClass>         <Owner>             <ID>00220120222</ID>             <DisplayName>user_example</DisplayName>         </Owner>     </Contents>    <CommonPrefixes>         <Prefix>fun/movie/</Prefix>    </CommonPrefixes> </ListBucketResult>

 

相關閱讀：

Ø  Put Bucket

Ø  Put Object

Ø  Get Object

 

 

5.3.3                Get Bucket Acl

Get Bucket ACL用來獲取某個Bucket的訪問權限。

 

請求語法：

GET /?acl HTTP/1.1 Host: BucketName.oss.aliyuncs.com Date: GMT Date Authorization: SignatureValue

 

響應元素(Response Elements)

名稱	描述
AccessControlList	存儲ACL信息的容器 類型：容器 父節點：AccessControlPolicy
AccessControlPolicy	保存Get Bucket ACL結果的容器 類型：容器 父節點：None
DisplayName	Bucket擁有者的名稱.。(目前和ID一致) 類型：字符串 父節點：AccessControlPolicy.Owner
Grant	Bucket的ACL權限。 類型：枚舉字符串 有效值：private | public-read | public-read-write 父節點：AccessControlPolicy.AccessControlList
ID	Bucket擁有者的用戶ID 類型：字符串 父節點：AccessControlPolicy.Owner
Owner	保存Bucket擁有者信息的容器。 類型：容器 父節點：AccessControlPolicy

 

細節分析：

1)        只有Bucket的擁有者才能使用Get Bucket ACL這個接口。

 

請求示例：

GET /?acl HTTP/1.1 Host: oss-example.oss.aliyuncs.com Date: Fri, 24 Feb 2012 04:11:23 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:CTkuxpLAi4XZ+WwIfNm0FmgbrQ0=

返回示例：

HTTP/1.1 200 OK x-oss-request-id: 6f720c98-40fe-6de0-047b-e7fb08c4059b Date: Fri, 24 Feb 2012 04:11:23 GMT Content-Length: 253 Content-Tupe: application/xml Connection: close Server: AliyunOSS   <?xml version="1.0" ?> <AccessControlPolicy>     <Owner>         <ID>00220120222</ID>         <DisplayName>user_example</DisplayName>     </Owner>     <AccessControlList>         <Grant>public-read</Grant>     </AccessControlList> </AccessControlPolicy>

 

相關閱讀：

Ø  Put Bucket

Ø  Get Bucket Acl

 

 

5.3.4                Put Bucket

PutBucket用於建立Bucket（不支持匿名訪問）。

 

請求語法：

PUT / HTTP/1.1 Host: BucketName.oss.aliyuncs.com Date: GMT Date Authorization: SignatureValue

 

細節分析：

1)  若是請求的Bucket已經存在，而且請求者是全部者，一樣返回200 OK成功。

2)  若是請求的Bucket已經存在，可是不是請求者所擁有的，返回409 Conflict。錯誤碼：BucketAlreadyExists。

3)  若是想建立的Bucket不符合命名規範，返回400 Bad Request消息。錯誤碼：InvalidBucketName。

4)  若是用戶發起PUT Bucket請求的時候，沒有傳入用戶驗證信息，返回403 Forbidden消息。錯誤碼：AccessDenied。

5)  若是PutBucket的時候發現已經超過bucket最大建立數——10時，返回400 Bad Request消息。錯誤碼：TooManyBuckets。

6)  建立的Bucket，若是沒有指定訪問權限，則默認使用「Private」權限。

 

請求示例：

PUT / HTTP/1.1 Host: oss-example.oss.aliyuncs.com Date: Fri, 24 Feb 2012 03:15:40 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:77Dvh5wQgIjWjwO/KyRt8dOPfo8=

返回示例：

HTTP/1.1 200 OK x-oss-request-id: 7c9e8b71-3c6a-1b7d-2361-093f1af5f5e9 Date: Fri, 24 Feb 2012 03:15:40 GMT Location: /oss-example Content-Length: 0 Connection: close Server: AliyunOSS

 

相關閱讀：

Ø  Get Bucket (List Object)

Ø  Delete Bucket

Ø  Put Object

 

 

5.3.5                Put Bucket Acl

Put Bucket ACL接口用於修改Bucket訪問權限。目前Bucket有三種訪問權限：public-read-write，public-read和private。Put Bucket ACL操做經過Put請求中的「x-oss-acl」頭來設置。這個操做只有該Bucket的建立者有權限執行。若是操做成功，則返回200；不然返回相應的錯誤碼和提示信息。

 

請求語法：

PUT / HTTP/1.1 x-oss-acl: Permission Host: BucketName.oss.aliyuncs.com Date: GMT Date Authorization: SignatureValue

 

細節分析：

1)  若是bucket存在，發送時帶的權限和已有權限不同，而且請求發送者是bucket擁有者時。該請求不會改變bucket內容，可是會更新權限。

2)  若是用戶發起Put Bucket請求的時候，沒有傳入用戶驗證信息，返回403 Forbidden消息。錯誤碼：AccessDenied。

3)  若是請求中沒有，「x-oss-acl」頭，而且該bucket已存在，並屬於該請求發起者，則維持原bucket權限不變。

 

請求示例：

PUT / HTTP/1.1 x-oss-acl: public-read Host: oss-example.oss.aliyuncs.com Date: Fri, 24 Feb 2012 03:21:12 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:KU5h8YMUC78M30dXqf3JxrTZHiA=

返回示例：

HTTP/1.1 200 OK x-oss-request-id: 248c6483-2a95-622e-3022-ebe65d8aad5f Date: Fri, 24 Feb 2012 03:21:12 GMT Content-Length: 0 Connection: close Server: AliyunOSS

 

若是該設置的權限不存在，示例400 Bad Request消息：

錯誤返回示例：

HTTP/1.1 400 Bad Request x-oss-request-id: 4e63c87a-71dc-87f7-11b5-583a600e0038 Date: Fri, 24 Feb 2012 03:55:00 GMT Content-Length: 309 Content-Type: text/xml; charset=UTF-8 Connection: close Server: AliyunOSS   <?xml version="1.0" ?> <Error xmlns=」http://doc.oss.aliyuncs.com」>         <Code>                 InvalidArgument         </Code>         <Message>         </Message>         <ArgumentValue>                 error-acl         </ArgumentValue>         <ArgumentName>                 x-oss-acl         </ArgumentName>         <RequestId>                 4e63c87a-71dc-87f7-11b5-583a600e0038         </RequestId>         <HostId>                 oss.aliyuncs.com         </HostId> </Error>

 

相關閱讀：

Ø  Put Bucket

Ø  Get Bucket Acl

 

 

5.4          關於Object操做

5.4.1                Copy Object

拷貝一個在OSS上已經存在的object成另一個object，能夠發送一個PUT請求給OSS，並在PUT請求頭中添加元素「x-oss-copy-source」來指定拷貝源。OSS會自動判斷出這是一個Copy操做，並直接在服務器端執行該操做。若是拷貝成功，則返回新的object信息給用戶。

 

請求語法：

PUT / /ObjectName HTTP/1.1 Host: BucketName.oss.aliyuncs.com Date: GMT Date Authorization: SignatureValue x-oss-copy-source: /SourceBucketName/SourceObjectName

 

請求Header：

名稱	描述
x-oss-copy-source	複製源地址（必須有可讀權限） 類型：字符串 默認值：無
x-oss-copy-source-if-match	若是源Object的ETAG值和用戶提供的ETAG相等，則執行拷貝操做；不然返回412 HTTP錯誤碼（預處理失敗）。 類型：字符串 默認值：無
x-oss-copy-source-if-none-match	若是源Object自從用戶指定的時間之後就沒有被修改過，則執行拷貝操做；不然返回412 HTTP錯誤碼（預處理失敗）。 類型：字符串 默認值：無
x-oss-copy-source-if-unmodified-since	若是傳入參數中的時間等於或者晚於文件實際修改時間，則正常傳輸文件，並返回200 OK；不然返回412 precondition failed錯誤。 類型：字符串 默認值：無
x-oss-copy-source-if-modified-since	若是源Object自從用戶指定的時間之後被修改過，則執行拷貝操做；不然返回412 HTTP錯誤碼（預處理失敗）。 類型：字符串 默認值：無
x-oss-metadata-directive	有效值爲COPY和REPLACE。若是該值設爲COPY，則新的Object的meta都從源Object複製過來；若是設爲REPLACE，則忽視全部源Object的meta值，而採用用戶此次請求中指定的meta值；其餘值則返回400 HTTP錯誤碼。 類型：字符串 默認值：COPY 有效值：COPY | REPLACE

 

響應元素(Response Elements)：

名稱	描述
CopyObjectResult	Copy Object結果 類型：字符串 默認值：無
ETag	新Object的ETag值。 類型：字符串 父元素：CopyObjectResult
LastModified	新Object最後更新時間。 類型：字符串 父元素：CopyObjectResult

 

細節分析：

1)  能夠經過拷貝操做來實現修改已有Object的meta信息。

2)  若是拷貝操做的源Object地址和目標Object地址相同，則不管x-oss-metadata-directive爲什麼值，都會直接替換源Object的meta信息。

3)  OSS支持拷貝操做的四個預判斷Header任意個同時出現，相應邏輯參見Get Object操做的細節分析。

4)  拷貝操做須要請求者對源Object有讀權限。

5)  拷貝操做的計費統計會對源Object所在的Bucket增長一次Get請求次數，並對目標Object所在的Bucket增長一次Put請求次數，以及相應的新增存儲空間。

6)  拷貝操做涉及到的請求頭，都是以「x-oss-」開頭的，因此要加入簽名字符串中。

 

請求示例：

PUT /copy_oss.jpg HTTP/1.1 Host: oss-example.oss.aliyuncs.com Date: Fri, 24 Feb 2012 07:18:48 GMT x-oss-copy-source: /oss-example/oss.jpg Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:gmnwPKuu20LQEjd+iPkL259A+n0=

返回示例：

HTTP/1.1 200 OK x-oss-request-id: 3dfb2597-72a0-b3f7-320f-8b6627a96e68 Content-Type: application/xml Content-Length: 193 Connection: close Date: Fri, 24 Feb 2012 07:18:48 GMT Server: AliyunOSS   <?xml version="1.0" encoding="UTF-8"?> <CopyObjectResult xmlns=」http://doc.oss.aliyuncs.com」>     <LastModified>Fri, 24 Feb 2012 07:18:48 GMT</LastModified>     <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag> </CopyObjectResult>

 

相關閱讀：

Ø  Put Object

Ø  Get Object

Ø  Delete Object

 

 

5.4.2                Delete Object

DeleteObject用於刪除某個Object。

 

請求語法：

DELETE /ObjectName HTTP/1.1 Host: BucketName.oss.aliyuncs.com Date: GMT Date Authorization: SignatureValue

 

細節分析：

1)  DeleteObject要求對該Object要有寫權限。

2)  若是要刪除的Object不存在，OSS也返回狀態碼204（ No Content）。

3)  若是Bucket不存在，返回404 Not Found。

 

請求示例：

DELETE /copy_oss.jpg HTTP/1.1 Host: oss-example.oss.aliyuncs.com Date: Fri, 24 Feb 2012 07:45:28 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:zUglwRPGkbByZxm1+y4eyu+NIUs=

返回示例：

HTTP/1.1 204 NoContent x-oss-request-id: 1a61ecd1-5de8-4e2e-20b5-c66e135bc379 Date: Fri, 24 Feb 2012 07:45:28 GMT Content-Length: 0 Connection: close Server: AliyunOSS

 

相關閱讀：

Ø  Put Object

Ø  Get Object

Ø  Delete Multiple Objects

 

 

5.4.3                Delete Multiple Objects

Delete Multiple Object操做支持用戶經過一個HTTP請求刪除同一個Bucket中的多個Object。Delete Multiple Object操做支持一次請求內最多刪除1000個Object，並提供兩種返回模式：詳細(verbose)模式和簡單(quiet)模式:

l  詳細模式：OSS返回的消息體中會包含每個刪除Object的結果。

l  簡單模式：OSS返回的消息體中只包含刪除過程當中出錯的Object結果；若是全部刪除都成功的話，則沒有消息體。

 

請求語法：

POST /?delete HTTP/1.1 Host: BucketName.oss.aliyuncs.com Date: GMT Date Content-Length: ContentLength Content-MD5: MD5Value Authorization: SignatureValue   <?xml version="1.0" encoding="UTF-8"?> <Delete>   <Quiet>true</Quiet>   <Object>     <Key>key</Key>   </Object> … </Delete>

 

請求元素(Request Elements)：

名稱	描述
Delete	保存Delete Multiple Object請求的容器。 類型：容器 子節點：一個或多個Object元素，可選的Quiet元素 父節點： None.
Key	被刪除Object的名字。 類型：字符串 父節點：Object
Object	保存一個Object信息的容器。 類型：容器 子節點：key 父節點：Delete.
Quiet	打開「安靜」響應模式的開關。 類型：枚舉字符串 有效值：true | false 默認值：false 父節點：Delete

 

響應元素(Response Elements)：

名稱	描述
Deleted	保存被成功刪除的Object的容器。 類型：容器 子節點：Key 父節點：DeleteResult
DeleteResult	保存Delete Multiple Object請求結果的容器。 類型：容器 子節點：Deleted 父節點：None
Key	OSS執行刪除操做的Object名字。 類型：字符串 父節點：Deleted

 

細節分析：

1)  Delete Multiple Object請求必須填Content-Length和Content-MD5字段。OSS會根據這些字段驗證收到的消息體是正確的，以後纔會執行刪除操做。

2)  生成Content-MD5字段內容方法：首先將Delete Multiple Object請求內容通過MD5加密後獲得一個128位字節數組；再將該字節數組用base64算法編碼；最後獲得的字符串便是Content-MD5字段內容。

3)  Delete Multiple Object請求默認是詳細(verbose)模式。

4)  在Delete Multiple Object請求中刪除一個不存在的Object，仍然認爲是成功的。

5)  Delete Multiple Object的消息體最大容許2MB的內容，超過2MB會返回MalformedXML錯誤碼。

6)  Delete Multiple Object請求最多容許一次刪除1000個Object；超過1000個Object會返回MalformedXML錯誤碼。

 

請求示例I：

POST /?delete HTTP/1.1 Host: oss-example.oss.aliyuncs.com Date: Wed, 29 Feb 2012 12:26:16 GMT Content-Length:151 Content-MD5: fae2e404736a78a0067b62d80b1cc7d8 Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:+z3gBfnFAxBcBDgx27Y/jEfbfu8=   <?xml version="1.0" encoding="UTF-8"?> <Delete> <Quiet>false</Quiet> <Object> <Key>multipart.data</Key> </Object> <Object> <Key>test.jpg</Key> </Object> <Object> <Key>demo.jpg</Key> </Object> </Delete>

返回示例：

HTTP/1.1 200 OK x-oss-request-id: 78320852-7eee-b697-75e1-b6db0f4849e7 Date: Wed, 29 Feb 2012 12:26:16 GMT Content-Length: 244 Content-Type: application/xml Connection: close Server: AliyunOSS   <?xml version="1.0" encoding="UTF-8"?> <DeleteResult xmlns=」http://doc.oss.aliyuncs.com」>     <Deleted>        <Key>multipart.data</Key>     </Deleted>     <Deleted>        <Key>test.jpg</Key>     </Deleted>     <Deleted>        <Key>demo.jpg</Key>     </Deleted> </DeleteResult>

 

請求示例II：

POST /?delete HTTP/1.1 Host: oss-example.oss.aliyuncs.com Date: Wed, 29 Feb 2012 12:33:45 GMT Content-Length:151 Content-MD5: fae2e404736a78a0067b62d80b1cc7d8 Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:WuV0Jks8RyGSNQrBca64kEExJDs=   <?xml version="1.0" encoding="UTF-8"?> <Delete> <Quiet>true</Quiet> <Object> <Key>multipart.data</Key> </Object> <Object> <Key>test.jpg</Key> </Object> <Object> <Key>demo.jpg</Key> </Object> </Delete>

返回示例：

HTTP/1.1 200 OK x-oss-request-id: 501ad9bb-1383-771d-0ee9-59a810bd5fde Date: Wed, 29 Feb 2012 12:33:45 GMT Content-Length: 0 Connection: close Server: AliyunOSS

 

相關閱讀：

Ø  Delete Object

 

 

5.4.4                Get Object

用於獲取某個Object，此操做要求用戶對該Object有讀權限。

 

請求語法：

GET /ObjectName HTTP/1.1 Host: BucketName.oss.aliyuncs.com Date: GMT Date Authorization: SignatureValue Range: bytes=ByteRange(可選)

 

請求參數：

   OSS支持用戶在發送GET請求時，能夠自定義OSS返回請求中的一些Header，這些Header包括：

名稱	描述
response-content-type	設置OSS返回請求的content-type頭 類型：字符串 默認值：無
response-content-language	設置OSS返回請求的content-language頭 類型：字符串 默認值：無
response-expires	設置OSS返回請求的expires頭 類型：字符串 默認值：無
response-cache-control	設置OSS返回請求的cache-control頭 類型：字符串 默認值：無
response-content-disposition	設置OSS返回請求的content-disposition頭 類型：字符串 默認值：無
response-content-encoding	設置OSS返回請求的content-encoding頭 類型：字符串 默認值：無

 

請求Header：

名稱	描述
Range	指定文件傳輸的範圍。如，設定 bytes=0-9，表示傳送第0到第9這10個字符。 類型：字符串 默認值：無
If-Modified-Since	若是指定的時間早於實際修改時間，則正常傳送文件，並返回200 OK；不然返回304 not modified 類型：字符串 默認值：無
If-Unmodified-Since	若是傳入參數中的時間等於或者晚於文件實際修改時間，則正常傳輸文件，並返回200 OK；不然返回412 precondition failed錯誤 類型：字符串 默認值：無
If-Match	若是傳入指望的ETag和object的 ETag匹配，則正常傳輸文件，並返回200 OK；不然返回412 precondition failed錯誤 類型：字符串 默認值：無
If-None-Match	若是傳入的ETag值和Object的ETag不匹配，則正常傳輸文件,並返回200 OK；不然返回304 Not Modified 類型：字符串 默認值：無

 

細節分析：

1)  GetObject經過range參數能夠支持斷點續傳，對於比較大的Object建議使用該功能。

2)  若是在請求頭中使用Range參數；則返回消息中會包含整個文件的長度和這次返回的範圍，例如：Content-Range: bytes 0-9/44，表示整個文件長度爲44，這次返回的範圍爲0-9。若是不符合範圍規範，則傳送整個文件，而且不在結果中說起Content-Range。

3)  若是「If-Modified-Since」元素中設定的時間不符合規範，直接返回文件，並返回200 OK。

4)  If-Modified-Since和If-Unmodified-Since能夠同時存在，If-Match和If-None-Match也能夠同時存在。

5)  若是包含If-Unmodified-Since而且不符合或者包含If-Match而且不符合，返回412 precondition failed

6)  若是包含If-Modified-Since而且不符合或者包含If-None-Match而且不符合，返回304 Not Modified

7)  若是文件不存在返回404 Not Found錯誤。錯誤碼：NoSuchKey。

8)  OSS不支持在匿名訪問的GET請求中，經過請求參數來自定義返回請求的header。

9)  在自定義OSS返回請求中的一些Header時，只有請求處理成功（即返回碼爲200時），OSS纔會將請求的header設置成用戶GET請求參數中指定的值。

 

請求示例：

GET /oss.jpg HTTP/1.1 Host: oss-example.oss.aliyuncs.com Date: Fri, 24 Feb 2012 06:38:30 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:UNQDb7GapEgJCZkcde6OhZ9Jfe8=

返回示例：

HTTP/1.1 200 OK x-oss-request-id: 3a89276f-2e2d-7965-3ff9-51c875b99c41 Date: Fri, 24 Feb 2012 06:38:30 GMT Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT ETag: "5B3C1A2E053D763E1B002CC607C5A0FE " Content-Type: image/jpg Content-Length: 344606 Server: AliyunOSS   [344606 bytes of object data]

 

Range請求示例：

GET //oss.jpg HTTP/1.1 Host:oss-example. oss.aliyuncs.com Date: Fri, 28 Feb 2012 05:38:42 GMT Range: bytes=100-900 Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:qZzjF3DUtd+yK16BdhGtFcCVknM=

返回示例：

HTTP/1.1 206 Partial Content x-oss-request-id: 28f6508f-15ea-8224-234e-c0ce40734b89 Date: Fri, 28 Feb 2012 05:38:42 GMT Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT ETag: "5B3C1A2E053D763E1B002CC607C5A0FE " Accept-Ranges: bytes Content-Range: bytes 100-900/344606 Content-Type: image/jpg Content-Length: 801 Server: AliyunOSS   [801 bytes of object data]

 

自定義返回消息頭的請求示例（URL簽名方式）：

GET /oss.jpg?response-expires=Thu%2C%2001%20Feb%202012%2017%3A00%3A00%20GMT& response-content-type=text&response-cache-control=No-cache&response-content-disposition=attachment%253B%2520filename%253Dtesting.txt&response-content-encoding=utf-8&response-content-language=%E4%B8%AD%E6%96%87 HTTP/1.1 Host: oss-example.oss.aliyuncs.com: Date: Fri, 24 Feb 2012 06:09:48 GMT

返回示例：

HTTP/1.1 200 OK x-oss-request-id: 1144d124-055c-4052-2c65-a1e3439d41c1 Date: Fri, 24 Feb 2012 06:09:48 GMT Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT ETag: "5B3C1A2E053D763E1B002CC607C5A0FE " Content-Length: 344606 Connection: close Content-disposition: attachment; filename:testing.txt Content-language: 中文 Content-encoding: utf-8 Content-type: text Cache-control: no-cache Expires: Fri, 24 Feb 2012 17:00:00 GMT Server: AliyunOSS   [344606 bytes of object data]

 

相關閱讀：

Ø  Get Object

Ø  Delete Object

 

 

5.4.5                Head Object

Head Object只返回某個Object的meta信息，不返回文件內容。

 

請求語法：

HEAD /ObjectName HTTP/1.1 Host: BucketName/oss.aliyuncs.com Date: GMT Date Authorization: SignatureValue

 

請求Header：

名稱	描述
If-Modified-Since	若是指定的時間早於實際修改時間，則返回200 OK和Object Meta；不然返回304 not modified 類型：字符串 默認值：無
If-Unmodified-Since	若是傳入參數中的時間等於或者晚於文件實際修改時間，則返回200 OK和Object Meta；不然返回412 precondition failed錯誤 類型：字符串 默認值：無
If-Match	若是傳入指望的ETag和object的 ETag匹配，則返回200 OK和Object Meta；不然返回412 precondition failed錯誤 類型：字符串 默認值：無
If-None-Match	若是傳入的ETag值和Object的ETag不匹配，則返回200 OK和Object Meta；不然返回304 Not Modified 類型：字符串 默認值：無

 

細節分析：

1)  不論正常返回200 OK仍是非正常返回，Head Object都不返回消息體。

2)  HeadObject支持在頭中設定If-Modified-Since, If-Unmodified-Since, If-Match，If-None-Match的查詢條件。具體規則請參見GetObject中對應的選項。若是沒有修改，返回304 Not Modified。

3)  若是用戶在PutObject的時候傳入以x-oss-meta-爲開頭的user meta，好比x-oss-meta-location，返回消息時，返回這些user meta。

4)  若是文件不存在返回404 Not Found錯誤。

 

請求示例：

HEAD /oss.jpg HTTP/1.1 Host: oss-example.oss.aliyuncs.com Date: Fri, 24 Feb 2012 07:32:52 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:JbzF2LxZUtanlJ5dLA092wpDC/E=

返回示例：

HTTP/1.1 200 OK x-oss-request-id: 06d4be30-2216-9264-757a-8f8b19b254bb Date: Fri, 24 Feb 2012 07:32:52 GMT Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT ETag: "fba9dede5f27731c9771645a39863328" Content-Length: 344606 Content-Type: image/jpg Connection: close Server: AliyunOSS

 

相關閱讀：

Ø  Put Object

Ø  Get Object

 

 

5.4.6                Put Object

Put Object用於上傳文件。

 

請求語法：

PUT /ObjectName HTTP/1.1 Content-Length：ContentLength Content-Type: ContentType Host: BucketName.oss.aliyuncs.com Date: GMT Date Authorization: SignatureValue

 

請求Header：

名稱	描述
Cache-Control	指定該Object被下載時的網頁的緩存行爲；更詳細描述請參照RFC2616。 類型：字符串 默認值：無
Content-Disposition	指定該Object被下載時的名稱；更詳細描述請參照RFC2616。 類型：字符串 默認值：無
Content-Encoding	指定該Object被下載時的內容編碼格式；更詳細描述請參照RFC2616。 類型：字符串 默認值：無
Expires	過時時間（milliseconds）；更詳細描述請參照RFC2616。 類型：整數 默認值：無

 

細節分析：

1)  Put Object請求處理成功後，OSS會將收到文件的MD5值放在返回給用戶的請求頭「ETag」中，以便用戶檢查OSS上的數據和要上傳的數據內容一致。

2)  若是請求頭中的「Content-Length」值小於實際請求體（body）中傳輸的數據長度，OSS仍將成功建立文件；但Object大小隻等於「Content-Length」中定義的大小，其餘數據將被丟棄。

3)  若是試圖添加的Object的同名文件已經存在，而且有訪問權限。新添加的文件將覆蓋原來的文件，成功返回200 OK。

4)  若是在PutObject的時候，攜帶以x-oss-meta-爲前綴的參數，則視爲user meta，好比x-oss-meta-location。一個Object能夠有多個相似的參數，但全部的user meta總大小不能超過2k。

5)  若是Head中沒有加入Content length參數，會返回411 Length Required錯誤。錯誤碼：MissingContentLength。

6)  若是設定了長度，可是沒有發送消息Body，或者發送的body大小小於給定大小，服務器會一直等待，直到time out，返回400 Bad Request消息。錯誤碼：RequestTimeout。此時OSS上的這個文件內容是用戶已經上傳完的數據。

7)  若是試圖添加的Object所在的Bucket不存在，返回404 Not Found錯誤。錯誤碼：NoSuchBucket。

8)  若是試圖添加的Object所在的Bucket沒有訪問權限，返回403 Forbidden錯誤。錯誤碼：AccessDenied。

9)  若是添加文件長度超過5G，返回錯誤消息400 Bad Request。錯誤碼：InvalidArgument。

10) 若是傳入的Object key長度大於1023，返回400 Bad Request。錯誤碼：InvalidObjectName。

11) PUT一個Object的時候，OSS支持4個 HTTP RFC 2616協議規定的Header 字段：Cache-Control、Expires、Content-Encoding、Content-Disposition。若是上傳Object時設置了這些Header，則這個Object被下載時，相應的Header值會被自動設置成上傳時的值。

 

請求示例：

PUT /oss.jpg HTTP/1.1 Host: oss-example.oss.aliyuncs.com Cache-control: no-cache Expires: Fri, 28 Feb 2012 05:38:42 GMT Content-Encoding: utf-8 Content-Disposition: attachment;filename=oss_download.jpg Date: Fri, 24 Feb 2012 06:03:28 GMT Content-Type: image/jpg Content-Length: 344606 Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:kZoYNv66bsmc10+dcGKw5x2PRrk=   [344606 bytes of object data]

返回示例：

HTTP/1.1 200 OK x-oss-request-id: 61d2042d-1b68-6708-5906-33d81921362e Date: Fri, 24 Feb 2012 06:03:28 GMT ETag: 5B3C1A2E053D763E1B002CC607C5A0FE Connection: close Content-Length: 0  Server: AliyunOSS

 

相關閱讀：

Ø  Get Object

Ø  Delete Object

 

 

5.5          關於Multipart Upload的操做

除了經過PUT Object接口上傳文件到OSS之外，OSS還提供了另一種上傳模式——Multipart Upload。用戶能夠在以下的應用場景內（但不只限於此），使用Multipart Upload上傳模式，如：

l  須要支持斷點上傳。

l  上傳超過100MB大小的文件。

l  網絡條件較差，和OSS的服務器之間的連接常常斷開。

l  須要流式地上傳文件。

l  上傳文件以前，沒法肯定上傳文件的大小。

5.5.1                Initiate Multipart Upload

使用Multipart Upload模式傳輸數據前，必須先調用該接口來通知OSS初始化一個Multipart Upload事件。該接口會返回一個OSS服務器建立的全局惟一的Upload ID，用於標識本次Multipart Upload事件。用戶能夠根據這個ID來發起相關的操做，如停止Multipart Upload、查詢Multipart Upload等。

 

請求語法：

POST /ObjectName?uploads HTTP/1.1 Host: BucketName.oss.aliyuncs.com Date: GMT date Authorization: SignatureValue

 

請求Header：

名稱	描述
Cache-Control	指定該Object被下載時的網頁的緩存行爲；更詳細描述請參照RFC2616。 類型：字符串 默認值：無
Content-Disposition	指定該Object被下載時的名稱；更詳細描述請參照RFC2616。 類型：字符串 默認值：無
Content-Encoding	指定該Object被下載時的內容編碼格式；更詳細描述請參照RFC2616。 類型：字符串 默認值：無
Expires	過時時間（milliseconds）；更詳細描述請參照RFC2616。 類型：整數 默認值：無

 

響應元素(Response Elements)：

名稱	描述
Bucket	初始化一個Multipart Upload事件的Bucket名稱。 類型：字符串 父節點：InitiateMultipartUploadResult
InitiateMultipartUploadResult	保存Initiate Multipart Upload請求結果的容器。 類型：容器 子節點：Bucket, Key, UploadId 父節點：None
Key	初始化一個Multipart Upload事件的Object名稱。 類型：字符串 父節點：InitiateMultipartUploadResult
UploadId	惟一標示這次Multipart Upload事件的ID。 類型：字符串 父節點：InitiateMultipartUploadResult

 

細節分析：

1)  該操做計算認證簽名的時候，須要加「?uploads」到CanonicalizedResource中。

2)  初始化Multipart Upload請求，支持以下標準的HTTP請求頭：Cache-Control，Content- Disposition，Content-Encoding，Content-Type，Expires，以及以「x-oss-meta-」開頭的用戶自定義Headers。具體含義請參見PUT Object接口。

3)  初始化Multipart Upload請求，並不會影響已經存在的同名object。

4)  服務器收到初始化Multipart Upload請求後，會返回一個XML格式的請求體。該請求體內有三個元素：Bucket，Key和UploadID。請記錄下其中的UploadID，以用於後續的Multipart相關操做。

 

請求示例：

POST /multipart.data?uploads HTTP/1.1 Host: oss-example.oss.aliyuncs.com Date: Wed, 22 Feb 2012 08:32:21 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:/cluRFtRwMTZpC2hTj4F67AGdM4=

返回示例：

HTTP/1.1 200 OK Content-Length: 230 Server: AliyunOSS Connection: close x-oss-request-id: 42c25703-7503-fbd8-670a-bda01eaec618 Date: Wed, 22 Feb 2012 08:32:21 GMT Content-Type: application/xml   <?xml version="1.0" encoding="UTF-8"?> <InitiateMultipartUploadResult xmlns=」http://doc.oss.aliyuncs.com」>     <Bucket> multipart_upload</Bucket>     <Key>multipart.data</Key>     <UploadId>0004B9894A22E5B1888A1E29F8236E2D</UploadId> </InitiateMultipartUploadResult>

 

相關閱讀：

Ø  List Multipart Uploads

Ø  Abort Multipart Upload

Ø  Complete Multipart Upload

 

 

5.5.2                Upload Part

在初始化一個Multipart Upload以後，能夠根據指定的Object名和Upload ID來分塊（Part）上傳數據。每個上傳的Part都有一個標識它的號碼（part number，範圍是1~10,000）。對於同一個Upload ID，該號碼不但惟一標識這一塊數據，也標識了這塊數據在整個文件內的相對位置。若是你用同一個part號碼，上傳了新的數據，那麼OSS上已有的這個號碼的Part數據將被覆蓋。除了最後一塊Part之外，其餘的part最小爲5MB；最後一塊Part沒有大小限制。

 

請求語法：

PUT /ObjectName? partNumber=PartNumber&uploadid=UploadId HTTP/1.1 Host: BucketName.oss.aliyuncs.com Date: GMT Date Content-Length: Size Authorization: SignatureValue

 

細節分析：

1)  調用該接口上傳Part數據前，必須調用Initiate Multipart Upload接口，獲取一個OSS服務器頒發的Upload ID。

2)  Multipart Upload要求除最後一個Part之外，其餘的Part大小都要大於5MB。可是Upload Part接口並不會當即校驗上傳Part的大小（由於不知道是否爲最後一塊）；只有當Complete Multipart Upload的時候纔會校驗。

3)  OSS會將服務器端收到Part數據的MD5值放在ETag頭內返回給用戶。爲了保證數據在網絡傳輸過程當中不出現錯誤，強烈推薦用戶在收到OSS的返回請求後，用該MD5值驗證上傳數據的正確性。

4)  Part號碼的範圍是1~10000。若是超出這個範圍，OSS將返回InvalidArgument的錯誤碼。

 

請求示例:

PUT /multipart.data?partNumber=1&uploadId=0004B9895DBBB6EC98E36  HTTP/1.1 Host: oss-example.oss.aliyuncs.com Content-Length：6291456 Date: Wed, 22 Feb 2012 08:32:21 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:J/lICfXEvPmmSW86bBAfMmUmWjI=   [6291456 bytes data]

返回示例:

HTTP/1.1 200 OK Server: AliyunOSS Connection: close ETag: 7265F4D211B56873A381D321F586E4A9 x-oss-request-id: 3e6aba62-1eae-d246-6118-8ff42cd0c21a Date: Wed, 22 Feb 2012 08:32:21 GMT

 

相關閱讀：

Ø  Initiate Multipart Upload

Ø  List Parts

Ø  Complete Multipart Upload

 

 

5.5.3                Complete Multipart Upload

在將全部數據Part都上傳完成後，必須調用Complete Multipart Upload API來完成整個文件的Multipart Upload。在執行該操做時，用戶必須提供全部有效的數據Part的列表（包括part號碼和ETAG）；OSS收到用戶提交的Part列表後，會逐一驗證每一個數據Part的有效性。當全部的數據Part驗證經過後，OSS將把這些數據part組合成一個完整的Object。

 

請求語法：

POST /ObjectName?uploadId=UploadId HTTP/1.1 Host: BucketName.oss.aliyuncs.com Date: GMT Date Content-Length: Size Authorization: Signature   <CompleteMultipartUpload> <Part> <PartNumber>PartNumber</PartNumber> <ETag>ETag</ETag> </Part> ... </CompleteMultipartUpload>

 

請求元素(Request Elements)：

名稱	描述
CompleteMultipartUpload	保存Complete Multipart Upload請求內容的容器。 類型：容器 子節點：一個或多個Part元素 父節點：無
ETag	Part成功上傳後，OSS返回的ETag值。 類型：字符串 父節點：Part
Part	保存已經上傳Part信息的容器。 類型：容器 子節點：ETag, PartNumber 父節點：InitiateMultipartUploadResult
PartNumber	Part數目。 類型：整數 父節點：Part

 

響應元素(Response Elements)：

名稱	描述
Bucket	Bucket名稱。 類型：字符串 父節點：CompleteMultipartUploadResult
CompleteMultipartUploadResult	保存Complete Multipart Upload請求結果的容器。 類型：容器 子節點：Bucket, Key, ETag, Location 父節點：None
ETag	ETag (entity tag) 在每一個Object生成的時候被建立，用於標示一個Object的內容。Complete Multipart Upload請求建立的Object，ETag值是其內容的UUID。ETag值能夠用於檢查Object內容是否發生變化。. 類型：字符串 父節點：CompleteMultipartUploadResult
Location	新建立Object的URL。 類型：字符串 父節點：CompleteMultipartUploadResult
Key	新建立Object的名字。 類型：字符串 父節點：CompleteMultipartUploadResult

 

細節分析：

1)  Complete Multipart Upload時，會確認除最後一塊之外全部塊的大小都大於5MB，並檢查用戶提交的Partlist中的每個Part號碼和Etag。因此在上傳Part時，客戶端除了須要記錄Part號碼外，還須要記錄每次上傳Part成功後，服務器返回的ETag值。

2)  OSS處理Complete Multipart Upload請求時，會持續必定的時間。在這段時間內，若是客戶端和OSS之間的連接斷掉，OSS仍會繼續將請求作完。

3)  用戶提交的Part List中,Part號碼能夠是不連續的。例如第一塊的Part號碼是1；第二塊的Part號碼是5。

4)  OSS處理Complete Multipart Upload請求成功後，該Upload ID就會變成無效。

5)        同一個Object能夠同時擁有不一樣的Upload Id，當Complete一個Upload ID後，該Object的其餘Upload ID不受影響。

 

請求示例:

POST /multipart.data? uploadId=0004B9B2D2F7815C432C9057C03134D4  HTTP/1.1 Host: oss-example.oss.aliyuncs.com Content-Length: 1056 Date: Fri, 24 Feb 2012 10:19:18 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:8VwFhFUWmVecK6jQlHlXMK/zMT0=   <CompleteMultipartUpload> <Part> <PartNumber>1</PartNumber> <ETag>"3349DC700140D7F86A078484278075A9"</ETag> </Part> <Part> <PartNumber>5</PartNumber> <ETag>"8EFDA8BE206636A695359836FE0A0E0A"</ETag> </Part> <Part> <PartNumber>8</PartNumber> <ETag>"8C315065167132444177411FDA149B92"</ETag> </Part> </CompleteMultipartUpload>

返回示例:

HTTP/1.1 200 OK Server: AliyunOSS Content-Length: 329 Content-Type: Application/xml Connection: close x-oss-request-id: 594f0751-3b1e-168f-4501-4ac71d217d6e Date: Fri, 24 Feb 2012 10:19:18 GMT   <?xml version="1.0" encoding="UTF-8"?> <CompleteMultipartUploadResult xmlns=」http://doc.oss.aliyuncs.com」>     <Location>http://storage.aliyun-inc.com/multipart_upload/multipart.data</Location>     <Bucket>multipart_upload</Bucket>     <Key>multipart.data</Key>     <ETag>"B864DB6A936D376F9F8D3ED3BBE540DD-3"</ETag> </CompleteMultipartUploadResult>

 

相關閱讀：

Ø  Initiate Multipart Upload

Ø  List Parts

 

 

5.5.4                Abort Multipart Upload

該接口能夠根據用戶提供的Upload ID停止其對應的Multipart Upload事件。當一個Multipart Upload事件被停止後，就不能再使用這個Upload ID作任何操做，已經上傳的Part數據也會被刪除。

 

請求語法：

DELETE /ObjectName?uploadId=UploadId HTTP/1.1 Host: BucketName.oss.aliyuncs.com Date: GMT Date Authorization: Signature

 

細節分析：

1)  停止一個Multipart Upload事件時，若是其所屬的某些Part仍然在上傳，那麼此次停止操做將沒法刪除這些Part。因此若是存在併發訪問的狀況，爲了完全釋放OSS上的空間，須要調用幾回Abort Multipart Upload接口。

2)  若是輸入的Upload Id不存在，OSS會返回404錯誤，錯誤碼爲：NoSuchUpload。

 

請求示例:

Delete /multipart.data?partNumber=1&uploadId=0004B9895DBBB6EC98E  HTTP/1.1 Host: oss-example.oss.aliyuncs.com Date: Wed, 22 Feb 2012 08:32:21 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:J/lICfXEvPmmSW86bBAfMmUmWjI=

返回示例:

HTTP/1.1 204 Server: AliyunOSS Connection: close x-oss-request-id: 059a22ba-6ba9-daed-5f3a-e48027df344d Date: Wed, 22 Feb 2012 08:32:21 GMT

 

相關閱讀：

Ø  Initiate Multipart Upload

Ø  List Multipart Uploads

 

 

5.5.5                List Multipart Uploads

List Multipart Uploads能夠羅列出全部執行中的Multipart Upload事件，即已經被初始化的Multipart Upload可是未被Complete或者Abort的Multipart  Upload事件。OSS返回的羅列結果中最多會包含1000個Multipart Upload信息。若是想指定OSS返回羅列結果內Multipart Upload信息的數目，能夠在請求中添加max-uploads參數。另外，OSS返回羅列結果中的IsTruncated元素標明是否還有其餘的Multipart Upload。

 

請求語法：

Get /?uploads HTTP/1.1 Host: BucketName.oss.aliyuncs.com Date: GMT Date Authorization: Signature

 

請求參數：

名稱	描述
delimiter	是一個用於對Object名字進行分組的字符。全部名字包含指定的前綴且第一次出現delimiter字符之間的object做爲一組元素——CommonPrefixes。 類型：字符串
max-uploads	限定這次返回Multipart Uploads事件的最大數目，若是不設定，默認爲1000，max-keys取值不能大於1000。 類型：字符串
key-marker	與upload-id-marker參數一同使用來指定返回結果的起始位置。 l   若是upload-id-marker參數未設置，查詢結果中包含：全部Object名字的字典序大於key-marker參數值的Multipart事件。 l   若是upload-id-marker參數被設置，查詢結果中包含：全部Object名字的字典序大於key-marker參數值的Multipart事件和Object名字等於key-marker參數值，可是Upload ID比upload-id-marker參數值大的Multipart Uploads事件。 類型：字符串
prefix	限定返回的object key必須以prefix做爲前綴。注意使用prefix查詢時，返回的key中仍會包含prefix。 類型：字符串
upload-id-marker	與key-marker參數一同使用來指定返回結果的起始位置。 l   若是key-marker參數未設置，則OSS忽略upload-id-marker參數。 l   若是key-marker參數被設置，查詢結果中包含：全部Object名字的字典序大於key-marker參數值的Multipart事件和Object名字等於key-marker參數值，可是Upload ID比upload-id-marker參數值大的Multipart Uploads事件。 類型：字符串

 

響應元素(Response Elements)：

名稱	描述
ListMultipartUploadsResult	保存List Multipart Upload請求結果的容器。 類型：容器 子節點：Bucket, KeyMarker, UploadIdMarker, NextKeyMarker, NextUploadIdMarker, MasUploads, Delimiter, Prefix, CommonPrefixes, IsTruncated, Upload 父節點：None
Bucket	Bucket名稱。 類型：字符串 父節點：ListMultipartUploadsResult
KeyMarker	列表的起始Object位置。 類型：字符串 父節點：ListMultipartUploadsResult
UploadIdMarker	列表的起始UploadID位置。 類型：字符串 父節點：ListMultipartUploadsResult
NextKeyMarker	若是本次沒有返回所有結果，響應請求中將包含NextKeyMarker元素，用於標明接下來請求的KeyMarker值。 類型：字符串 父節點：ListMultipartUploadsResult
NextUploadMarker	若是本次沒有返回所有結果，響應請求中將包含NextUploadMarker元素，用於標明接下來請求的UploadMarker值。 類型：字符串 父節點：ListMultipartUploadsResult
MaxUploads	返回的最大Upload數目。 類型：整數 父節點：ListMultipartUploadsResult
IsTruncated	標明是否本次返回的Multipart Upload結果列表被截斷。「true」表示本次沒有返回所有結果；「false」表示本次已經返回了所有結果。 類型：枚舉字符串 有效值：false | true 默認值：false 父節點：ListMultipartUploadsResult
Upload	保存Multipart Upload事件信息的容器。 類型：容器 子節點：Key, UploadId, Initiated 父節點：ListMultipartUploadsResult
Key	初始化Multipart Upload事件的Object名字。 類型：字符串 父節點：Upload
UploadId	Multipart Upload事件的ID。 類型：字符串 父節點：Upload
Initiated	Multipart Upload事件初始化的時間. 類型：日期 父節點：Upload

 

細節分析：

1)  「max-uploads」參數最大值爲1000。

2)  在OSS的返回結果首先按照Object名字字典序升序排列；對於同一個Object，則按照時間序，升序排列。

3)  能夠靈活地使用prefix參數對bucket內的object進行分組管理（相似與文件夾的功能）。

4)  List Multipart Uploads請求支持5種請求參數： prefix，marker，delimiter，upload-id-marker和max-keys。經過這些參數的組合，能夠設定查詢Multipart Uploads事件的規則，得到指望的查詢結果。

 

請求示例:

Get /?uploads  HTTP/1.1 Host:oss-example. oss.aliyuncs.com Date: Thu, 23 Feb 2012 06:14:27 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:JX75CtQqsmBBz+dcivn7kwBMvOY=

返回示例:

HTTP/1.1 200 Server: AliyunOSS Connection: close Content-length: 1839 Content-type: application/xml x-oss-request-id: 58a41847-3d93-1905-20db-ba6f561ce67a Date: Thu, 23 Feb 2012 06:14:27 GMT   <?xml version="1.0" encoding="UTF-8"?> <ListMultipartUploadsResult xmlns=」http://doc.oss.aliyuncs.com」>     <Bucket>oss-example</Bucket>     <KeyMarker></KeyMarker>     <UploadIdMarker></UploadIdMarker>     <NextKeyMarker>oss.avi</NextKeyMarker>     <NextUploadIdMarker>0004B99B8E707874FC2D692FA5D77D3F</NextUploadIdMarker>     <Delimiter></Delimiter>     <Prefix></Prefix>     <MaxUploads>1000</MaxUploads>     <IsTruncated>false</IsTruncated>     <Upload>         <Key>multipart.data</Key>         <UploadId>0004B999EF518A1FE585B0C9360DC4C8</UploadId>         <Initiated>2012-02-23T04:18:23.000Z</Initiated>     </Upload>     <Upload>         <Key>multipart.data</Key>         <UploadId>0004B999EF5A239BB9138C6227D69F95</UploadId>         <Initiated>2012-02-23T04:18:23.000Z</Initiated>     </Upload>     <Upload>         <Key>oss.avi</Key>         <UploadId>0004B99B8E707874FC2D692FA5D77D3F</UploadId>         <Initiated>2012-02-23T06:14:27.000Z</Initiated>     </Upload> </ListMultipartUploadsResult>

 

相關閱讀：

Ø  Initiate Multipart Upload

Ø  List Parts

 

 

5.5.6                List Parts

List Parts命令能夠羅列出指定Upload ID所屬的全部已經上傳成功Part。

請求語法：

Get  /ObjectName?uploadId=UploadId HTTP/1.1 Host: BucketName.oss.aliyuncs.com Date: GMT Date Authorization: Signature

 

請求參數(Request Parameters)：

名稱	描述
uploadId	Multipart Upload事件的ID。 類型：字符串 默認值：無
max-parts	規定在OSS響應中的最大Part數目。 類型：整數 默認值：1,000
part-number-marker	指定List的起始位置，只有Part Number數目大於該參數的Part會被列出。 類型：整數 默認值：無

 

名稱	描述
uploadId	Upload ID identifying the multipart upload whose parts are being listed. Type: String Default: None
max-parts	Sets the maximum number of parts to return in the response body. Type: Integer Default: 1,000
part-number-marker	Specifies the part after which listing should begin. Only parts with higher part numbers will be listed. Type: Integer Default: None

 

響應元素(Response Elements)：

名稱	描述
ListPartsResult	保存List Part請求結果的容器。 類型：容器 子節點：Bucket, Key, UploadId, PartNumberMarker, NextPartNumberMarker, MaxParts, IsTruncated, Part 父節點：無
Bucket	Bucket名稱。 類型：字符串 父節點：ListPartsResult
Key	Object名稱。 類型：字符串 父節點：ListPartsResult
UploadId	Upload事件ID。 類型：字符串 父節點：ListPartsResult
PartNumberMarker	本次List結果的Part Number起始位置。 類型：整數 父節點：ListPartsResult
NextPartNumberMarker	若是本次沒有返回所有結果，響應請求中將包含NextPartNumberMarker元素，用於標明接下來請求的PartNumberMarker值。. 類型：整數 父節點：ListPartsResult
MaxParts	返回請求中最大的Part數目。 類型：整數 父節點：ListPartsResult
IsTruncated	標明是否本次返回的List Part結果列表被截斷。「true」表示本次沒有返回所有結果；「false」表示本次已經返回了所有結果。 類型：枚舉字符串 有效值：true | false 父節點：ListPartsResult
Part	保存Part信息的容器。 類型：字符串 子節點：PartNumber, LastModified, ETag, Size 父節點：ListPartsResult
PartNumber	標示Part的數字。 類型：整數 父節點：ListPartsResult.Part
LastModified	Part上傳的時間。 類型：日期 父節點：ListPartsResult.part
ETag	已上傳Part內容的ETag。 類型：字符串 父節點：ListPartsResult.Part
Size	已上傳Part大小。 類型：整數 父節點：ListPartsResult.Part

 

細節分析：

1)  List Parts支持max-parts和part-number-marker兩種請求參數。

2)   max-parts參數最大值爲1000；默認值也爲1000。

3)  在OSS的返回結果按照Part號碼升序排列。

4)  因爲網絡傳輸可能出錯，因此不推薦用List Part出來的結果（Part Number和ETag值）來生成最後Complete Multipart的Part列表。

 

請求示例:

Get /multipart.data?uploadId=0004B999EF5A239BB9138C6227D69F95  HTTP/1.1 Host: oss-example.oss.aliyuncs.com Date: Thu, 23 Feb 2012 07:13:28 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:4qOnUMc9UQWqkz8wDqD3lIsa9P8=

返回示例:

HTTP/1.1 200 Server: AliyunOSS Connection: close Content-length: 1221 Content-type: application/xml x-oss-request-id: 106452c8-10ff-812d-736e-c865294afc1c Date: Thu, 23 Feb 2012 07:13:28 GMT   <?xml version="1.0" encoding="UTF-8"?> <ListPartsResult xmlns=」http://doc.oss.aliyuncs.com」>     <Bucket>multipart_upload</Bucket>     <Key>multipart.data</Key>     <UploadId>0004B999EF5A239BB9138C6227D69F95</UploadId>     <NextPartNumberMarker>5</NextPartNumberMarker>     <MaxParts>1000</MaxParts>     <IsTruncated>false</IsTruncated>     <Part>         <PartNumber>1</PartNumber>         <LastModified>2012-02-23T07:01:34.000Z</LastModified>         <ETag>"3349DC700140D7F86A078484278075A9"</ETag>         <Size>6291456</Size>     </Part>     <Part>         <PartNumber>2</PartNumber>         <LastModified>2012-02-23T07:01:12.000Z</LastModified>         <ETag>"3349DC700140D7F86A078484278075A9"</ETag>         <Size>6291456</Size>     </Part>     <Part>         <PartNumber>5</PartNumber>         <LastModified>2012-02-23T07:02:03.000Z</LastModified>         <ETag>"7265F4D211B56873A381D321F586E4A9"</ETag>         <Size>1024</Size>     </Part> </ListPartsResult>

 

相關閱讀：

Ø  Initiate Multipart Upload

Ø  List Multipart Uploads

 

 

6. OSS的錯誤響應

當用戶訪問OSS出現錯誤時，OSS會返回給用戶相應的錯誤碼和錯誤信息，便於用戶定位問題，並作出適當的處理。

6.1.   OSS的錯誤響應格式

當用戶訪問OSS出錯時，OSS會返回給用戶一個合適的3xx，4xx或者5xx的HTTP狀態碼；以及一個application/xml格式的消息體。

錯誤響應的消息體例子：

<?xml version="1.0" ?> <Error xmlns=」http://doc.oss.aliyuncs.com」> <Code>            AccessDenied </Code> <Message>            Query-string authentication requires the Signature, Expires and OSSAccessKeyId parameters </Message> <RequestId>            1D842BC5425544BB </RequestId> <HostId>            oss.aliyuncs.com </HostId> </Error>

全部錯誤的消息體中都包括如下幾個元素：

n  Code：OSS返回給用戶的錯誤碼。

n  Message：OSS給出的詳細錯誤信息。

n  RequestId：用於惟一標識該次請求的UUID；當你沒法解決問題時，能夠憑這個RequestId來請求OSS開發工程師的幫助。

n  HostId：用於標識訪問的OSS集羣（目前統一爲oss.aliyuncs.com）

其餘特殊的錯誤信息元素請參照每一個請求的具體介紹。

 

 

6.2.   OSS的錯誤碼

OSS的錯誤碼列表以下：

錯誤碼	描述	HTTP狀態碼
AccessDenied	拒絕訪問	403
BucketAlreadyExists	Bucket已經存在	409
BucketNotEmpty	Bucket不爲空	409
EntityTooLarge	實體過大	400
EntityTooSmall	實體太小	400
FileGroupTooLarge	文件組過大	400
FilePartNotExist	文件Part不存在	400
FilePartStale	文件Part過期	400
InvalidArgument	參數格式錯誤	400
InvalidAccessKeyId	Access Key ID不存在	403
InvalidBucketName	無效的Bucket名字	400
InvalidDigest	無效的摘要	400
InvalidObjectName	無效的Object名字	400
InvalidPart	無效的Part	400
InvalidPartOrder	無效的part順序	400
InvalidTargetBucketForLogging	Logging操做中有無效的目標bucket	400
InternalError	OSS內部發生錯誤	500
MalformedXML	XML格式非法	400
MethodNotAllowed	不支持的方法	405
MissingArgument	缺乏參數	411
MissingContentLength	缺乏內容長度	411
NoSuchBucket	Bucket不存在	404
NoSuchKey	文件不存在	404
NoSuchUpload	Multipart Upload ID不存在	404
NotImplemented	沒法處理的方法	501
PreconditionFailed	預處理錯誤	412
RequestTimeTooSkewed	發起請求的時間和服務器時間超出15分鐘	403
RequestTimeout	請求超時	400
SignatureDoesNotMatch	簽名錯誤	403
TooManyBuckets	用戶的Bucket數目超過限制	400

 

 

 

6.3.   OSS不支持分塊傳輸編碼

HTTP協議有一種分塊傳輸編碼的機制(Chunked Transfer Encoding)，即一個HTTP消息能夠分紅多個部分進行傳輸。它對HTTP請求和HTTP響應都是適用的。出於安全的考慮，OSS不支持這種分塊傳輸編碼方式。若是OSS收到這種分塊傳輸編碼方式的請求，回直接返回HTTP錯誤碼：411。該錯誤碼在HTTP協議中的含義是：「The request must be chunked or have a content length」。

 

 

6.4.   OSS不支持的操做

若是試圖以OSS不支持的操做來訪問某個資源，返回405 Method Not Allowed錯誤。

 

錯誤請求示例：

abc / HTTP/1.1 Host:oss-example. oss.aliyuncs.com Date: date Authorization: signatureValue

 

返回示例：

x-oss-request-id: 2403382433A2EDA8 Allow: GET, DELETE, HEAD, PUT Content-Type: application/xml Transfer-Encoding: chunked Date: Thu, 31 Mar 2011 10:01:52 GMT Server: AliyunOSS   <?xml version="1.0" ?> <Error xmlns=」http://doc.oss.aliyuncs.com」> <Code>            MethodNotAllowed </Code> <Message>            The specified method is not allowed against this resource. </Message> <ResourceType>            BUCKET </ResourceType> <Method>            abc </Method> <RequestId>            2403382433A2EDA8 </RequestId> <HostId>            oss.aliyuncs.com </HostId> </Error>

注意：若是訪問的資源是 /bucket/， ResourceType應該是bucket，若是訪問的資源是 /bucket/object，ResourceType應該是object。

 

 

6.5.   OSS操做支持但參數不支持的操做

若是在OSS合法的操做中，添加了OSS不支持的參數（例如在PUT的時候，加入If-Modified-Since參數），OSS會返回501 Not Implemented錯誤

 

錯誤請求示例：

PUT /my-image.jpg HTTP/1.1 Host:oss-example. oss.aliyuncs.com Date: Wed, 28 May 2011 22:32:00 GMT If-Modified-Since: Wed, 06 Apr 2011 10:02:46 GMT

 

返回示例：

501 Not Implemented x-oss-request-id: 77E534EBF90372BE Content-Type: application/xml Transfer-Encoding: chunked Date: Thu, 28 Apr 2011 08:03:07 GMT Connection: close Server: AliyunOSS   <?xml version="1.0" ?> <Error xmlns=」http://doc.oss.aliyuncs.com」> <Code>            NotImplemented </Code> <Message>            A header you provided implies functionality that is not implemented. </Message> <Header>            If-Modified-Since </Header> <RequestId>            77E534EBF90372BE </RequestId> <HostId>            oss.aliyuncs.com </HostId> </Error>

 

 

 

^[1] 阿里雲主機經過內網域名訪問OSS，會擁有比訪問公網域名更快的響應時間、更高的傳輸速度；同時，上傳、下載流量都是免費的。

^[2] OSS提供Bucket訪問日誌的目的是方便bucket的擁有者理解和分析bucket的訪問行爲。OSS提供的Bucket訪問日誌不保證記錄下每一條訪問記錄。

^[3] OSS目前支持的子資源包括：acl，group，uploadId，partNumber，uploads，logging

[4] OSS目前支持的override查詢字符串包括：response-content-type, response-content-language,  response-expires,  reponse-cache-control, response-content-disposition,  response-content-encoding

 

 

 

 

 

 

 

 

 

 

 

1 基本概念介紹 1.1 存儲空間（Bucket） 存儲空間是您用於存儲對象（Object）的容器，全部的對象都必須隸屬於某個存儲空間。您能夠設置和修改存儲空間屬性用來控制地域、訪問權限、生命週期等，這些屬性設置直接做用於該存儲空間內全部對象，所以您能夠經過靈活建立不一樣的存儲空間來完成不一樣的管理功能。 同一個存儲空間的內部是扁平的，沒有文件系統的目錄等概念，全部的對象都直接隸屬於其對應的存儲空間。 每一個用戶能夠擁有多個存儲空間。 存儲空間的名稱在 OSS 範圍內必須是全局惟一的，一旦建立以後沒法修更名稱。 存儲空間內部的對象數目沒有限制。 存儲空間的命名規範以下： 只能包括小寫字母，數字和短橫線（-）。 必須以小寫字母或者數字開頭。 長度必須在3-63字節之間。 1.2 對象/文件（Object） 對象是 OSS 存儲數據的基本單元，也被稱爲 OSS 的文件。對象由元信息（Object Meta），用戶數據（Data）和文件名（Key）組成。對象由存儲空間內部惟一的 Key 來標識。對象元信息是一個鍵值對，表示了對象的一些屬性，好比最後修改時間、大小等信息，同時用戶也能夠在元信息中存儲一些自定義的信息。 根據不一樣的上傳方式，對象的大小限制是不同的。分片上傳 最大支持 48.8TB 的對象大小，其餘的上傳方式最大支持 5GB。 對象的生命週期是從上傳成功到被刪除爲止。在整個生命週期內，對象信息不可變動。重複上傳同名的對象會覆蓋以前的對象，所以，OSS 不支持修改文件的部份內容等操做。 OSS 提供了 追加上傳 功能，用戶可使用該功能不斷地在Object尾部追加寫入數據。   對象的命名規範以下： 使用UTF-8編碼。 長度必須在1-1023字節之間。 不能以「/」或者「\」字符開頭。 對象名稱須要區分大小寫。如無特殊說明，本文檔中的對象、文件稱謂等同於 Object。 1.3 Region（區域） Region 表示 OSS 的數據中心所在的區域，物理位置。用戶能夠根據費用、請求來源等綜合選擇數據存儲的 Region。通常來講，距離用戶更近的 Region 訪問速度更快。詳細請查看 OSS 已經開通的 Region。 Region是在建立 Bucket 的時候指定的，一旦指定以後就不容許更改，該 Bucket 下全部的 Object 都存儲在對應的數據中心，目前不支持 Object 級別的 Region 設置。 1.4 Endpoint（訪問域名） Endpoint 表示 OSS 對外服務的訪問域名。OSS 以 HTTP RESTful API 的形式對外提供服務，當訪問不一樣的 Region 的時候，須要不一樣的域名。經過內網和外網訪問同一個 Region 所須要的 Endpoint 也是不一樣的。例如杭州 Region 的外網 Endpoint 是 oss-cn-hangzhou.aliyuncs.com，內網 Endpoint 是 oss-cn-hangzhou-internal.aliyuncs.com。具體的內容請參見 各個 Region 對應的 Endpoint。 1.5 AccessKey（訪問密鑰） AccessKey，簡稱 AK，指的是訪問身份驗證中用到的 AccessKeyId 和AccessKeySecret。OSS 經過使用 AccessKeyId 和 AccessKeySecret 對稱加密的方法來驗證某個請求的發送者身份。AccessKeyId 用於標識用戶，AccessKeySecret 是用戶用於加密簽名字符串和 OSS 用來驗證簽名字符串的密鑰，其中 AccessKeySecret 必須保密。對於 OSS 來講，AccessKey 的來源有： Bucket 的擁有者申請的 AccessKey。 被 Bucket 的擁有者經過 RAM 受權給第三方請求者的 AccessKey。 被 Bucket 的擁有者經過 STS 受權給第三方請求者的 AccessKey。 更多 AccessKey 介紹請參見 訪問控制。 1.6 強一致性 Object 操做在 OSS 上具備原子性，操做要麼成功要麼失敗，不會存在有中間狀態的Object。OSS 保證用戶一旦上傳完成以後讀到的 Object 是完整的，OSS 不會返回給用戶一個部分上傳成功的 Object。 Object 操做在 OSS 上一樣具備強一致性，用戶一旦收到了一個上傳（PUT）成功的響應，該上傳的 Object 就已經當即可讀，而且數據的三份副本已經寫成功。不存在一種上傳的中間狀態，即 read-after-write 卻沒法讀取到數據。對於刪除操做也是同樣的，用戶刪除指定的 Object 成功以後，該 Object 當即變爲不存在。 強一致性方便了用戶架構設計，可使用跟傳統存儲設備一樣的邏輯來使用OSS，修改當即可見，無需考慮最終一致性帶來的各類問題。 1.7 OSS與文件系統的對比 OSS 是一個分佈式的對象存儲服務，提供的是一個 Key-Value 對形式的對象存儲服務。用戶能夠根據 Object 的名稱（Key）惟一的獲取該Object的內容。雖然用戶可使用相似 test1/test.jpg 的名字，可是這並不表示用戶的 Object 是保存在test1 目錄下面的。對於 OSS 來講，test1/test.jpg 僅僅只是一個字符串，和a.jpg 這種並無本質的區別。所以不一樣名稱的 Object 之間的訪問消耗的資源是相似的。 文件系統是一種典型的樹狀索引結構，一個名爲 test1/test.jpg 的文件，訪問過程須要先訪問到 test1 這個目錄，而後再在該目錄下查找名爲 test.jpg 的文件。所以文件系統能夠很輕易的支持文件夾的操做，好比重命名目錄、刪除目錄、移動目錄等，由於這些操做僅僅只是針對目錄節點的操做。這種組織結構也決定了文件系統訪問越深的目錄消耗的資源也越大，操做擁有不少文件的目錄也會很是慢。 對於 OSS 來講，能夠經過一些操做來模擬相似的功能，可是代價很是昂貴。好比重命名目錄，但願將 test1 目錄重命名成 test2，那麼 OSS 的實際操做是將全部以 test1/ 開頭的 Object 都從新複製成以 test2/ 開頭的 Object，這是一個很是消耗資源的操做。所以在使用 OSS 的時候要儘可能避免相似的操做。 OSS 保存的 Object 不支持修改（追加寫 Object 須要調用特定的接口，生成的 Object 也和正常上傳的 Object 類型上有差異）。用戶哪怕是僅僅須要修改一個字節也須要從新上傳整個 Object。而文件系統的文件支持修改，好比修改指定偏移位置的內容、截斷文件尾部等，這些特色也使得文件系統擁有普遍的適用性。但另一方面，OSS 能支持海量的用戶併發訪問，而文件系統會受限於單個設備的性能。 所以，將 OSS 映射爲文件系統是很是低效的，也是不建議的作法。若是必定要掛載成文件系統的話，建議儘可能只作寫新文件、刪除文件、讀取文件這幾種操做。使用 OSS 應該充分發揮其優勢，即海量數據處理能力，優先用來存儲海量的非結構化數據，好比圖片、視頻、文檔等。 1.8 OSS 術語表 英文 中文 Bucket 存儲空間 Object 對象或者文件 Endpoint OSS 訪問域名 Region 區域或者數據中心 AccessKey AccessKeyId 和 AccessKeySecret 的統稱，訪問密鑰 Put Object 簡單上傳 Post Object 表單上傳 Multipart Upload 分片上傳 Append Object 追加上傳 Get Object 簡單下載 Callback 回調 Object Meta 文件元信息。用來描述文件信息，例如長度，類型等 Data 文件數據 Key 文件名 ACL (Access Control List) 存儲空間或者文件的權限   Jessica程序猿  博客園