阿里云-歸檔存儲(chǔ)-SDK手冊(cè)-D

1、歸檔存儲(chǔ)SDK使用手冊(cè)歸檔存儲(chǔ)/SDK使用手冊(cè)歸檔存儲(chǔ)/SDK使用手冊(cè) PAGE 98 PAGE 98SDK使用手冊(cè)Python 概述Python SDKOAS API參考手冊(cè)（API）第一章基Vault、Archive、Mupltipart Upload、Job，這部分內(nèi)容本手冊(cè)將不再詳述。Python SDKoascmdSDK，oascmd，oascmd的使用方法請(qǐng)移步 OAS命令行工具。有更高開(kāi)發(fā)需求的用戶SDKPython SDK 接口分為兩種形態(tài)，分別為低級(jí)接口和高級(jí)接口。其中，低級(jí)接口置于 oas 模塊內(nèi)，高級(jí)接口置oas.ease低級(jí)接口HTTPURLRESTfulRESTful

2、 接口均對(duì)應(yīng)于低級(jí)接口的一個(gè)方法。每個(gè)低級(jí)接口返回 HTTPResponse 原始對(duì)象，用戶須根據(jù) API在oascmd中，通過(guò)命令行參數(shù)，用戶即可以方便地調(diào)用每一個(gè)低級(jí)接口。高級(jí)接口為了簡(jiǎn)化用戶的開(kāi)發(fā)流程，縮短學(xué)習(xí)曲線，SDK 在低級(jí)接口的基礎(chǔ)上提供更抽象的高級(jí)接口。高級(jí)接口在低級(jí)接口的基礎(chǔ)上，進(jìn)一步封裝了校驗(yàn)碼生成、自動(dòng)重試、斷點(diǎn)續(xù)傳等高級(jí)功能。用戶在使用過(guò)程中不需要關(guān)心高 級(jí)接口內(nèi)部實(shí)際調(diào)用的是哪個(gè)RESTful接口，只需按照所需的業(yè)務(wù)類型調(diào)用接口即可，如上傳、查詢等。使用建議建議用戶使用高級(jí)接口，這樣會(huì)使得用戶的程序邏輯更加簡(jiǎn)明。但當(dāng)所需功能沒(méi)有被包含在高級(jí)接口內(nèi)時(shí)，建 議用戶參考高級(jí)

3、接口的實(shí)現(xiàn)，在其基礎(chǔ)上增加相應(yīng)的定制功能，同時(shí)，歡迎用戶把相關(guān)需求反映給 歸檔存儲(chǔ) 開(kāi)發(fā)團(tuán)隊(duì)，對(duì)于合理的需求，會(huì)在接下來(lái)的版本中得到實(shí)現(xiàn)。若用戶需要更細(xì)粒度的操作，則可直接調(diào)用低級(jí)接 口，根據(jù)實(shí)際使用場(chǎng)景進(jìn)行封裝。郵件推送/SMTP接口說(shuō)明郵件推送/SMTP接口說(shuō)明Demo程序參考最佳實(shí)踐-Python。高級(jí)接口高級(jí)接口中的所有方法均為阻塞操作，在操作沒(méi)有完成之前不會(huì)返回。所有接口都可能會(huì)拋出兩種異常，分別 為OASServerError和OASClientError，具體描述請(qǐng)參閱Exceptions一節(jié)。import logging import syshandler = logging.

4、StreamHandler(sys.stdout) handler.setFormatter(logging.Formatter(%(asctime)s %(message)s) import logging import syshandler = logging.StreamHandler(sys.stdout) handler.setFormatter(logging.Formatter(%(asctime)s %(message)s) handler.setLevel(logging.INFO)log = logging.getLogger(oas.ease.uploader) log.

5、addHandler(handler) log.setLevel(logging.INFO)Vault類Vault是用戶所有操作的入口點(diǎn)。要實(shí)例化Vault對(duì)象，需要通過(guò)Vault的類方法，其中create_vault、get_vault_by_id和get_vault_by_name是簡(jiǎn)單工廠方法，返回Vault對(duì)象，list_all_vaults返回Vault list。這些類方法都需要以O(shè)ASAPI對(duì)象作為參數(shù)（參見(jiàn)低級(jí)接口概述部分）。對(duì)于上傳操作，可以直接調(diào)用成員方法upload_archive，接口內(nèi)部會(huì)根據(jù)文件大小自動(dòng)選擇Normal Upload或Multipart Upload

6、方式，并實(shí)現(xiàn)了多線程并行上傳和失敗重試。對(duì)于Multipart Upload任務(wù)，用戶也可調(diào)用成員方法initiate_uploader獲得Uploader對(duì)象再進(jìn)行上傳（參見(jiàn)Uploader一節(jié)）。使用后一種方法，用戶可獲 得時(shí)機(jī)保存Multipart Upload的任務(wù)ID，若任務(wù)沒(méi)有成功完成，可在之后調(diào)用成員方法recover_uploader傳入任務(wù)ID進(jìn)行續(xù)傳。用戶應(yīng)根據(jù)業(yè)務(wù)需要選擇合適的方法。對(duì)于下載操作，可調(diào)用成員方法retrieve_inventory或retrieve_archive獲得Job對(duì)象再進(jìn)行下載（參見(jiàn)Job一節(jié)）。下面按照功能分組，介紹Vault的接口。成員變量V

7、ault對(duì)象包含了Vault的JSON描述中的所有字段，其中JSON標(biāo)簽與變量之間的轉(zhuǎn)換關(guān)系如下表所示，各個(gè)字段的具體含義請(qǐng)參考API文檔4.1.3一節(jié)的返回體部分。JSON標(biāo)簽變量名類型CreationDatecreation_datestringLastInventoryDatelast_inventory_datestringNumberOfArchivesnumber_of_archivesintSizeInBytessizeintVaultIdidstringVaultNamenamestring構(gòu)造方法類Vault包含了三個(gè)簡(jiǎn)單工廠方法用于構(gòu)造Vault對(duì)象，三個(gè)類方法均需OASA

8、PI對(duì)象作為參數(shù)，OASAPI的構(gòu)造請(qǐng)參閱低級(jí)接口的概述部分。create_vault類方法。新建指定名稱的Vault。定義def create_vault(cls, api, name)參數(shù)api：OASAPI name：string待新建的Vault的名稱，名稱應(yīng)遵守API手冊(cè)4.1.1節(jié)中Vault命名規(guī)范。返回值Vaultget_vault_by_id類方法。獲取指定ID的Vault。定義def get_vault_by_id(cls, api, vault_id)參數(shù)DRDS/服務(wù)條款與價(jià)格模型DRDS/服務(wù)條款與價(jià)格模型api：OASAPIvault_id：string待檢索的Va

9、ult的ID。返回值Vaultget_vault_by_name類方法。獲取指定名稱的Vault。定義def get_vault_by_name(cls, api, vault_name)參數(shù)api：OASAPI vault_name：string待檢索的Vault的名稱。返回值VaultVault刪除delete_vault_by_id類方法。刪除指定ID的Vault。定義def delete_vault_by_id(cls, api, vault_id)參數(shù)api：OASAPI vault_id：string企業(yè)級(jí)分布式應(yīng)用服務(wù) EDAS/API參考手冊(cè)企業(yè)級(jí)分布式應(yīng)用服務(wù) EDAS/AP

10、I參考手冊(cè)待刪除的Vault的ID。返回值Nonedelete_vault_by_name類方法。刪除指定名稱的Vault。定義def delete_vault_by_name(cls, api, vault_name)參數(shù)- api：OASAPI vault_name：string待刪除的Vault的名稱。返回值None delete刪除當(dāng)前Vault。定義def delete(self)參數(shù)None返回值None狀態(tài)查詢所有查詢方法默認(rèn)返回全部的檢索結(jié)果，用戶不需要對(duì)Marker標(biāo)識(shí)進(jìn)行處理。list_all_vaults類方法。返回用戶持有的所有Vault。定義def list_all_

11、vaults(cls, api)參數(shù)- api：OASAPI返回值Vault listlist_all_multipart_uploads返回Vault下的全部Multipart Upload任務(wù)。定義def list_all_multipart_uploads(self)參數(shù)None返回值Uploader list list_all_jobs返回Vault下的所有Job任務(wù)。定義def list_all_jobs(self)參數(shù)None返回值Job listArchive操作upload_archive上傳指定文件到當(dāng)前Valut，成功上傳后返回相應(yīng)的Archive ID。定義def upl

12、oad_archive(self, file_path, desc=None)參數(shù)file_path：string待上傳的文件路徑。desc：string可選參數(shù)。Archive的描述字段。返回值string：Archive ID initiate_uploader新建Multipart Upload任務(wù)。定義def initiate_uploader(self, file_path, desc=None)參數(shù)file_path：string待上傳的文件路徑。desc：string可選參數(shù)。Archive的描述字段。返回值Uploaderrecover_uploader續(xù)傳指定的Multipa

13、rt Upload任務(wù)。定義def recover_uploader(self, upload_id)參數(shù)upload_id：stringMultipart Upload任務(wù)的ID。返回值Uploaderdelete_archive刪除指定ID的Archive。定義def delete_archive(self, archive_id)參數(shù)archive_id：string待刪除的Archive的ID。返回值NoneJob操作get_job獲取指定ID的Job任務(wù)。定義def get_job(self, job_id)參數(shù)job_id：stringJob任務(wù)的ID。返回值Jobretrieve

14、_archive新建類型為archive-retrieval的Job任務(wù)。定義def retrieve_archive(self, archive_id, desc=None, byte_range=None):參數(shù)archive_id：string待查詢的Archive的ID。desc：string可選參數(shù)。Job任務(wù)的描述字段。byte_range：tuple可選參數(shù)。長(zhǎng)度為2，元素分別為字節(jié)長(zhǎng)度的起點(diǎn)和終點(diǎn)（含）。返回值Jobretrieve_inventory新建類型為inventory-retrieval的Job任務(wù)。定義def retrieve_inventory(self, de

15、sc=None)參數(shù)desc：string可選參數(shù)。Job任務(wù)的描述字段。返回值Jobpull_from_oss新建類型為pull-from-oss的Job任務(wù)。定義def pull_from_oss(self, osshost, bucket, object, desc=None)參數(shù)osshost：stringjob的源oss域名bucket：stringjob任務(wù)的oss Bucketobject：stringjob任務(wù)的oss Objectdesc：string可選參數(shù)。Job任務(wù)的描述字段。返回值Jobpush_to_oss新建類型為push-to-oss的Job任務(wù)。定義def p

16、ush_to_oss(self, archive_id, osshost, bucket, object, desc=None)參數(shù)- archive_id：string待轉(zhuǎn)儲(chǔ)的archive_idosshost：stringjob的源oss域名HTTPDNS/接口參考手冊(cè)HTTPDNS/接口參考手冊(cè)bucket：stringjob任務(wù)的oss Bucketobject：stringjob任務(wù)的oss Objectdesc：string可選參數(shù)。Job任務(wù)的描述字段。返回值JobUploaderUploader是Multipart Upload任務(wù)的抽象。要獲取Uploader對(duì)象，可通過(guò)Va

17、ult的三個(gè)成員方法，包括：initiate_uploaderrecover_uploaderlist_all_multipart_uploads其中，initiate_uploader、recover_uploader返回Uploader對(duì)象。list_all_multipart_uploads返回Uploader list。initiate_uploader用于新建Multipart Upload任務(wù)，可直接調(diào)用Uploader的成員方法start開(kāi)始上傳。recover_uploader和list_all_multipart_uploads返回的Uploader用于續(xù)傳Multipart

18、 Upload任務(wù)，應(yīng)調(diào)用Uploader的成員方法resume繼續(xù)上傳。成員變量Uploader對(duì)象包含了Multipart Upload的JSON描述中的所有字段，其中JSON標(biāo)簽與變量之間的轉(zhuǎn)換關(guān)系如下表所示，各個(gè)字段的具體含義請(qǐng)參考API文檔4.3.5一節(jié)的返回體部分。JSON標(biāo)簽變量名類型ArchiveDescriptiondescriptionstringCreationDatecreation_datestringMultipartUploadIdidstringPartSizeInBytespart_sizeintPropertysize_completed已上傳的字節(jié)數(shù)。成員

19、方法start開(kāi)始上傳任務(wù)。定義def start(self)參數(shù)None返回值String：Archive ID resume恢復(fù)上傳任務(wù)。定義def resume(self, file_path)參數(shù)file_path：string待上傳的文件路徑。返回值String：Archive ID cancel取消上傳任務(wù)。定義def cancel(self)參數(shù)None返回值NoneJobJob是Job任務(wù)的抽象。根據(jù)下載文件的大小，Job內(nèi)部會(huì)自動(dòng)進(jìn)行分塊并行下載，并實(shí)現(xiàn)了斷點(diǎn)續(xù)傳和簡(jiǎn)單的 出錯(cuò)重試。在使用時(shí)，用戶需要注意Job任務(wù)并不是實(shí)時(shí)完成的（參見(jiàn)OAS API文檔-1.1.6節(jié)），用戶

20、應(yīng)調(diào)用Job的成員方法update_status更新任務(wù)狀態(tài)，并通過(guò)檢查成員變量completed確認(rèn)任務(wù)是否完成。當(dāng)任務(wù)完成時(shí)，可 通過(guò)調(diào)用download_to_file或download_by_range開(kāi)始下載。用戶也可直接設(shè)置download_to_file和download_by_range方法的block參數(shù)，當(dāng)block為True時(shí)，接口內(nèi)部會(huì)循環(huán)等待至Job完成再開(kāi)始下載，用戶不需調(diào)用手工更新任務(wù)狀態(tài)。對(duì)于未完成的下載任務(wù)，Job內(nèi)部會(huì)自動(dòng)創(chuàng)建一個(gè)進(jìn)度存儲(chǔ)文件，該進(jìn)度文件路徑為用戶指定的文件保存路徑加 上.oas后綴。若用戶希望重新下載整個(gè)文件，不進(jìn)行續(xù)傳，可以手動(dòng)刪除該進(jìn)度

21、文件，否則應(yīng)保留該文件，當(dāng) 任務(wù)完成時(shí)，該文件會(huì)自動(dòng)刪除。成員變量Job對(duì)象包含了Job的JSON描述中的所有字段，其中JSON標(biāo)簽與變量之間的轉(zhuǎn)換關(guān)系如下表所示，各個(gè)字段的 具體含義請(qǐng)參考API文檔4.4.4一節(jié)的返回體部分。JSON標(biāo)簽變量名類型ActionactionstringArchiveContentEtagetagstringArchiveIdarchive_idstringArchiveSizeInBytesarchive_sizeintCompletedcompletedbooleanCompletionDatecompletion_datestringCreationDat

22、ecreation_datestringInventorySizeInBytesinventory_sizeintJobDescriptiondescriptionstringJobIdidstringStatusCodestatus_codestringStatusMessagestatus_messagestringPropertysize_completed已下載的字節(jié)數(shù)成員方法update_status更新Job的任務(wù)狀態(tài)。定義def update_status(self)參數(shù)None返回值Nonedownload_by_range下載指定字節(jié)范圍到文件。定義def download_

23、by_range(self, byte_range, file_path=None, file_obj=None, chunk_size=None, block=True)參數(shù)byte_range：tuple長(zhǎng)度為2，兩個(gè)元素分別為字節(jié)長(zhǎng)度的起點(diǎn)和終點(diǎn)（含）。file_path：string file_obj：file object二選一參數(shù)，下載到指定的文件路徑或保存到指定的文件對(duì)象。當(dāng)兩個(gè)參數(shù)均提供時(shí)，結(jié)果不確定。chunk_size：int可選參數(shù)。每次讀寫的塊大小，默認(rèn)為1048576（1MB）。block：boolean可選參數(shù)。當(dāng)block為False時(shí)，直接開(kāi)始下載，若Job未完

24、成會(huì)拋出異常。當(dāng)block為True時(shí)，循環(huán)等 待至Job完成，再開(kāi)始下載。默認(rèn)為True。download_to_file下載Job任務(wù)輸出到指定文件路徑。定義def download_to_file(self, file_path, chunk_size=None, block=True)參數(shù)file_path：string文件保存的路徑。chunk_size：int可選參數(shù)。每次讀寫的塊大小，默認(rèn)為1048576（1MB）。block：int可選參數(shù)。當(dāng)block為False時(shí)，直接開(kāi)始下載，若Job未完成會(huì)拋出異常。當(dāng)block為True時(shí)，循環(huán)等 待至Job完成，再開(kāi)始下載。默認(rèn)為T

25、rue。說(shuō)明ResponseOASResponse是HttpResponse的簡(jiǎn)單抽象。OASResponse是字典對(duì)象，HttpResponse中的頭部信息以鍵值對(duì)的形式存儲(chǔ)在OASResponse中。對(duì)于類型為JSON的響應(yīng)，OASResponse會(huì)自動(dòng)解析JSON數(shù)據(jù)并保存為字典。對(duì)于類型為二進(jìn)制流的響應(yīng)，可通過(guò)成員方法read讀取返回體中的數(shù)據(jù)。Exceptions根據(jù)出錯(cuò)原因的不同，SDK把異常分為兩種不同類型，分別為OAServerError，和OASClientError。OASServerErrorOASServerError是指一次完整的HTTP請(qǐng)求中，服務(wù)器返回了錯(cuò)誤響應(yīng)。

26、各個(gè)成員變量的含義見(jiàn)下表。具體錯(cuò)誤信息請(qǐng)參閱API文檔第5節(jié)錯(cuò)誤響應(yīng)。成員變量類型含義headersdictHTTP響應(yīng)中的頭部，以鍵值對(duì)存儲(chǔ)，所有鍵均為小寫request_idstring出錯(cuò)的請(qǐng)求的ID值，見(jiàn)API文檔2.3.3節(jié)statusintHTTP狀態(tài)碼codestring錯(cuò)誤代碼，見(jiàn)API文檔2.3.3節(jié)typestring錯(cuò)誤類型，見(jiàn)API文檔2.3.3節(jié)messagestring錯(cuò)誤信息，見(jiàn)API文檔2.3.3節(jié)OASClientErrrorOASClientError表示客戶端異常，可能原因包括網(wǎng)絡(luò)連接出錯(cuò)、文件讀寫出錯(cuò)等，具體出錯(cuò)原因可通過(guò)查看成員變量message獲得。

27、異常僅作為標(biāo)記錯(cuò)誤類型，沒(méi)有實(shí)現(xiàn)額外的方法。此外，UploadArchiveError、DownloadArchiveError和HashDoesNotMatchError均繼承于OASClientError，作為更細(xì)一級(jí)的異常分類，分別代表上傳出錯(cuò)、下載出錯(cuò)和校驗(yàn)出錯(cuò)。Utilsutils中包含的是高級(jí)接口所使用的公共工具方法，用戶在開(kāi)發(fā)時(shí)可直接使用這些方法。文件操作is_file_like判斷指定對(duì)象是否支持read操作。定義def is_file_like(obj)參數(shù)obj：object返回值booleancontent_length根據(jù)輸入類型的不同，自動(dòng)獲取目標(biāo)的長(zhǎng)度。對(duì)于無(wú)法處理

28、的類型，拋出ValueError異常。定義def content_length(content)參數(shù)content返回值intopen_file當(dāng)提供file_obj參數(shù)時(shí)，返回file_obj；否則以mode默認(rèn)打開(kāi)file_path。定義def open_file(file_path=None, file_obj=None, mode=r)參數(shù)file_path：string file_obj：file object mode：string可選參數(shù)。打開(kāi)模式，默認(rèn)為rb。返回值file objectRange操作range_size計(jì)算指定字節(jié)范圍的長(zhǎng)度。定義def range_size(

29、byte_range)參數(shù)byte_range：tuple長(zhǎng)度為2，元素分別為字節(jié)長(zhǎng)度的起點(diǎn)和終點(diǎn)（含）。返回值intcalc_num_part計(jì)算長(zhǎng)度為size_total的文件，以part_size長(zhǎng)度進(jìn)行分塊的總分塊數(shù)。定義def calc_num_part(part_size, size_total)參數(shù)part_size：intPart的字節(jié)長(zhǎng)度。size_total：int文件總字節(jié)長(zhǎng)度。返回值intcalc_ranges計(jì)算長(zhǎng)度為size_total的文件，以part_size長(zhǎng)度進(jìn)行分塊的所有分塊字節(jié)范圍。定義def calc_ranges(part_size, size_to

30、tal)參數(shù)part_size：intPart的字節(jié)長(zhǎng)度。size_total：int文件總字節(jié)長(zhǎng)度。返回值tuple list：每個(gè)元組長(zhǎng)度為2，分別為分塊的字節(jié)起點(diǎn)和終點(diǎn)（含）。校驗(yàn)碼計(jì)算校驗(yàn)碼是歸檔存儲(chǔ)用于判斷archive完整性的手段，etag與tree-etag是校驗(yàn)碼的兩種方式。本節(jié)中compute_etag_from_string、compute_etag_from_file、compute_etag_from_file、compute_etag_from_file_obj三個(gè)函數(shù)中的任何一個(gè)函數(shù)可以用來(lái)計(jì)算etag校驗(yàn)碼，、compute_tree_etag_from_file

31、、compute_tree_etag_from_file_obj、compute_combine_tree_etag_from_list幾個(gè)函數(shù)都是用來(lái)計(jì)算tree-etag校驗(yàn)碼的?？梢酝瑫r(shí)計(jì)算出etag、tree-etag兩個(gè)校驗(yàn)碼，并 通過(guò)數(shù)組返回。compute_etag_from_string計(jì)算指定字符串的etag。定義def compute_etag_from_string(content)參數(shù)content：string待計(jì)算的字符串。返回值string說(shuō)明compute_etag_from_file計(jì)算指定文件的etag。定義def compute_etag_from_fil

32、e(file_path, offset=0, size=None, chunk_size=1048576)參數(shù)file_path：string待計(jì)算的文件路徑。offset：int可選參數(shù)。計(jì)算的字節(jié)起始點(diǎn)（含），默認(rèn)為0。size：int可選參數(shù)。待計(jì)算的字節(jié)長(zhǎng)度，默認(rèn)為offset起的所有字節(jié)的長(zhǎng)度。chunk_size：int可選參數(shù)。每次讀取的塊大小，默認(rèn)為1048576（1MB）。返回值stringcompute_etag_from_file_obj計(jì)算指定文件對(duì)象的etag。定義def compute_etag_from_file_obj(file_obj, offset=0, s

33、ize=None, chunk_size=1048576)參數(shù)file_obj：file object待計(jì)算的文件對(duì)象。offset：int可選參數(shù)。計(jì)算的字節(jié)起始點(diǎn)（含），默認(rèn)為0。size：int可選參數(shù)。待計(jì)算的字節(jié)長(zhǎng)度，默認(rèn)為offset起的所有字節(jié)的長(zhǎng)度。chunk_size：int可選參數(shù)。每次讀取的塊大小，默認(rèn)為1048576（1MB）。返回值stringcompute_tree_etag_from_file計(jì)算指定文件的tree-etag校驗(yàn)碼。定義def compute_tree_etag_from_file(file_path, offset=0, size=None, c

34、hunk_size=1048576)參數(shù)file_path：string待計(jì)算的文件路徑。offset：int可選參數(shù)。計(jì)算的字節(jié)起始點(diǎn)（含），默認(rèn)為0。size：int可選參數(shù)。待計(jì)算的字節(jié)長(zhǎng)度，默認(rèn)為offset起的所有字節(jié)的長(zhǎng)度。chunk_size：int可選參數(shù)。每次讀取的塊大小，默認(rèn)為1048576（1MB）。返回值stringcompute_tree_etag_from_file_obj計(jì)算指定文件對(duì)象的tree-etag。定義def compute_tree_etag_from_file_obj(file_obj, offset=0, size=None, chunk_size

35、=1048576)參數(shù)file_obj：file object待計(jì)算的文件對(duì)象。offset：int可選參數(shù)。計(jì)算的字節(jié)起始點(diǎn)（含），默認(rèn)為0。size：int可選參數(shù)。待計(jì)算的字節(jié)長(zhǎng)度，默認(rèn)為offset起的所有字節(jié)的長(zhǎng)度。chunk_size：int可選參數(shù)。每次讀取的塊大小，默認(rèn)為1048576（1MB）。返回值stringcompute_combine_tree_etag_from_list根據(jù)各個(gè)分塊的tree-etag所組成的list，計(jì)算整個(gè)文件的校驗(yàn)碼。定義def compute_combine_tree_etag_from_list(tree_etag_list)參數(shù)tree

36、_etag_list：list列表元素為每個(gè)分塊的tree-etag。返回值stringcompute_hash_from_file計(jì)算指定文件的etag及tree-etag校驗(yàn)碼。消息服務(wù)/API使用手冊(cè)消息服務(wù)/API使用手冊(cè)定義def compute_hash_from_file(file_path, offset=0, size=None, chunk_size=1048576)參數(shù)file_path：string待計(jì)算的文件路徑。offset：int可選參數(shù)。計(jì)算的字節(jié)起始點(diǎn)（含），默認(rèn)為0。size：int可選參數(shù)。待計(jì)算的字節(jié)長(zhǎng)度，默認(rèn)為offset起的所有字節(jié)的長(zhǎng)度。chunk

37、_size：int可選參數(shù)。每次讀取的塊大小，默認(rèn)為1048576（1MB）。返回值(string,string)返回的是兩個(gè)校驗(yàn)碼數(shù)組：(etag，tree-etag)compute_hash_from_file_obj計(jì)算指定文件對(duì)象的etag及tree-etag校驗(yàn)碼。定義def compute_hash_from_file_obj(file_obj, offset=0, size=None, chunk_size=1048576)參數(shù)file_obj：file object待計(jì)算的文件對(duì)象。offset：int可選參數(shù)。計(jì)算的字節(jié)起始點(diǎn)（含），默認(rèn)為0。size：int可選參數(shù)。待計(jì)算

38、的字節(jié)長(zhǎng)度，默認(rèn)為offset起的所有字節(jié)的長(zhǎng)度。chunk_size：int可選參數(shù)。每次讀取的塊大小，默認(rèn)為1048576（1MB）。返回值(string, string)返回的是兩個(gè)校驗(yàn)碼數(shù)組：(etag，tree-etag)低級(jí)接口類OASAPI是歸檔存儲(chǔ) API的基礎(chǔ)實(shí)現(xiàn)，其開(kāi)放的接口和API手冊(cè)所描述的RESTful接口分別一一對(duì)應(yīng)。OASAPI的實(shí)例化需要提供服務(wù)器地址（參見(jiàn)OAS API手冊(cè)-2.1.1服務(wù)地址）和可選的端口，以及用戶認(rèn)證信息，包括Access Key ID和Access Key Secret。OASAPI所開(kāi)放的所有接口均返回對(duì)象HTTPResponse，下文

39、中res默認(rèn)指HTTPResponse對(duì)象。用戶可通過(guò)獲取返回頭部參數(shù)或res.read()獲取返回體。對(duì)于HTTP返 回體格式為JSON的數(shù)據(jù)，下文以rjson表示解析后的JSON數(shù)據(jù)。關(guān)于HTTPResponse的更詳細(xì)使用，請(qǐng)參見(jiàn)Python官方文檔關(guān)于httplib的說(shuō)明。Vault操作創(chuàng)建Vault定義def create_vault(self, vault_name)參數(shù)vault_name：stringVault的名稱，名稱應(yīng)遵守API手冊(cè)4.1.1節(jié)中Vault命名規(guī)范。返回值HTTPResponse說(shuō)明創(chuàng)建指定名稱的Vault，并返回Vault ID?？赏ㄟ^(guò)res.statu

40、s檢查調(diào)用是否成功，對(duì)于成功的操作，可通過(guò)res.getheader(x-oas-vault-id)獲取成功創(chuàng)建的Vault的ID值。刪除Vault定義def delete_vault(self, vault_id)參數(shù)vault_id：string待刪除Vault的ID。返回值HTTPResponse說(shuō)明刪除指定ID的Vault。成功的調(diào)用要求給定的Vault ID存在，并且指定的Vault為空，即不包含任何Archive?？赏ㄟ^(guò)res.status檢查調(diào)用是否成功。獲取Vault信息定義def get_vault_desc(self, vault_id)參數(shù)vault_id：stringV

41、ault的ID。返回值HTTPResponse說(shuō)明獲取指定ID的Vault描述。對(duì)于成功的調(diào)用，可通過(guò)解析HTTP返回體中的JSON獲取相關(guān)信息，JSON的各個(gè)字 段解釋詳見(jiàn)API手冊(cè)4.1.3節(jié)中的返回體。Vault列表定義def list_vault(self, marker=None, limit=None)參數(shù)marker：string可選參數(shù)。指明所請(qǐng)求的列表起點(diǎn)，與API手冊(cè)4.1.4節(jié)中的請(qǐng)求參數(shù)描述一致。limit：int可選參數(shù)。限制返回的Vault數(shù)量，與API手冊(cè)4.1.4節(jié)中的請(qǐng)求參數(shù)描述一致。返回值HTTPResponse說(shuō)明獲取用戶的Vault列表。對(duì)于成功的調(diào)用，

42、可通過(guò)解析HTTP返回體中的JSON獲取相關(guān)信息?？赏ㄟ^(guò)marker參數(shù)。rjsonVaultList是Vault描述 信息數(shù)組。關(guān)于JSON的各個(gè)字段的更詳細(xì)解釋見(jiàn)API手冊(cè)4.1.4節(jié)中的返回體。Archive操作上傳Archive定義def post_archive(self, vault_id, content, etag, tree_etag, desc=None)def post_archive_from_reader(self, vault_id, reader, content_length, etag, tree_etag, desc=None)參數(shù)vault_id：stri

43、ng指定保存Archive的Vault的ID。content待上傳的字節(jié)流。MongoDBMongoDB/最佳實(shí)踐reader實(shí)現(xiàn)了read接口的對(duì)象，如file object。content_length：int待上傳的Archive的字節(jié)長(zhǎng)度。etag：string待上傳的文件的etag校驗(yàn)碼，詳細(xì)計(jì)算方法請(qǐng)參閱API文檔2.5.1一節(jié)。tree_etag：string待上傳文件的tree_etag校驗(yàn)碼。desc：string可選參數(shù)。Archive的描述信息。返回值HTTPResponse說(shuō)明上傳Archive至指定的Vault，并返回Archive ID。對(duì)于已存在于內(nèi)存的數(shù)據(jù)，可直

44、接調(diào)用post_archive；對(duì)于文件上傳，可使用post_archive_from_reader。所有超出content_length長(zhǎng)度的數(shù)據(jù)會(huì)被忽略。對(duì)于成功的操作，可通過(guò)res.getheader(x-oas-archive-id)獲取相應(yīng)的Archive ID。關(guān)于Archive上傳的限制，請(qǐng)參見(jiàn)OAS API手冊(cè)-4.2.1節(jié)的描述。刪除Archive定義def delete_archive(self, vault_id, archive_id)參數(shù)vault_id：string待刪除的Archive所屬Vault的ID。archive_id：string歸檔存儲(chǔ)/最佳實(shí)踐歸檔存

45、儲(chǔ)/最佳實(shí)踐待刪除的Archive的ID。返回值HTTPResponse說(shuō)明刪除指定的Archive?？赏ㄟ^(guò)檢查res.status判斷調(diào)用是否成功。Multipart Upload操作關(guān)于Multipart Upload操作的完整流程請(qǐng)參考API手冊(cè)1.1.4節(jié)。初始化Multipart Upload任務(wù)定義def create_multipart_upload(self, vault_id, partsize, desc=None)參數(shù)vault_id：string上傳任務(wù)所屬Vault的ID。partsize：int指定Part的字節(jié)長(zhǎng)度，請(qǐng)參閱API手冊(cè)4.3.1節(jié)中描述關(guān)于Part長(zhǎng)

46、度的限制。desc：string可選參數(shù)，Archive的描述信息。返回值HTTPResponse說(shuō)明新建Multipart Upload任務(wù)，并返回Upload ID。對(duì)于成功的操作，可通過(guò)res.getheader(x-oas-multipart- upload-id)獲得任務(wù)ID，用于后續(xù)的Part上傳。獲取Multipart Upload任務(wù)列表定義彈性伸縮/常見(jiàn)問(wèn)題彈性伸縮/常見(jiàn)問(wèn)題def list_multipart_upload(self, vault_id, marker=None, limit=None)參數(shù)vault_id：string待查詢的目標(biāo)Vault的ID。mark

47、er：string可選參數(shù)，指明所請(qǐng)求的列表起點(diǎn)，與API手冊(cè)4.3.2節(jié)中的請(qǐng)求參數(shù)描述一致。limit：int可選參數(shù)，限制返回的任務(wù)數(shù)量，與API手冊(cè)4.3.2節(jié)中的請(qǐng)求參數(shù)描述一致。返回值HTTPResponse說(shuō)明獲取指定Vault下Multipart Upload任務(wù)。對(duì)于成功地調(diào)用，可通過(guò)解析HTTP返回體中的JSON獲取相關(guān)信息。可通過(guò)rjsonMarker判斷是否還有后續(xù)列表，該字段可用于下次請(qǐng)求的marker參數(shù)。rjsonUploadsList是任務(wù)描述信息數(shù)組。關(guān)于JSON的各個(gè)字段的更詳細(xì)解釋見(jiàn)API手冊(cè)4.3.2節(jié)中的返回體。刪除Multipart Upload任務(wù)

48、定義def delete_multipart_upload(self, vault_id, upload_id)參數(shù)vault_id：string待刪除的任務(wù)所屬Vault的ID。upload_id：string待刪除任務(wù)的ID。返回值HTTPResponse說(shuō)明刪除指定任務(wù)?？赏ㄟ^(guò)res.status檢查調(diào)用是否成功。Part上傳定義def post_multipart(self, vault_id, upload_id, content, prange, etag, tree_etag)def post_multipart_from_reader(self, vault_id, uploa

49、d_id, reader, content_length, prange, etag, tree_etag)參數(shù)vault_id：string上傳任務(wù)所屬Vault的ID。upload_id：string待上傳的Part所屬的任務(wù)ID。content：string待上傳的字節(jié)流。reader實(shí)現(xiàn)了read接口的對(duì)象，如file object。partsize：int待上傳的Part的字節(jié)長(zhǎng)度。prange：string待上傳的Part在整個(gè)Archive中的字節(jié)范圍，字節(jié)以0開(kāi)始計(jì)數(shù)，格式為start-end。prange所指定范 圍的長(zhǎng)度應(yīng)與partsize一致，所有超出partsize長(zhǎng)度

50、的數(shù)據(jù)會(huì)被忽略。除最后一個(gè)Part外，partsize應(yīng) 與初始化Multipart Upload任務(wù)時(shí)所指定的partsize一致。參數(shù)定義與API手冊(cè)4.3.4一節(jié)中描述部分一致。etag：string容器服務(wù)/服務(wù)編排文檔容器服務(wù)/服務(wù)編排文檔待上傳的Part的etag校驗(yàn)碼，詳細(xì)計(jì)算方法請(qǐng)參閱API文檔2.5.2一節(jié)。tree_etag：string待上傳Part的tree_etag校驗(yàn)碼。返回值HTTPResponse說(shuō)明上傳Archive中指定字節(jié)范圍的Part，注意prange定義應(yīng)符合API手冊(cè)指定的規(guī)范。對(duì)于已存在于內(nèi)存的數(shù)據(jù)，可直接調(diào)用post_multipart；對(duì)于文件

51、上傳，可使用post_multipart_from_reader?？赏ㄟ^(guò)res.status檢查上傳是否成功。獲取Part列表定義def list_multipart(self, vault_id, upload_id, marker=None, limit=None)參數(shù)vault_id：string上傳任務(wù)所屬Vault的ID。upload_id：string待查詢的目標(biāo)Multipart Upload任務(wù)的ID。marker：string可選參數(shù)。指明所請(qǐng)求的Part列表起點(diǎn)，與API手冊(cè)4.3.5節(jié)中的請(qǐng)求參數(shù)描述一致。limit：int可選參數(shù)。限制返回的Part數(shù)量，與API手冊(cè)4

52、.3.5節(jié)中的請(qǐng)求參數(shù)描述一致。返回值HTTPResponse說(shuō)明獲取目標(biāo)Vault下指定Multipart Upload任務(wù)已上傳完成的Part列表。對(duì)于成功的調(diào)用，可通過(guò)解析HTTP返回體中的JSON獲取相關(guān)信息?？赏ㄟ^(guò)rjsonMarker判斷是否還有后續(xù)列表，該字段可用于下次請(qǐng)求的是Part描述信息數(shù)組。關(guān)于JSON的各個(gè)字段的更詳細(xì)解釋見(jiàn)API手冊(cè)4.3.5節(jié)中的返 回體。Part合并定義def complete_multipart_upload(self, vault_id, upload_id, filesize, tree_etag)參數(shù)vault_id：string上傳任務(wù)所

53、屬Vault的ID。upload_id：string所要進(jìn)行合并的Multipart Upload任務(wù)ID。filesize：int所要進(jìn)行合并的Archive總字節(jié)大小。tree_etag：string待上傳文件的tree-etag校驗(yàn)碼。返回值HTTPResponse說(shuō)明對(duì)某個(gè)已完成所有Part上傳的任務(wù)進(jìn)行合并?？赏ㄟ^(guò)res.status檢查合并是否成功。對(duì)于成功的操作，可通過(guò)res.getheader(x-oas-archive-id)獲取成功合并后創(chuàng)建的Archive ID。Job操作初始化Job任務(wù)定義def create_job(self, vault_id, job_type,

54、 archive_id=None, desc=None, byte_range=None)def create_oss_transfer_job(self, vault_id, job_type, osshost, bucket, object, archive_id=None, desc=None)參數(shù)vault_idJob任務(wù)所屬Vault的ID。job_type任務(wù)類型?？蛇x值為archive-retrieval和inventory-retrieval。與API文檔4.4.1一節(jié)中的請(qǐng)求體中的Type描述一致。archive_id當(dāng)job_type為inventory-retrieval

55、時(shí)，忽略該參數(shù)。當(dāng) job_type為archive-retrieval時(shí)，該參數(shù)是指待下載的Archive的ID。desc可選參數(shù)。Job任務(wù)的描述信息。byte_range可選參數(shù)。待下載的Archive字節(jié)范圍，與API文檔4.4.1一節(jié)中的請(qǐng)求體中得RetrievalByteRange描 述一致。osshost當(dāng)job_type為pull-from-oss或push-to-oss時(shí)，該參數(shù)是指轉(zhuǎn)儲(chǔ)job的oss域名。bucket當(dāng)job_type為pull-from-oss或push-to-oss時(shí)，該參數(shù)是指轉(zhuǎn)儲(chǔ)job的oss bucket。object當(dāng)job_type為pull-

56、from-oss或push-to-oss時(shí)，該參數(shù)是指轉(zhuǎn)儲(chǔ)job的 oss Object。說(shuō)明新建Job任務(wù)并返回Job ID，根據(jù)所要操作的類型選擇合適的job_type，當(dāng)任務(wù)類型是archive-retrieval時(shí)，需要提供目標(biāo)Archive的ID，以及可選的下載范圍byte_range?？赏ㄟ^(guò)res.status檢查新建是否成功。對(duì)于成功新 建的Job任務(wù)，可通過(guò)res.getheader(x-oas-job-id)獲取JobID，該ID可用于后續(xù)Job任務(wù)狀態(tài)查詢。create_oss_transfer_job函數(shù)適用于在歸檔存儲(chǔ)與OSS產(chǎn)品之間的跨產(chǎn)品數(shù)據(jù)歸檔、提檔，幫助用戶在阿

57、里云 上實(shí)現(xiàn)無(wú)中轉(zhuǎn)的數(shù)據(jù)遷移。Job Output下載定義def fetch_job_output(self, vault_id, job_id, orange=None)參數(shù)vault_id：string目標(biāo)Job任務(wù)所屬Vault的ID。job_id：string目標(biāo)Job的ID。orange：string可選參數(shù)。所要下載的Job輸出字節(jié)范圍，格式為start-end，字節(jié)以0開(kāi)始計(jì)數(shù)。參數(shù)定義與API手冊(cè)5.4.3一節(jié)中描述部分一致。返回值HTTPResponse說(shuō)明下載已完成的Job任務(wù)輸出的結(jié)果。對(duì)于Job類型為inventory-retrieval的任務(wù)，rjsonArchive

58、List是所查詢 的Archive列表信息。關(guān)于JSON的各個(gè)字段的更詳細(xì)解釋見(jiàn)API手冊(cè)5.4.2一節(jié)中返回體的描述。對(duì)于Job類型為archive-retrieval的任務(wù)，HTTP返回體是所請(qǐng)求范圍的字節(jié)。對(duì)于大文件的下載，建議設(shè)置orange參數(shù)分塊下載。獲取Job列表定義def list_job(self, vault_id, marker=None, limit=None)參數(shù)vault_id：string待查詢的Vault的ID。marker：string可選參數(shù)，指明所請(qǐng)求的Job列表起點(diǎn)，與API手冊(cè)5.4.3節(jié)中的請(qǐng)求參數(shù)描述一致。limit：int可選參數(shù)，限制返回的Jo

59、b數(shù)量，與API手冊(cè)5.4.3節(jié)中的請(qǐng)求參數(shù)描述一致。返回值HTTPResponse說(shuō)明獲取指定Vault下的Job列表。對(duì)于成功的調(diào)用，可通過(guò)解析HTTP返回體中的JSON獲取相關(guān)信息?？赏ㄟ^(guò)marker參數(shù)。rjsonJobList是Job描述信 息數(shù)組。關(guān)于JSON的各個(gè)字段的更詳細(xì)解釋見(jiàn)API手冊(cè)5.4.3節(jié)中的返回體。Job任務(wù)狀態(tài)查詢定義def get_jobdesc(self, vault_id, job_id)參數(shù)vault_id：string目標(biāo)Job任務(wù)所屬Vault的ID。job_id：string目標(biāo)Job任務(wù)的ID。返回值HTTPResponse說(shuō)明查看指定ID的Jo

60、b任務(wù)狀態(tài)。對(duì)于成功的調(diào)用，可通過(guò)解析HTTP返回體中的JSON獲取相關(guān)信息，JSON的各個(gè) 字段解釋詳見(jiàn)API手冊(cè)4.4.4節(jié)中的返回體。數(shù)據(jù)傳輸/常見(jiàn)問(wèn)題FAQ數(shù)據(jù)傳輸/常見(jiàn)問(wèn)題FAQ命令行工具oascmd.pyPython SDK，還有分別與 歸檔存儲(chǔ) API 文檔描述的接口一一對(duì)應(yīng)的底層命令。其中，內(nèi)的參數(shù)為可選參數(shù)。字符串前綴 oas:/ 僅僅作為資源標(biāo)識(shí)，沒(méi)有其他含義。除了特別說(shuō)明外，所有結(jié)果均直接輸出至命令行，輸出結(jié)果為友好的自解釋可讀文本，因此下文不再對(duì) oascmd.py 輸出進(jìn)行詳細(xì)說(shuō)明。授權(quán)設(shè)置oascmd.py 使用前需要進(jìn)行授權(quán)信息的配置格式config -h -ho