阿里云-歸檔存儲-API手冊-D

1、歸檔存儲API使用手冊移動推送/OpenAPI文檔移動推送/OpenAPI文檔 PAGE 55 PAGE 55API使用手冊歡迎使用阿里云歸檔存儲。歸檔存儲作為阿里云數(shù)據(jù)存儲服務(wù)體系的一部分，提供了極低成本的數(shù)據(jù)存儲服務(wù)。適合各種離線數(shù)據(jù)，包括但不局限于數(shù)字媒體、企業(yè)歸檔資料、科學(xué)實驗數(shù)據(jù)、個人備份等。用戶可以將數(shù) 據(jù)進行幾個月、幾年甚至幾十年的長時間存儲。同時不需要任何基礎(chǔ)設(shè)施的投入，即可擁有無限擴容、可選擇 地域的低成本數(shù)據(jù)歸檔方案，也免去了后續(xù)數(shù)據(jù)的管理維護成本。 需要注意的是，存放于歸檔存儲的數(shù)據(jù)大部分時間會處于休眠狀態(tài)，而對數(shù)據(jù)的喚醒操作需要消耗一些時間和資源，因此如果您對數(shù)據(jù)長期穩(wěn)

2、定存儲 的需求較高，而對數(shù)據(jù)的訪問和讀取速度要求較低的話，歸檔存儲會是一個理想的選擇。 用戶可以使用本文檔介紹的API對歸檔存儲進行相關(guān)操作。在使用這些接口前，請確保已充分了解歸檔存儲產(chǎn)品說明、使用協(xié)議和收 費方式。若要了解更多相關(guān)信息，請訪問阿里云歸檔存儲官方網(wǎng)站 HYPERLINK /product/oas /product/oas。基本概念阿里云歸檔存儲的數(shù)據(jù)模型，由Vault（目錄）和Archive（文檔）組成。Archive在歸檔存儲中，用戶操作的基本數(shù)據(jù)單元是Archive，它需要包含在Vault（1.1.2）中。Archive可以是任意類 型的數(shù)據(jù)。上傳Archive（4.2.1

3、）時，文檔大小限制在6GB；如果文檔大小超出6GB，請使用Multipart Upload（1.1.4）方式。Archive包含ArchiveID、Description和Data等Data信息，其中ArchiveID是，Description是用戶對該Archive的描 述，Data是ArchiveArchive目前僅支持通過API進行操作。VaultArchive的目錄，也是計費、權(quán)限控制等功能的管理單位。Vault名稱在每 個用戶的每個Region（1.1.3）下唯一，每個用戶在每個Region最多可以創(chuàng)建10個Vault，Vault不支持嵌套。 每個Vault里可以包含任意數(shù)量的Arc

4、hive。Vault可以通過阿里云管理控制臺、API兩種方式進行創(chuàng)建、刪除等 操作。Vault的命名規(guī)范：只能包含小寫字母、數(shù)字、下劃線（_）、短橫線（-）；必須以小寫字母或者數(shù)字開頭和結(jié)尾；3-63Region專有網(wǎng)絡(luò) VPC/API使用手冊專有網(wǎng)絡(luò) VPC/API使用手冊Region是歸檔存儲集群的標識。各Region間的操作相互獨立。當前可用Region列表參見2.1.1。MultipartUploadMultipart Upload是把單個文檔分段上傳的方式，每段稱之為Part（1.1.5），目的是為了便于用戶上傳較大的文檔。使用Multipart Upload最大可以上傳10000*

5、4GB的文檔。不僅如此，多段上傳還支持獨立、任意順序、甚至并行上傳這些段。如果某段上傳失敗，只需要重新上傳該段即可。我們建議用戶在上傳大于100MB的文檔 時使用這種方式。 該上傳操作是異步方式，用戶需要首先新建Multipart Upload任務(wù)，指定每次需要上傳的Part字節(jié)長度，該長度值必須能夠被1MB整除，且介于32MB到4096MB之間。任務(wù)啟動成功后，歸檔存儲會 為該任務(wù)分配唯一的Upload ID，用戶需要使用該ID作為標識完成后續(xù)Part的上傳與合并。需要注意的是該任務(wù)自創(chuàng)建起24小時后，會自動失效。Part啟動MultipartUpload任務(wù)成功以后，單獨上傳的某個范圍內(nèi)的

6、文檔數(shù)據(jù)稱為Part。用戶上傳時需要指定Part在文檔中所屬的范圍。當所有Part都上傳成功以后，用戶還需要主動發(fā)起一次Part合并請求（4.3.6），才 能將上傳的數(shù)據(jù)完整地提交到歸檔存儲，否則任務(wù)創(chuàng)建超出24小時以后，用戶在該任務(wù)中上傳的數(shù)據(jù)將會丟失。Job歸檔存儲的Vault/Archive的內(nèi)容提取為異步操作，用戶需要首先提交指定類型的Job完成對數(shù)據(jù)的喚醒，然 后通過查詢Job狀態(tài)來確認Job是否完成。在正常情況下，任務(wù)會在4小時內(nèi)完成。Job完成以后，就可以獲取 Job Output。 Job類型可以是inventory-retrieval或archive-retrieval。前者

7、獲取到的Job Output是Job指定Vault的Archive列表信息，后者則是Job指定Archive的數(shù)據(jù)內(nèi)容。注意inventory-retrieval類型Job獲取到的Archive列表信息是由系統(tǒng)每天定期掃描生成的信息，不是實時數(shù)據(jù)。這兩種Job類型為方便阿里云用戶在歸檔存儲產(chǎn)品與OSS產(chǎn)品 之間實現(xiàn)數(shù)據(jù)歸檔、提檔功能，并幫助用戶實現(xiàn)無中轉(zhuǎn)方式的跨產(chǎn)品數(shù)據(jù)傳輸。pull-from-oss類型的Job用于 將用戶在OSS產(chǎn)品上的Object歸檔到歸檔存儲產(chǎn)品。 push-to-oss類型的Job用于將用戶在歸檔存儲產(chǎn)品上的Archive，提檔到OSS產(chǎn)品。 這兩種類型的Job依賴用

8、戶對歸檔存儲產(chǎn)品授予用戶OSS訪問權(quán)限。AccessKeyID、AccessKeySecret歸檔存儲會對每個訪問的請求進行身份驗證，請求中需要包含簽名（Signature）信息。歸檔存儲通過使用AccessKeyID和AccessKeySecret進行對稱加密的方法來驗證請求的發(fā)送者身份。AccessKeyID和Access Key Secret由阿里云官方頒發(fā)給訪問者（可以通過阿里云官方網(wǎng)站申請和管理），其中Access Key ID用于標識訪問者的身份；Access Key Secret是用于加密簽名字符串和服務(wù)器端驗證簽名字符串的密鑰，請嚴格保密，請勿泄露給第三方。ContentEta

9、g、TreeEtag歸檔存儲會對上傳的單文檔或者文檔分段，進行ContentEtag和TreeEtag兩種方式的數(shù)據(jù)校驗。ContentEtag是對數(shù)據(jù)進行md5sum校驗的數(shù)值，TreeEtag是對數(shù)據(jù)按照tree-hash算法校驗的數(shù)值（tree-hash算法參考：歸檔存儲 API調(diào)用方式-2.5.2 x-oas-tree-etag校驗碼）。功能簡介Vault操作歸檔存儲目前支持Vault創(chuàng)建（4.1.1）、刪除（4.1.2）、單個Vault信息查詢（4.1.3）以及Vault列表查詢（4.1.4），需要注意的是：如果Vault中包含有Archive，刪除操作會失敗；Vault列表查詢不支

10、持跨Region操作，同一請求只能獲取單個Region下用戶的Vault列表；用戶獲取Vault統(tǒng)計信息時，該信息不是實時更新。返回消息中Last Inventory（最后統(tǒng)計時間）的標識，反映了該信息的最后統(tǒng)計時間，信息更新來自歸檔存儲系統(tǒng)定期掃描統(tǒng)計或者由用戶主動發(fā)起的inventory-retrieval類型Job；Vault創(chuàng)建操作會返回Vault ID，其他的Vault操作都需要使用該ID來完成。Archive操作Archive操作包括上傳（4.2.1）和刪除（4.2.2）。Archive上傳成功以后，歸檔存儲會返回唯一的Archive ID，刪除操作需要使用該Archive ID。

11、MultipartUpload操作Multipart Upload操作包括任務(wù)初始化（4.3.1）、刪除（4.3.3）、任務(wù)列表查詢（4.3.2）。初始化操作成功以后會啟動一個多段上傳的任務(wù)并返回Upload ID，后續(xù)的Part上傳（4.3.4）、已上傳完成的Part列表查詢（4.3.5）以及Part合并操作（4.3.6）都需要指定該Upload ID。用戶可以通過Multipart Upload刪除操作（4.3.3）主動取消相應(yīng)Archive的多段上傳；多個Multipart Upload任務(wù)可以通過任務(wù)列表查詢（4.3.2）來獲取任務(wù)信息。任務(wù)的刪除和任務(wù)列表查詢同樣也需要使用初始化成功

12、返回的Upload ID進行。Job操作Job操作包括Job初始化（4.4.1）、Job Output下載、Job列表查詢以及Job狀態(tài)查詢。Job初始化成功以后會創(chuàng)建指定類型的Job，開始數(shù)據(jù)準備并返回Job ID。準備的過程中，用戶可以使用Job狀態(tài)查詢（4.4.4）來查看Job的狀態(tài)，待Job完成后使用Job Output下載（4.4.2）來獲取所需的數(shù)據(jù)。正在進行的或近期完成的Job操作可以通過Job列表查詢（4.4.3）來查看。后三個Job操作都需要指定初始化Job成功后返回的Job ID。對歸檔存儲 API的接口調(diào)用是通過向歸檔存儲 API的服務(wù)端地址發(fā)送HTTP請求，并按照接口說

13、明在請求中加入相應(yīng)請求參數(shù)來完成的；根據(jù)請求的處理情況，系統(tǒng)會返回相應(yīng)的處理結(jié)果。操作審計/API參考手冊操作審計/API參考手冊通信結(jié)構(gòu)服務(wù)地址歸檔存儲 API的服務(wù)接入地址為：公網(wǎng)： RegionName .內(nèi)網(wǎng)： RegionName .其中， RegionName 取值為: cn-hangzhou、cn-qingdao、cn-beijing、cn-hongkong等。通信協(xié)議按照HTTP/1.1協(xié)議進行通信。字符編碼請求及返回結(jié)果都使用UTF-8字符編碼進行編碼。通信請求請求方法HTTP RESTful方法發(fā)送請求，這種方式下請求的資源由URI指定。請求消息與格式Request-Lin

14、eCommon Request Headers Request Headers Request Body Request-LineCommon Request Headers Request Headers Request Body 請求行指定要執(zhí)行的操作，格式參照 HTTP/1.1 協(xié)議 Request-Line。如：PUT /vaults/ VaultName HTTP/1.1PUT /vaults/ VaultName HTTP/1.1表示創(chuàng)建名稱為 VaultName 的 Vault。請求行中的 URI 指定需要訪問的資源，各接口指定資源的方式是將接口示例中的字段替換成相應(yīng)的資源標識即

15、可。如 4.4.4 Job 任務(wù)狀態(tài)查詢的請求行：GET /vaults/ VaultId /jobs/ JobId HTTP/1.1GET /vaults/ VaultId /jobs/ JobId HTTP/1.1 VaultId 和 JobId 需要替換成實際相應(yīng)的 Vault ID 和 Job ID。請求行中的URI還可以附帶請求參數(shù)（Request Parameters），請求參數(shù)按照參數(shù)名稱=參數(shù)值的格式以GET /vaults?limit=1&marker=C83DE8B245184E28AEED6CF1CED915F2 HTTP/1.1?符號與URI分隔并緊跟在URI后面，多個

16、請求參數(shù)以&符號連接。例如4.1.3 獲取Vault列表，limit和GET /vaults?limit=1&marker=C83DE8B245184E28AEED6CF1CED915F2 HTTP/1.1公共請求頭部是不論操作類型，每個請求消息都需要包含的一些頭部參數(shù)（詳細頭部參數(shù)列表見2.4.1）。請求頭部是一些操作特定的頭部參數(shù)，比如4.2.1上傳 Archive 操作，x-oas-archive-description是該操作的請求頭部，指定Archive的描述信息。公共請求頭部和請求頭部的格式參照 HTTP/1.1協(xié)議各Headers。請求體則是請求需要提供的額外信息，如4.4.1初

17、始化Job任務(wù)，請求需要提供Type等其他信息來指定Job的類 型等。請求體的格式按照JSON的格式封裝。本文檔中的請求體示例為了便于用戶查看，做了格式化處理，實際 是沒有換行、縮進等處理。通信返回返回消息與格式Status-LineCommon Response Headers Response Headers Response Body Status-LineCommon Response Headers Response Headers Response Body 狀態(tài)行格式參照HTTP/1.1協(xié)議Status-Line，返回的HTTP狀態(tài)碼2xx，代表調(diào)用成功；返回4xx或5xx的HT

18、TP狀 態(tài)碼代表調(diào)用失敗。公共返回頭部是無論調(diào)用是否成功，都會返回的頭部參數(shù)（詳細參數(shù)列表見2.4.2）。返回頭部是不同類型的操作，可能會額外返回的頭部參數(shù)。如4.1.1創(chuàng)建Vault操作返回頭部包括Location和x- oas-vault-id，分別指定新創(chuàng)建Vault的URI和Vault ID。公共返回頭部和返回頭部的格式參照HTTP/1.1協(xié)議各Headers。返回體是操作返回的額外信息。如獲取Vault列表中，緊跟在頭部參數(shù)后面就是返回的Vault列表信息，返回體 按照JSON的格式封裝。本文檔的返回體示例為了便于用戶查看，做了格式化處理，實際返回結(jié)果是沒有進行換郵件推送/API參考

19、手冊郵件推送/API參考手冊行、縮進等處理的。成功結(jié)果ArchiveId: ArchiveId ,ArchiveId: ArchiveId ,/* 其他信息*/錯誤結(jié)果調(diào)用接口出錯后，HTTP請求會返回一個4xx或5xx的HTTP狀態(tài)碼，且不會提供返回頭部，但是在返回體中會提 供具體的錯誤代碼及錯誤信息，調(diào)用方也可以根據(jù)附表來定位錯誤原因。在調(diào)用方找不到錯誤原 因，可以聯(lián)系阿里云客服，并提供公共返回頭部的x-oas-request-id和公共請求頭部Host字段，以便我們盡快 幫您解決問題。code: UnsupportedOperation,code: UnsupportedOperatio

20、n,message: The specified action is not supported., type: client公共頭部參數(shù)公共請求頭部公共請求頭部是指每個接口都需要使用到的頭部參數(shù)。名稱是否必須描述Authorization是請看簽名形成機制Content-Length否（文件上傳時必須）請求體的字節(jié)長度（不包括請求頭）Date否這個頭部參數(shù)在創(chuàng)建簽名時使用，它是按照HTTP1.1協(xié)議Date頭部的格式，如 Tue, 25Mar 2014 12:00:00 GMT。Host否指定要發(fā)送到的服務(wù)端地址如，RegionName.oas.aliyuncs.c om。x-oas-ver

21、sion是阿里云歸檔存儲 API版本，如EclipseEclipse/最佳實踐2014-01-01。Host: Date: Tue, 25 Mar 2014 12:00:00 GMTx-oas-archive-description: MyArchive Authorization: SignatureValuex-oas-version: 2014-01-01Host: Date: Tue, 25 Mar 2014 12:00:00 GMTx-oas-archive-description: MyArchive Authorization: SignatureValuex-oas-versi

22、on: 2014-01-01公共返回頭部用戶發(fā)送的每次接口調(diào)用請求，無論成功與否，系統(tǒng)都會返回一些固定的頭部參數(shù)，其中最重要的是x-oas- request-id，它對各個請求都是唯一存在的。名稱描述Content-Length返回體的字節(jié)長度（不包括返回頭部，無返回體時無此頭部）Date這個頭部參數(shù)在 歸檔存儲 響應(yīng)時生成，它是按照HTTP1.1協(xié)議Date頭部的格式，如Tue, 25 Mar2014 12:00:00 GMT。x-oas-request-id由阿里云歸檔存儲生成唯一請求標識符，以便定位問題。x-oas-request-id: RequestId Date: Tue, 25

23、Mar 2014 12:00:00 GMTx-oas-request-id: RequestId Date: Tue, 25 Mar 2014 12:00:00 GMT校驗碼計算歸檔存儲的校驗碼頭部參數(shù)有兩個：x-oas-content-etag和x-oas-tree-etag，其中x-oas-content-etag是針 對上傳請求的請求體用md5計算得出的校驗碼，x-oas-tree-etag是針對上傳請求的請求體用tree-hash算法計 算得出的校驗碼。為了確保上傳數(shù)據(jù)的一致性，歸檔存儲要求用戶在上傳文檔時，無論是單個文檔上傳方式還是Multipart 上傳方式，都必須包含上傳數(shù)據(jù)的校

24、驗碼。歸檔存儲收到數(shù)據(jù)以后，會計算校驗碼，并與用戶提供的校 驗碼進行比對。如果不一致，會返回錯誤，該請求失敗。同樣用戶在下載Archive時，歸檔存儲也會返回相應(yīng)的 校驗碼，供用戶校驗下載數(shù)據(jù)是否完整。本節(jié)2.5.1、2.5.2用來描述x-oas-content-etag和x-oas-tree-etag兩種校驗碼的設(shè)置，2.5.3描述計算x-oas- tree-etag使用到的tree-hash算法，2.5.4描述下載數(shù)據(jù)時x-oas-tree-etag校驗碼的使用規(guī)則。x-oas-content-etag校驗碼x-oas-content-etag是通過計算待上傳數(shù)據(jù)的MD5，并將該MD5值所

25、有小寫字母轉(zhuǎn)換為大寫字母的結(jié)果。如 某個數(shù)據(jù)的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是通過對上傳或接收數(shù)據(jù)進行tree-hash算法（請參見2.5.3 tree-hash算法說明）計算出的校驗碼。有四個接口會使用到x-o

26、as-tree-etag參數(shù)，其中上傳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的用法。單文檔上傳方式用戶在調(diào)用單文檔上傳接口之前需要對上傳的文檔進行tree-hash算法計算tree-etag校驗碼。如某個文檔的tree-etag校驗碼為26093833F5438BD1F2F3

27、4C731A0F90DE，它便是這個單文檔的x-oas-tree-etag。Multipart Upload上傳方式Multipart Upload方式在Part 上傳與Part 合并時都需要提供x-oas-tree-etag頭部參數(shù)。Part上傳時x-oas-tree-etag的計算方法是取該Part對應(yīng)數(shù)據(jù)范圍，做tree-hash算法計算得到的值。在所有Part上傳完成后，用戶需要發(fā)起Part合并請求，此時用戶提交請求的x-oas-tree-etag頭部可以通過對整 個上傳數(shù)據(jù)做 tree-hash 算法計算得出，也可以復(fù)用已上傳Part的x-oas-tree-etag校驗值，省去tre

28、e-hash算法(參見2.5.3)中計算每個1MB數(shù)據(jù)的tree-etag值的步驟，直接把每個Part的x-oas-tree-etag值作為葉子節(jié)點，再按照tree-hash算法的步驟2、步驟3，最終得到整個Archive的tree-hash算法根值。示例：假設(shè)一個149903360字節(jié)的文件，用戶以67108864為Part 大小上傳，如下圖所示：第一個段上傳Archive的0-67108863字節(jié)，用tree-hash算法得到該段的x-oas-tree-etag校驗碼為： F60F379B33C234F69FA4F79254650F65第二個段上傳Archive的67108864-1342

29、17727 字節(jié)，用tree-hash算法得到該段的x-oas-tree-etag校驗碼為：9D739013ABAE399B173B3C3415BDC69A第三個段上傳Archive的134217728-149903359字節(jié)，用tree-hash算法得到該段的x-oas-tree-etag校驗碼為：F9C22EBEA613C03AF231187B85BD3D30合并時的x-oas-tree-etag校驗碼計算：按字節(jié)順序排列已上傳Part的x-oas-tree-etag校驗碼，作為tree-etag樹的葉子節(jié)點： F60F379B33C234F69FA4F79254650F65 9D7390

30、13ABAE399B173B3C3415BDC69A F9C22EBEA613C03AF231187B85BD3D30按照tree-hash算法步驟2、步驟3計算出整個Archive的x-oas-tree-etag校驗碼： 93C106A8937AC115BD21A63FE9114B1。Job Output下載當用戶調(diào)用Job Output下載接口時，如果用戶遵守tree-hash樹對齊規(guī)則（具體規(guī)則請參見2.5.4 下載數(shù)據(jù)時x- oas-tree-etag校驗碼的使用），歸檔存儲會在返回頭部中設(shè)置一個x-oas-tree-etag參數(shù)，該參數(shù)是歸檔存儲 用tree-hash算法對返回數(shù)據(jù)計

31、算出的校驗碼。用戶可以使用該校驗碼確認所接收到的數(shù)據(jù)與歸檔存儲的數(shù)據(jù)是 否一致。tree-hash算法x-oas-tree-etag是通過對數(shù)據(jù)進行tree-hash算法計算得出的校驗值，它的具體操作步驟如下：對數(shù)據(jù)的每個1MB塊，計算它的md5值，并轉(zhuǎn)換為大寫。只有數(shù)據(jù)的最后一個塊可以小于1MB。例 如，上傳或者下載6.5MB的數(shù)據(jù)，則需要計算該數(shù)據(jù)的前6個1MB塊的md5值，及最后的0.5MB數(shù)據(jù)md5。這7個md5值轉(zhuǎn)大寫后，就構(gòu)成了tree-hash算法的葉子節(jié)點。構(gòu)建父節(jié)點。依次連接兩個連續(xù)子節(jié)點的值形成一個字符串，對這個字符串作md5計算，并且轉(zhuǎn)大寫。這個值 就是兩個子節(jié)點的父節(jié)點

32、。最后如果只剩一個子節(jié)點，則它的父節(jié)點就是自身。重復(fù)步驟2，直到得到一個根節(jié)點為止。這個根節(jié)點就是待上傳或者下載數(shù)據(jù)的x-oas-tree-etag值。 舉例如下圖所示：假設(shè)有份數(shù)據(jù)6.5MB，分別計算它的前6個1MB塊的md5值，及最后一個0.5MB的md5值，按順序 依次為：1ca30cd59f0b566f9ef3a8208679585e e07910a06a086c83ba41827aa00b26ed 76f556302c49d8f6503a7e60b2ed1d7d 7a3b8c43b0791ba6ce01f5696fd36f13 65487827c964185d8929fa30bf11

33、df182c7282bbca9abc9d446e02b8adee9563 46a5e231e4581f5defd12e8688da6377 轉(zhuǎn)大寫后的結(jié)果為：H節(jié)點值1CA30CD59F0B566F9EF3A8208679585E I節(jié)點值E07910A06A086C83BA41827AA00B26ED J節(jié)點值76F556302C49D8F6503A7E60B2ED1D7D K節(jié)點值7A3B8C43B0791BA6CE01F5696FD36F13 L節(jié)點值65487827C964185D8929FA30BF11DF18 N節(jié)點值46A5E231E4581F5DEFD12E8688DA6377

34、構(gòu)建父節(jié)點。H, I的父節(jié)點D的值：85786098CA1FFDE6E267FA131DE97BCE。首先計算節(jié)點D的值，連接H和I的值形成一個字符串85786098ca1ffde6e267fa131de97bceH, I的父節(jié)點D的值：85786098CA1FFDE6E267FA131DE97BCE。依此類推，兩兩連接，得到J,J, K的父節(jié)點E的值：B15B5E7BDDB12E28B1AF9711591B260B， L, M的父節(jié)點F的值：6CE4D37E18F3642B1E9D1CF2D2532D86。最后剩下的單個節(jié)點N， 父節(jié)點G和N相同：46A5E231E4581F5DEFD12E

35、8688DA6377。D, E的父節(jié)點B的值：6C9924508699E38F6F898ECCE4F64F9B，F(xiàn), G的父節(jié)點C的值：687DC906A777E986DD792FD469A3CC65。將D、E、F、GD, E的父節(jié)點B的值：6C9924508699E38F6F898ECCE4F64F9B，F(xiàn), G的父節(jié)點C的值：687DC906A777E986DD792FD469A3CC65。將B,CaA的值：26093833F5438BD1F2F34C731A0F90DE加密服務(wù)/使用手冊加密服務(wù)/使用手冊通過步驟2，最終計算得到tree-hash樹根節(jié)點的值26093833F5438BD

36、1F2F34C731A0F90DE，這 個值就是待上傳或者下載數(shù)據(jù)的x-oas-tree-etag值。下載時x-oas-tree-etag校驗碼的使用當用戶創(chuàng)建Job取回Archive時，可以選擇要取回的Archive范圍。同樣，當用戶下載這個job時，也可以選擇要 下載的Job范圍。用戶在下載Job能否得到歸檔存儲服務(wù)端返回x-oas-tree-etag校驗碼，取決于兩個范圍（用 戶創(chuàng)建Job指定的Archive范圍與下載Job時指定的Job范圍）是否遵守了兆字節(jié)對齊、tree-hash樹對齊。所謂 兆字節(jié)對齊與tree-hash樹對齊的定義如下：兆字節(jié)對齊，是指Range startPos

37、, EndPos是以兆（1024*1024）字節(jié)對齊，其中startPos可被1MB整除；EndPos加1可被1MB整除，或者等于Archive的大小。tree-hash樹對齊，是指在范圍startPos, EndPos 用tree-hash算法計算出來的根節(jié)點，會存在于整個Archive的tree-etag樹中。Tree-hash樹對齊說明假設(shè)整個Archive大小為n字節(jié)，0ABn-1A, B要tree-hash樹對齊，首要條件是A與B+1都能夠被(1024*1024)P, Q分別為A與B+1整除1MB后的值，即AB可以用P*1024*1024,Q*1024*1024-1表示。為便于閱讀，

38、以下用P, Q)來表示P, Q-1。A, B滿足tree-hash樹對齊，需要P, Q)符合以下特征：如果P0Q2k或n，k00klog2(n); 如果P為奇數(shù)，則只有QP+1時，PQtree-hash樹對齊；如果P為偶數(shù)，k定義為以P開始的能夠tree-hash樹對齊的范圍個數(shù)，其中k的計算方式為：假設(shè)T=P，將T做循環(huán)位右移運算，直到T模2不等于0，或者T等于0。對于每個i，如果(0 = i = k)且P+ 2i n，則P, P+2i)是以tree-hash樹對齊的范圍。為簡化用戶使用tree-hash樹對齊，建議用戶將數(shù)據(jù)以2N MB為range大小進行Job創(chuàng)建或者下載（N為大于0的整

39、數(shù)）。如下圖所示：以下案例描述了在下載檔案數(shù)據(jù)時，會在哪些情況下收到x-oas-tree-etag頭部：補丁管理/補丁列表補丁管理/補丁列表如果在創(chuàng)建 Job請求中未指定要取回的范圍，并且在Job下載請求中下載整個檔案。如果在創(chuàng)建 Job請求中未指定要取回的范圍，并且在Job下載請求中下載整個檔案。如果在創(chuàng)建Job請求中未指定要取回的范圍，并且在Job下載請求中指定要下載的范圍以tree-hash樹對齊。 如果在創(chuàng)建Job請求中指定要取回的范圍以tree-hash樹對齊，并且在Job下載請求中下載整個Job。如果在創(chuàng)建Job請求中指定要取回的范圍以tree-hash樹對齊，并且在Job下載請求

40、中指定要下載的范圍以tree-hash樹對齊。以下圖舉例說明：當用戶提交對整個Archive的Job，在下載整個Job時，遵守了tree-hash樹對齊，則歸檔存儲會在響 應(yīng)頭部的x-oas-tree-etag參數(shù)中返回整個Archive的tree-etag值。如果用戶提交整個Archive的Job，但只下載Data-1.1的數(shù)據(jù)，則歸檔存儲不會返回tree-etag值。如果用戶提交整Archive的Job，但只下載Data-2.1的數(shù)據(jù)，下載請求的響應(yīng)頭部中歸檔存儲會返回tree-etag樹的F節(jié)點的值。如果用戶提交針對Data-1的Job，且下載整個Job遵守了tree-hash樹對齊，下

41、載請求的響應(yīng)頭部中 歸檔存儲會返回tree-hash樹中的B節(jié)點值。如果用戶提交針對Data-1的Job，且只下載Data-1.1范圍的數(shù)據(jù)，則歸檔存儲不會返回x-oas-tree- etag參數(shù)。如果用戶提交針對Data-2的Job，且下載Data-2.2范圍的數(shù)據(jù)，則歸檔存儲會在響應(yīng)頭部參數(shù)x-oas- tree-etag中返回tree-hash樹中N節(jié)點的值。如果用戶提交Data-1.1范圍數(shù)據(jù)的Job，則針對該Job的任何下載范圍，歸檔存儲都不會返回x-oas- tree-etag參數(shù)。用戶簽名驗證（Authentication）歸檔存儲通過使用AccessKeyID/AccessKe

42、ySecret對稱加密的方法來驗證某個請求的發(fā)送者身份。是用戶用于加密簽名字符串和歸檔存儲用來驗證簽名字符串的 密鑰，請勿將其泄露給第三方。每個AccessKey對（AccessKeyID和AccessKeySecret）有兩種狀態(tài)，分別為active和inactive。active表明用戶可以用此AccessKey對簽名驗證請求inactive表明用戶暫停此AccessKey對簽名驗證的功能當用戶向歸檔存儲發(fā)送請求時，需要首先將發(fā)送的請求按照歸檔存儲指定的格式生成簽名字符串；然后使用AccessKeyID找到對應(yīng) 的AccessKeySecret，以同樣的方法提取簽名字符串和驗證碼，如果計算

43、出來的驗證碼和提供的一樣即認為該 請求是有效的；否則，歸檔存儲將拒絕處理這次請求，并返回HTTP403錯誤。用戶簽名計算方法用戶需要在HTTP請求中增加Authorization（授權(quán)）的HTTP頭部字段來包含Signature（簽名）信息，表明這 個消息已被授權(quán)。Authorization: OAS + Access Key Id + : + Signature Signature = base64(hmac-sha1(VERB + n+ DATE + n+ CanonicalizedOASHeaders+ CanonicalizedResource)AuthorizationAuthori

44、zation: OAS + Access Key Id + : + Signature Signature = base64(hmac-sha1(VERB + n+ DATE + n+ CanonicalizedOASHeaders+ CanonicalizedResource)VERB 表 示 HTTP 方 法 ， 如 GET/POST DATE表示此次操作的時間，必須為HTTP/1.1中支持的GMT格式表示所有前綴為x-oas-的HTTPHeader CanonicalizedResource表示用戶想要訪問的歸檔存儲資源，即URI其中，DATE和CanonicalizedResource

45、不能為空；如果請求中的DATE時間和歸檔存儲的服務(wù)器時間差正負 15分鐘以上，歸檔存儲將拒絕該請求，并返回HTTP403錯誤。構(gòu)建CanonicalizedOASHeaders的方法所有以x-oas-為前綴的HTTP Header被稱為CanonicalizedOASHeaders，它的構(gòu)建方法如下：將所有以x-oas-為前綴的HTTP請求頭的名字轉(zhuǎn)換成小寫字母。如X-OASPart-Size: 67108864轉(zhuǎn)換成x-oas-part-size: 67108864。將上一步得到的所有HTTP請求頭按照字典序進行升序排列。刪除請求頭和內(nèi)容之間分隔符兩端出現(xiàn)的任何空格。如x-oas-part-

46、size: 67108864轉(zhuǎn)換成x-oas- part-size:67108864。將所有的頭和內(nèi)容用n分隔符分隔拼成最后的CanonicalizedOASHeader。構(gòu)建CanonicalizedResource的方法用戶發(fā)送請求中想訪問的歸檔存儲目標資源被稱為CanonicalizedResource。它的構(gòu)建方法如下： 將CanonicalizedResource置成空字符串（）。放入要訪問的歸檔存儲資源，如：/vaults/ VaultId 。如果請求的資源包括子資源（sub-resource），將所有的子資源按照字典序，從小到大排列，以 字符串尾添加?和子資源字符串。如： /va

47、ults/ VaultId /multipart-uploads。如果請求含參數(shù)，將參數(shù)及值按照字典序，從小到大排列，以&為分隔符，添加到CanonicalizedResource中。如： /vaults/ VaultId/multipartuploads?limit=1&marker=30DF64484BD34B4C44BB261A02DF89BA。 參數(shù)值為空的時候，請不要傳遞此參數(shù)。如marker為空串（）時，參數(shù)列表中不要包含該參數(shù)。用戶簽名示例Access Key ID：ckdwpp7o2l2rhxf3d5j7dzzmGET /vaults/ VaultId /multipart-u

48、ploads HTTP/1.1 Date: Wed, 16 Apr 2014 05:51:14 GMTAccess Key Secret：gUWY5b687iv0d+LJLHRJW1PzhZY= 待簽名內(nèi)容如下：GET /vaults/ VaultId /multipart-uploads HTTP/1.1 Date: Wed, 16 Apr 2014 05:51:14 GMTHost: Host: import base64 import hmac import shah = hmac.new(gUWY5b687iv0d+LJLHRJW1PzhZY=,GETnWed,16Apr201405:

49、51:14GMTn/vaults/30DF64484BD34B4C44BB261A02DF89BA/multipart- uploads,sha) base64.encodestring(h.digest().strip()GET /vaults/30DF64484BD34B4C44BB261A02DF89BA/multipart-uploads HTTP/1.1 Host: GET /vaults/30DF64484BD34B4C44BB261A02DF89BA/multipart-uploads HTTP/1.1 Host: Date: Wed, 16 Apr 2014 05:51:14

50、GMTAuthorization: OAS ckdwpp7o2l2rhxf3d5j7dzzm:dZpCvvKgxiFw6wvMHHj5g3W6STM=在計算簽名的時候請遵循如下規(guī)則：用來簽名的字符串必須為UTF-8格式。含有中文字符的簽名字符串必須先進行UTF-8編碼，再與Access Key Secret計算最終簽名。簽名的方法用RFC 2104中定義的HMAC-SHA1方法，其中Key為Access Key Secret。在所有非HTTP標準定義的Header中，只有以x-oas-開頭的Header，需要加入簽名字符串；其他 非HTTP標準Header將被歸檔存儲忽略。以x-oas-開頭的

51、Header在簽名驗證前需要符合以下規(guī)范：Header的名字需要變成小寫。Header按字典序自小到大排序。分割HeaderName和Value的冒號前后不能有空格。每個Header之后都有一個換行符n。如果沒有符合要求的Header，CanonicalizedOASHeaders應(yīng)置為空。異常說明傳入的Access Key ID不存在或inactive，返回 403 Forbidden。錯誤碼：InvalidAccessKeyId。MongoDBMongoDB/使用手冊Authorization字段值格式不對，返回 400 Bad Request。錯誤碼：InvalidArgument。沒有

52、傳入Date或者格式不正確，返回 403 Forbidden錯誤。錯誤碼：AccessDenied。傳入的Date必須在歸檔存儲的服務(wù)器當前時間前后15分鐘以內(nèi)，否則返回 403 Forbidden，錯誤碼：RequestTimeTooSkewed。Vault操作創(chuàng)建Vault（PUT）描述此操作能夠用指定名稱創(chuàng)建一個新的 Vault，該名稱在同一賬戶的同一Region下是唯一的。同一個賬號在同一Region下最多只能擁有10個Vault。當用戶提交創(chuàng)建Vault請求且創(chuàng)建成功時，會返回該Vault對應(yīng)的Vault ID。創(chuàng)建 Vault 需要遵守如下規(guī)范：只能包含小寫字母、數(shù)字、下劃線（_）

53、、短橫線（-）。必須以小寫字母或者數(shù)字開頭和結(jié)尾。3-63發(fā)送 HTTP PUT 請求，就可以完成 Vault 的創(chuàng)建。請求參數(shù)無請求頭部無，其他公共請求頭部參見2.4.1請求體無返回頭部名稱描述Location該Vault對應(yīng)的URIx-oas-vault-id該Vault的ID彈性伸縮/計量計費彈性伸縮/計量計費其他公共返回頭部參見2.4.2返回體無示例PUT /vaults/VaultName HTTP/1.1 Host: Date: Tue, 25 Mar 2014 12:00:00 GMTx-oas-version: 2014-01-01 PUT /vaults/VaultName

54、HTTP/1.1 Host: Date: Tue, 25 Mar 2014 12:00:00 GMTx-oas-version: 2014-01-01 Authorization: SignatureValue返回示例HTTP/1.1 201 CreatedHTTP/1.1 201 Createdx-oas-request-id: RequestIdDate: Tue, 25 Mar 2014 12:00:00 GMTLocation: /vaults/VaultId x-oas-vault-id: VaultId刪除Vault（DELETE）描述此操作是為刪除一個空的Vault?？盏腣aul

55、t是指：VaultArchive 自最近一次檢索結(jié)果生成的時間至今，該 Vault 沒有新的文檔寫入請求參數(shù)無請求頭部無，其他公共請求頭部參見2.4.1請求體無返回頭部無，其他公共返回頭部參見2.4.2返回體無示例DELETE /vaults/VaultId HTTP/1.1 Host: Date: Tue, 25 Mar 2014 12:00:00 GMTx-oas-version: 2014-01-01 DELETE /vaults/VaultId HTTP/1.1 Host: Date: Tue, 25 Mar 2014 12:00:00 GMTx-oas-version: 2014-0

56、1-01 Authorization: SignatureValue返回示例HTTP/1.1 204 No ContentHTTP/1.1 204 No Contentx-oas-request-id: RequestIdDate: Tue, 25 Mar 2014 12:00:00 GMT獲取Vault信息（GET）描述此操作返回的Vault信息包括：VaultName，Vault創(chuàng)建時間，Archive數(shù)，Archive總大小等。歸檔存儲每天定 時掃描生成一次Vault索引緩存。如果用戶添加或者刪除一個Archive之后，立即發(fā)起獲取Vault信息的請求，則 該請求的響應(yīng)很可能不會反映這次

57、改變。請求參數(shù)無請求頭部無，其他公共請求頭部參見2.4.1請求體無返回頭部視頻直播/使用手冊視頻直播/使用手冊無，其他公共返回頭部參見2.4.2返回體CreationDateVault 的創(chuàng)建時間LastInventoryDate歸檔存儲對該Vault最近的一次索引緩存時間NumberOfArchives最近一次檢索時Vault的Archive數(shù)SizeInBytes最近一次檢索時Vault的Archive大小總和Vault的IDVaultNameVault的名稱示例GET /vaults/VaultId HTTP/1.1Host: Date: Tue, 25 Mar 2014 12:02:0

58、0 GMTGET /vaults/VaultId HTTP/1.1Host: Date: Tue, 25 Mar 2014 12:02:00 GMTx-oas-version: 2014-01-01 Authorization: SignatureValue返回示例HTTP/1.1 200 OKHTTP/1.1 200 OKx-oas-request-id: RequestIdDate: Tue, 25 Mar 2012 12:02:00 GMTContent-Type: application/json Content-Length: 260CreationDate: Tue, 25 Mar

59、 2014 12:00:00 GMT,LastInventoryDate: Tue, 25 Mar 2014 12:00:00 GMT,NumberOfArchives: 192,SizeInBytes: 78088912,VaultId: 79D2D8F33B7C287037286185863B6823,VaultName: myvaultVaultName: myvault獲取Vault列表（GET）描述此操作會列出該用戶擁有的全部Vault信息。默認情況下，此操作返回的列表中最多會有10個Vault，列表按Vault ID升序排列。用戶應(yīng)始終檢查返回體中的Marker為（空串），則表示列

60、表已 全部獲取完成。用戶還可以通過設(shè)置limit參數(shù)來限制每次請求返回的Vault數(shù)量，但是limit不能超過10，如果 超過10，按10處理。請求參數(shù)無請求頭部無，其他公共請求頭部參見2.4.1請求體無返回頭部無，其他公共返回頭部參見2.4.2返回體Marker下一次列表請求的起始標記，空串（）表示無后續(xù)的列表VaultList CreationDateVault的創(chuàng)建時間LastInventoryDate歸檔存儲對該Vault最近的一次檢索緩存時間NumberOfArchives最近一次檢索時Vault的Archive數(shù)SizeInBytes最近一次檢索時Vault的Archive大小總和