686      阿裏雲  技術社區[雲棲]

API調用方式__API使用手冊_歸檔存儲-阿裏雲

對歸檔存儲 API的接口調用是通過向歸檔存儲 API的服務端地址發送HTTP請求，並按照接口說明在請求中加入相應請求參數來完成的；根據請求的處理情況，係統會返回相應的處理結果。

通信結構

服務地址

歸檔存儲 API的服務接入地址為：

公網：[ RegionName ].oas.aliyuncs.com

內網：[ RegionName ].oas-internal.aliyuncs.com

其中，[ RegionName ]取值為: cn-hangzhou、cn-qingdao、cn-beijing、cn-hongkong等。

通信協議

按照HTTP/1.1協議進行通信。

字符編碼

請求及返回結果都使用UTF-8字符編碼進行編碼。

通信請求

請求方法

HTTP RESTful方法發送請求，這種方式下請求的資源由URI指定。

請求消息與格式

每個請求消息都必須包含請求行（Request-Line）和公共請求頭部（Common Request Headers），部分操作需要提供額外的請求頭部（Request Headers）和請求體（Request Body）。格式如下：

Request-Line
Common Request Headers
[ Request Headers ]
[ Request Body ]

請求行指定要執行的操作，格式參照 HTTP/1.1 協議 Request-Line。如：

PUT /vaults/[ VaultName ] HTTP/1.1

表示創建名稱為 VaultName 的 Vault。

請求行中的 URI 指定需要訪問的資源，各接口指定資源的方式是將接口示例中的字段替換成相應的資源標識即可。如 4.4.4 Job 任務狀態查詢的請求行：

GET /vaults/[ VaultId ]/jobs/[ JobId ] HTTP/1.1

[ VaultId ] 和 [ JobId ] 需要替換成實際相應的 Vault ID 和 Job ID。

請求行中的URI還可以附帶請求參數（Request Parameters），請求參數按照“參數名稱=參數值”的格式以“?”符號與URI分隔並緊跟在URI後麵，多個請求參數以“&”符號連接。例如4.1.3 獲取Vault列表，limit和marker是該操作可以附加的請求參數，組成的請求行可能如下所示：

GET /vaults?limit=1&marker=C83DE8B245184E28AEED6CF1CED915F2
HTTP/1.1

公共請求頭部是不論操作類型，每個請求消息都需要包含的一些頭部參數（詳細頭部參數列表見2.4.1）。

請求頭部是一些操作特定的頭部參數，比如4.2.1上傳 Archive 操作，x-oas-archive-description是該操作的請求頭部，指定Archive的描述信息。

公共請求頭部和請求頭部的格式參照 HTTP/1.1協議各Headers。

請求體則是請求需要提供的額外信息，如4.4.1初始化Job任務，請求需要提供Type等其他信息來指定Job的類型等。請求體的格式按照JSON的格式封裝。本文檔中的請求體示例為了便於用戶查看，做了格式化處理，實際是沒有換行、縮進等處理。

通信返回

返回消息與格式

調用 API 服務後返回數據采用統一格式，包括狀態行（Status-Line）、公共返回頭部（Common Response Headers），有些操作會提供額外的返回頭部（ResponseHeaders）和返回體（Response Body）。格式如下：

Status-Line
Common Response Headers
[ Response Headers ]
[ Response Body ]

狀態行格式參照HTTP/1.1協議Status-Line，返回的HTTP狀態碼2xx，代表調用成功；返回4xx或5xx的HTTP狀態碼代表調用失敗。

公共返回頭部是無論調用是否成功，都會返回的頭部參數（詳細參數列表見2.4.2）。

返回頭部是不同類型的操作，可能會額外返回的頭部參數。如4.1.1創建Vault操作返回頭部包括Location和x-oas-vault-id，分別指定新創建Vault的URI和Vault ID。公共返回頭部和返回頭部的格式參照HTTP/1.1協議各Headers。

返回體是操作返回的額外信息。如獲取Vault列表中，緊跟在頭部參數後麵就是返回的Vault列表信息，返回體按照JSON的格式封裝。本文檔的返回體示例為了便於用戶查看，做了格式化處理，實際返回結果是沒有進行換行、縮進等處理的。

成功結果

JSON示例：

{
    "ArchiveId":"[ ArchiveId ]",
    /* 其他信息*/
}

錯誤結果

調用接口出錯後，HTTP請求會返回一個4xx或5xx的HTTP狀態碼，且不會提供返回頭部，但是在返回體中會提供具體的錯誤代碼及錯誤信息，調用方也可以根據附表<錯誤代碼表>來定位錯誤原因。在調用方找不到錯誤原因，可以聯係阿裏雲客服，並提供公共返回頭部的x-oas-request-id和公共請求頭部Host字段，以便我們盡快幫您解決問題。

JSON示例：

{
    "code": "UnsupportedOperation",
    "message": "The specified action is not supported.",
    "type": "client"
}

公共頭部參數

公共請求頭部

公共請求頭部是指每個接口都需要使用到的頭部參數。

示例：

Host: cn-hangzhou.oas.aliyuncs.com
Date: Tue, 25 Mar 2014 12:00:00 GMT
x-oas-archive-description: MyArchive
Authorization: SignatureValue
x-oas-version: 2014-01-01

公共返回頭部

用戶發送的每次接口調用請求，無論成功與否，係統都會返回一些固定的頭部參數，其中最重要的是x-oas-request-id，它對各個請求都是唯一存在的。

示例：

x-oas-request-id: [ RequestId ]
Date: Tue, 25 Mar 2014 12:00:00 GMT

校驗碼計算

歸檔存儲的校驗碼頭部參數有兩個：x-oas-content-etag和x-oas-tree-etag，其中x-oas-content-etag是針對上傳請求的請求體用md5計算得出的校驗碼，x-oas-tree-etag是針對上傳請求的請求體用tree-hash算法計算得出的校驗碼。

為了確保上傳數據的一致性，歸檔存儲要求用戶在上傳文檔時，無論是單個文檔上傳方式還是Multipart Upload上傳方式，都必須包含上傳數據的校驗碼。歸檔存儲收到數據以後，會計算校驗碼，並與用戶提供的校驗碼進行比對。如果不一致，會返回錯誤，該請求失敗。同樣用戶在下載Archive時，歸檔存儲也會返回相應的校驗碼，供用戶校驗下載數據是否完整。

本節2.5.1、2.5.2用來描述x-oas-content-etag和x-oas-tree-etag兩種校驗碼的設置，2.5.3描述計算x-oas-tree-etag使用到的tree-hash算法，2.5.4描述下載數據時x-oas-tree-etag校驗碼的使用規則。

x-oas-content-etag校驗碼

x-oas-content-etag是通過計算待上傳數據的MD5，並將該MD5值所有小寫字母轉換為大寫字母的結果。如某個數據的MD5值是c011021548ef1855dd4dd15b8df79463，那麼用戶上傳時的x-oas-content-etag校驗碼為C011021548EF1855DD4DD15B8DF79463。

有兩個接口需要在請求頭部中加入x-oas-content-etag請求頭部，請分別參見4.2.1上傳Archive接口與4.3.4Part上傳接口。

x-oas-tree-etag校驗碼

x-oas-tree-etag是通過對上傳或接收數據進行tree-hash算法（請參見2.5.3 tree-hash算法說明）計算出的校驗碼。

有四個接口會使用到x-oas-tree-etag參數，其中上傳Archive（參見4.2.1）屬於單文件上傳接口，Part上傳(參見4.3.4)、Part合並(參見4.3.6)兩個接口屬於Multipart Upload上傳接口，Job Output下載接口（4.4.2）屬於下載類接口。

下麵分別描述單文檔上傳接口，Multipart Upload上傳接口，Job Output下載三個場景對x-oas-tree-etag的用法。

單文檔上傳方式

用戶在調用單文檔上傳接口之前需要對上傳的文檔進行tree-hash算法計算tree-etag校驗碼。如某個文檔的tree-etag校驗碼為26093833F5438BD1F2F34C731A0F90DE，它便是這個單文檔的x-oas-tree-etag。

Multipart Upload上傳方式

Multipart Upload方式在Part 上傳與Part 合並時都需要提供x-oas-tree-etag頭部參數。

Part上傳時x-oas-tree-etag的計算方法是取該Part對應數據範圍，做tree-hash算法計算得到的值。

在所有Part上傳完成後，用戶需要發起Part合並請求，此時用戶提交請求的x-oas-tree-etag頭部可以通過對整個上傳數據做 tree-hash 算法計算得出，也可以複用已上傳Part的x-oas-tree-etag校驗值，省去tree-hash算法(參見2.5.3)中計算每個1MB數據的tree-etag值的步驟，直接把每個Part的x-oas-tree-etag值作為葉子節點，再按照tree-hash算法的步驟2、步驟3，最終得到整個Archive的tree-hash算法根值。

示例：

假設一個149903360字節的文件，用戶以67108864為Part 大小上傳，如下圖所示：

第一個段上傳Archive的0-67108863字節，用tree-hash算法得到該段的x-oas-tree-etag校驗碼為：

F60F379B33C234F69FA4F79254650F65

第二個段上傳Archive的67108864-134217727 字節，用tree-hash算法得到該段的x-oas-tree-etag校驗碼為：

9D739013ABAE399B173B3C3415BDC69A

第三個段上傳Archive的134217728-149903359字節，用tree-hash算法得到該段的x-oas-tree-etag校驗碼為：

F9C22EBEA613C03AF231187B85BD3D30

合並時的x-oas-tree-etag校驗碼計算：

1. 按字節順序排列已上傳Part的x-oas-tree-etag校驗碼，作為tree-etag樹的葉子節點：

   F60F379B33C234F69FA4F79254650F65

   9D739013ABAE399B173B3C3415BDC69A

   F9C22EBEA613C03AF231187B85BD3D30

2. 按照tree-hash算法步驟2、步驟3計算出整個Archive的x-oas-tree-etag校驗碼：

   93C106A8937AC115BD21A63FE9114B1。

Job Output下載

當用戶調用Job Output下載接口時，如果用戶遵守tree-hash樹對齊規則（具體規則請參見2.5.4 下載數據時x-oas-tree-etag校驗碼的使用），歸檔存儲會在返回頭部中設置一個x-oas-tree-etag參數，該參數是歸檔存儲用tree-hash算法對返回數據計算出的校驗碼。用戶可以使用該校驗碼確認所接收到的數據與歸檔存儲的數據是否一致。

tree-hash算法

x-oas-tree-etag是通過對數據進行tree-hash算法計算得出的校驗值，它的具體操作步驟如下：

1. 對數據的每個1MB塊，計算它的md5值，並轉換為大寫。隻有數據的最後一個塊可以小於1MB。例如，上傳或者下載6.5MB的數據，則需要計算該數據的前6個1MB塊的md5值，及最後的0.5MB數據md5。這7個md5值轉大寫後，就構成了tree-hash算法的葉子節點。

2. 構建父節點。

   a. 依次連接兩個連續子節點的值形成一個字符串，對這個字符串作md5計算，並且轉大寫。這個值就是兩個子節點的父節點。

   b. 最後如果隻剩一個子節點，則它的父節點就是自身。

3. 重複步驟2，直到得到一個根節點為止。這個根節點就是待上傳或者下載數據的x-oas-tree-etag值。

舉例如下圖所示：

1. 假設有份數據6.5MB，分別計算它的前6個1MB塊的md5值，及最後一個0.5MB的md5值，按順序依次為：

   1ca30cd59f0b566f9ef3a8208679585e

   e07910a06a086c83ba41827aa00b26ed

   76f556302c49d8f6503a7e60b2ed1d7d

   7a3b8c43b0791ba6ce01f5696fd36f13

   65487827c964185d8929fa30bf11df18

   2c7282bbca9abc9d446e02b8adee9563

   46a5e231e4581f5defd12e8688da6377

   轉大寫後的結果為：

   H節點值1CA30CD59F0B566F9EF3A8208679585E

   I節點值E07910A06A086C83BA41827AA00B26ED

   J節點值76F556302C49D8F6503A7E60B2ED1D7D

   K節點值7A3B8C43B0791BA6CE01F5696FD36F13

   L節點值65487827C964185D8929FA30BF11DF18

   M節點值2C7282BBCA9ABC9D446E02B8ADEE9563

   N節點值46A5E231E4581F5DEFD12E8688DA6377

2. 構建父節點。

   a. 首先計算節點D的值，連接H和I的值形成一個字符串“1CA30CD59F0B566F9EF3A8208679585EE07910A06A086C83BA41827AA00B26ED”，對該字符串做md5計算得到 85786098ca1ffde6e267fa131de97bce， 將這個結果轉大寫就可以得到

   H, I的父節點D的值：85786098CA1FFDE6E267FA131DE97BCE。

   依此類推，兩兩連接，得到

   J, K的父節點E的值：B15B5E7BDDB12E28B1AF9711591B260B，
   L, M的父節點F的值：6CE4D37E18F3642B1E9D1CF2D2532D86。
   最後剩下的單個節點N， 父節點G和N相同：46A5E231E4581F5DEFD12E8688DA6377。

   b. 將D、E、F、G 作為子節點，重複操作 a，計算相應的父節點：

   D, E的父節點B的值：6C9924508699E38F6F898ECCE4F64F9B，
   F, G的父節點C的值：687DC906A777E986DD792FD469A3CC65。

   c. 將B, C作為子節點，按照 a 的方法，算出最終根節點A的值：26093833F5438BD1F2F34C731A0F90DE

3. 通過步驟2，最終計算得到tree-hash樹根節點的值26093833F5438BD1F2F34C731A0F90DE，這個值就是待上傳或者下載數據的x-oas-tree-etag值。

下載時x-oas-tree-etag校驗碼的使用

當用戶創建Job取回Archive時，可以選擇要取回的Archive範圍。同樣，當用戶下載這個job時，也可以選擇要下載的Job範圍。用戶在下載Job能否得到歸檔存儲服務端返回x-oas-tree-etag校驗碼，取決於兩個範圍（用戶創建Job指定的Archive範圍與下載Job時指定的Job範圍）是否遵守了兆字節對齊、tree-hash樹對齊。所謂兆字節對齊與tree-hash樹對齊的定義如下：

如果在創建 Job請求中未指定要取回的範圍，並且在Job下載請求中下載整個檔案。
如果在創建Job請求中未指定要取回的範圍，並且在Job下載請求中指定要下載的範圍以tree-hash樹對齊。
如果在創建Job請求中指定要取回的範圍以tree-hash樹對齊，並且在Job下載請求中下載整個Job。
如果在創建Job請求中指定要取回的範圍以tree-hash樹對齊，並且在Job下載請求中指定要下載的範圍以tree-hash樹對齊。