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

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

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

3、接口的實(shí)現(xiàn)，在其基礎(chǔ)上增加相應(yīng)的定制功能，同時，歡迎用戶把相關(guān)需求反映給 歸檔存儲 開發(fā)團(tuán)隊(duì)，對于合理的需求，會在接下來的版本中得到實(shí)現(xiàn)。若用戶需要更細(xì)粒度的操作，則可直接調(diào)用低級接 口，根據(jù)實(shí)際使用場景進(jìn)行封裝。郵件推送/SMTP接口說明郵件推送/SMTP接口說明Demo程序參考最佳實(shí)踐-Python。高級接口高級接口中的所有方法均為阻塞操作，在操作沒有完成之前不會返回。所有接口都可能會拋出兩種異常，分別 為OASServerError和OASClientError，具體描述請參閱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對象，需要通過Vault的類方法，其中create_vault、get_vault_by_id和get_vault_by_name是簡單工廠方法，返回Vault對象，list_all_vaults返回Vault list。這些類方法都需要以O(shè)ASAPI對象作為參數(shù)（參見低級接口概述部分）。對于上傳操作，可以直接調(diào)用成員方法upload_archive，接口內(nèi)部會根據(jù)文件大小自動選擇Normal Upload或Multipart Upload

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

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

8、PI對象作為參數(shù)，OASAPI的構(gòu)造請參閱低級接口的概述部分。create_vault類方法。新建指定名稱的Vault。定義def create_vault(cls, api, name)參數(shù)api：OASAPI name：string待新建的Vault的名稱，名稱應(yīng)遵守API手冊4.1.1節(jié)中Vault命名規(guī)范。返回值Vaultget_vault_by_id類方法。獲取指定ID的Vault。定義def get_vault_by_id(cls, api, vault_id)參數(shù)DRDS/服務(wù)條款與價格模型DRDS/服務(wù)條款與價格模型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è)級分布式應(yīng)用服務(wù) EDAS/API參考手冊企業(yè)級分布式應(yīng)用服務(wù) EDAS/AP

10、I參考手冊待刪除的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é)果，用戶不需要對Marker標(biāo)識進(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ù)。長度為2，元素分別為字節(jié)長度的起點(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)儲的archive_idosshost：stringjob的源oss域名HTTPDNS/接口參考手冊HTTPDNS/接口參考手冊bucket：stringjob任務(wù)的oss Bucketobject：stringjob任務(wù)的oss Objectdesc：string可選參數(shù)。Job任務(wù)的描述字段。返回值JobUploaderUploader是Multipart Upload任務(wù)的抽象。要獲取Uploader對象，可通過Va

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

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

19、方法start開始上傳任務(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)部會自動進(jìn)行分塊并行下載，并實(shí)現(xiàn)了斷點(diǎn)續(xù)傳和簡單的 出錯重試。在使用時，用戶需要注意Job任務(wù)并不是實(shí)時完成的（參見OAS API文檔-1.1.6節(jié)），用戶

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

21、文件，否則應(yīng)保留該文件，當(dāng) 任務(wù)完成時，該文件會自動刪除。成員變量Job對象包含了Job的JSON描述中的所有字段，其中JSON標(biāo)簽與變量之間的轉(zhuǎn)換關(guān)系如下表所示，各個字段的 具體含義請參考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長度為2，兩個元素分別為字節(jié)長度的起點(diǎn)和終點(diǎn)（含）。file_path：string file_obj：file object二選一參數(shù)，下載到指定的文件路徑或保存到指定的文件對象。當(dāng)兩個參數(shù)均提供時，結(jié)果不確定。chunk_size：int可選參數(shù)。每次讀寫的塊大小，默認(rèn)為1048576（1MB）。block：boolean可選參數(shù)。當(dāng)block為False時，直接開始下載，若Job未完

24、成會拋出異常。當(dāng)block為True時，循環(huán)等 待至Job完成，再開始下載。默認(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時，直接開始下載，若Job未完成會拋出異常。當(dāng)block為True時，循環(huán)等 待至Job完成，再開始下載。默認(rèn)為T

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

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

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

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

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

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

31、、compute_tree_etag_from_file_obj、compute_combine_tree_etag_from_list幾個函數(shù)都是用來計(jì)算tree-etag校驗(yàn)碼的?？梢酝瑫r計(jì)算出etag、tree-etag兩個校驗(yàn)碼，并 通過數(shù)組返回。compute_etag_from_string計(jì)算指定字符串的etag。定義def compute_etag_from_string(content)參數(shù)content：string待計(jì)算的字符串。返回值string說明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é)長度，默認(rèn)為offset起的所有字節(jié)的長度。chunk_size：int可選參數(shù)。每次讀取的塊大小，默認(rèn)為1048576（1MB）。返回值stringcompute_etag_from_file_obj計(jì)算指定文件對象的etag。定義def compute_etag_from_file_obj(file_obj, offset=0, s

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

36、_etag_list：list列表元素為每個分塊的tree-etag。返回值stringcompute_hash_from_file計(jì)算指定文件的etag及tree-etag校驗(yàn)碼。消息服務(wù)/API使用手冊消息服務(wù)/API使用手冊定義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é)長度，默認(rèn)為offset起的所有字節(jié)的長度。chunk

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

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

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

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

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

42、可通過解析HTTP返回體中的JSON獲取相關(guān)信息?？赏ㄟ^marker參數(shù)。rjsonVaultList是Vault描述 信息數(shù)組。關(guān)于JSON的各個字段的更詳細(xì)解釋見API手冊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接口的對象，如file object。content_length：int待上傳的Archive的字節(jié)長度。etag：string待上傳的文件的etag校驗(yàn)碼，詳細(xì)計(jì)算方法請參閱API文檔2.5.1一節(jié)。tree_etag：string待上傳文件的tree_etag校驗(yàn)碼。desc：string可選參數(shù)。Archive的描述信息。返回值HTTPResponse說明上傳Archive至指定的Vault，并返回Archive ID。對于已存在于內(nèi)存的數(shù)據(jù)，可直

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

45、儲/最佳實(shí)踐待刪除的Archive的ID。返回值HTTPResponse說明刪除指定的Archive?？赏ㄟ^檢查res.status判斷調(diào)用是否成功。Multipart Upload操作關(guān)于Multipart Upload操作的完整流程請參考API手冊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é)長度，請參閱API手冊4.3.1節(jié)中描述關(guān)于Part長

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

47、er：string可選參數(shù)，指明所請求的列表起點(diǎn)，與API手冊4.3.2節(jié)中的請求參數(shù)描述一致。limit：int可選參數(shù)，限制返回的任務(wù)數(shù)量，與API手冊4.3.2節(jié)中的請求參數(shù)描述一致。返回值HTTPResponse說明獲取指定Vault下Multipart Upload任務(wù)。對于成功地調(diào)用，可通過解析HTTP返回體中的JSON獲取相關(guān)信息?？赏ㄟ^rjsonMarker判斷是否還有后續(xù)列表，該字段可用于下次請求的marker參數(shù)。rjsonUploadsList是任務(wù)描述信息數(shù)組。關(guān)于JSON的各個字段的更詳細(xì)解釋見API手冊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說明刪除指定任務(wù)?？赏ㄟ^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接口的對象，如file object。partsize：int待上傳的Part的字節(jié)長度。prange：string待上傳的Part在整個Archive中的字節(jié)范圍，字節(jié)以0開始計(jì)數(shù)，格式為start-end。prange所指定范 圍的長度應(yīng)與partsize一致，所有超出partsize長度

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

51、上傳，可使用post_multipart_from_reader?？赏ㄟ^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ù)。指明所請求的Part列表起點(diǎn)，與API手冊4.3.5節(jié)中的請求參數(shù)描述一致。limit：int可選參數(shù)。限制返回的Part數(shù)量，與API手冊4

52、.3.5節(jié)中的請求參數(shù)描述一致。返回值HTTPResponse說明獲取目標(biāo)Vault下指定Multipart Upload任務(wù)已上傳完成的Part列表。對于成功的調(diào)用，可通過解析HTTP返回體中的JSON獲取相關(guān)信息。可通過rjsonMarker判斷是否還有后續(xù)列表，該字段可用于下次請求的是Part描述信息數(shù)組。關(guān)于JSON的各個字段的更詳細(xì)解釋見API手冊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說明對某個已完成所有Part上傳的任務(wù)進(jìn)行合并?？赏ㄟ^res.status檢查合并是否成功。對于成功的操作，可通過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ù)類型。可選值為archive-retrieval和inventory-retrieval。與API文檔4.4.1一節(jié)中的請求體中的Type描述一致。archive_id當(dāng)job_type為inventory-retrieval

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

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

57、里云 上實(shí)現(xiàn)無中轉(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開始計(jì)數(shù)。參數(shù)定義與API手冊5.4.3一節(jié)中描述部分一致。返回值HTTPResponse說明下載已完成的Job任務(wù)輸出的結(jié)果。對于Job類型為inventory-retrieval的任務(wù)，rjsonArchive

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

59、b數(shù)量，與API手冊5.4.3節(jié)中的請求參數(shù)描述一致。返回值HTTPResponse說明獲取指定Vault下的Job列表。對于成功的調(diào)用，可通過解析HTTP返回體中的JSON獲取相關(guān)信息?？赏ㄟ^marker參數(shù)。rjsonJobList是Job描述信 息數(shù)組。關(guān)于JSON的各個字段的更詳細(xì)解釋見API手冊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說明查看指定ID的Jo

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