954
REST API
以下幾部分詳細介紹 NOS Open API 的定義：前三章定義通用請求頭、響應頭、錯誤碼；第四 章定義了桶相關操作 API；第五章定義了對象相關的操作 API；第六章定義了大對象分塊上傳 相關的操作 API；
通用請求頭
| Header | 描述 | 是否必須 |
|---|---|---|
| Authorization | 認證信息 類型：字符串 默認：無 |
Yes |
| Content-Length | RFC2616所定義的請求長度 類型：字符串 默認：無 |
Conditional |
| Content-Type | 文件的類型 類型：字符串 默認：無 |
No |
| Content-MD5 | HTTP BODY MD5值base64編碼後的值，與md5sum結果一致，無效的Content-MD5將返回錯誤：InvalidDegest 類型：字符串 示例：fbacf535f27731c9771645a39863328 默認：無 |
No |
| Date | 請求的時間戳 類型：字符串，格式必須符合RFC1123的日期格式 示例：Wed, 01 Mar 2012 12:00:00 GMT 默認：無 |
Yes |
| Host | 請求資源的主機名，通常采用虛擬機風格描述 類型：字符串 示例：BucketName.nos-eastchina1.126.net 默認：無 |
Yes |
| x-nos-entity-type | 接口返回的格式，當前支持 xml 和 json 兩種格式 類型：字符串 示例：有效取值：json、xml 默認：xml |
No |
通用響應頭
| Header | 描述 |
|---|---|
| Content-Length | 響應體的字節數 類型：字符串 默認：無 |
| Connection | close 默認：無 |
| Date | 響應的時間戳 類型：字符串 默認：無 |
| ETag | HTTP Entity Tag，代表對象的哈希值，反應對象內容的更改情況。(RFC2616) 類型：字符串 |
| Server | 響應的服務器名稱 類型： 字符串 |
| x-nos-request-id | 唯一定位一個請求的 ID 號，主要用於某些情況下錯誤定位 類型：字符串 |
錯誤碼定義
| 錯誤碼 | HTTP狀態碼 | 描述 |
|---|---|---|
| AccessDenied | 403 Forbidden | 權限錯誤，拒絕訪問 |
| BadDigest | 400 Bad Request | 提供的MD5值與服務器收到的二進製內容不匹配 |
| BucketAlreadyExist | 409 Conflict | 創建桶時，桶名已存在 |
| BucketAlreadyOwnedByYou | 409 Conflict | 創建桶時，該桶已經屬於你，重複創建了 |
| BucketNotEmpty | 409 Conflict | 嚐試刪的桶非空 |
| EntityTooSmall | 400 Bad Request | 提交的請求小於允許的對象的最小值 |
| EntityTooLarge | 400 Bad Request | 提交的請求大於允許的對象的最大值 |
| IllegalVersioningConfigurationException | 400 Bad Request | 版本號配置無效 |
| IncompleteBody | 400 Bad Request | 上傳的數據量小於 HTTP 頭中的Content-Length |
| InternalError | 500 Internal Server Error | 服務器內部錯誤，請重試 |
| InvalidAccessKeyId | 403 Forbidden | AccessKey 找不到匹配的記錄 |
| InvalidArgument | 400 Bad Request | 無效參數 |
| InvalidBucketName | 400 Bad Request | 無效桶名稱 |
| InvalidDigest | 400 Bad Request | 不是有效的 Content-MD5 |
| InvalidPart | 400 Bad Request | 無效的上傳塊 |
| InvalidPartOrder | 400 Bad Request | 上傳塊的順序有錯誤 |
| InvalidRange | 416 Requested Range Not Satisfiable | 請求的 Range 不合法 |
| InvalidRequest | 400 Bad Request | 非法請求 |
| InvalidStorageClass | 400 Bad Request | 無效的存儲級別 |
| KeyTooLong | 400 Bad Request | Object Key 長度太長 |
| MalformedXML | 400 Bad Request | XML 格式錯誤 |
| MetadataTooLarge | 400 Bad Request | 元數據過大 |
| MethodNotAllowed | 405 Method Not Allowed | 請求的 HTTP Method 不允許訪問 |
| MissingContentLength | 411 Length Required | 缺少 HTTP Header Content-Length |
| MissingRequestBodyError | 400 Bad Request | 缺少請求體 |
| NoSuchBucket | 404 Not Found | 請求的桶不存在 |
| NoSuchKey | 404 Not Found | 沒有這個key |
| NoSuchUpload | 404 Not Found | 對應的分塊上傳不存在 |
| NoSuchVersion | 400 Bad Request | 沒有這個版本號 |
| NotImplemented | 501 Not Implemented | 該項功能尚未實現 |
| RequestTimeout | 400 Bad Request | 請求超時 |
| RequestTimeTooSkewed | 403 Forbidden | 請求時間戳和服務器時間戳差距過大 |
| SignatureDoesNotMatch | 403 Forbidden | 請求的簽名與服務器計算的簽名不符 |
| ServiceUnavailable | 503 Service Unavailable | 服務不可用 |
| TooManyBuckets | 400 Bad Request | 創建了過多的桶 |
錯誤響應格式
發生錯誤時，服務端的響應包括
- 相應的 HTTP 3xx，4xx，5xx 狀態碼（HTTP Status Code）
- Content-Type:application/xml
- XML 格式的消息體
下麵是一個 XML 格式消息體的例子
<?xml version="1.0" encoding="UTF-8"?>
<Error>
<Code>NoSuchKey</Code>
<Message>The resource you requested does not exist</Message>
<Resource>/myBucket/1.jpg</Resource>
<RequestId>123456</Request>
</Error>
下麵這個表格定義了錯誤響應的 XML 元素
| 錯誤碼 | HTTP 狀態碼 |
|---|---|
| Code | 錯誤代碼，唯一標識了一種類型的錯誤。 類型：字符串 父節點：Error |
| Error | 錯誤信息元素。 類型：容器 父節點：無 |
| Message | 父節點：Error |
| RequestId | 該錯誤對應的請求 ID 號，請求號主要用於定位某些異常問題 類型：字符串 父節點：Error |
| Resource | 包含了 Bucket 或 Object 的請求資源描述符。 類型：字符串 父節點：Error |
如http請求頭部中製定 x-nos-entity-type: json ,則返回 JSON 格式消息體，示例如下
{
"Error":{
"Code": "NoSuchKey",
"Message": "The resource you requested does not exist",
"Resource": "/myBucket/1.jpg",
"RequestId": "123456"
}
}
文檔約定
語法: 接口語法描述，使用 ${var} 的類 shell 語法表示變量。
請求參數: HTTP 請求 URL 參數說明，參數列表以 ? 開始，多個參數之間以 & 隔開。
請求頭: HTTP Reqeust Header 說明，每個接口特有的請求頭在接口定義中給出，通用的請求頭請參閱3.1節。
請求元素: HTTP PUT/POST 請求的 entity-body 中的 xml element 說明，通常比較多的內容用請求參數不友好，需要用 entity 來請求。
響應頭: HTTP Response Header 說明。
響應元素: 響應的 entity-body 中的 xml element 說明。
RFC: 文檔中備注的 RFC 語義參考 https://www.w3.org/Protocols/ 對 HTTP 相關 RFC 的解釋。
最後更新：2017-01-03 10:48:54