高級接口__Python_SDK使用手冊_歸檔存儲-阿裏雲

高級接口中的所有方法均為阻塞操作，在操作沒有完成之前不會返回。所有接口都可能會拋出兩種異常，分別為OASServerError和OASClientError，具體描述請參閱Exceptions一節。

高級接口使用Python內置模塊logging輸出日誌，用戶可根據實際需要自由配置日誌輸出，以下例子是輸出INFO級別日誌到標準輸出的簡單配置。

import logging
import sys

handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(logging.Formatter('%(asctime)s %(message)s'))
handler.setLevel(logging.INFO)

log = logging.getLogger('oas.ease.uploader')
log.addHandler(handler)
log.setLevel(logging.INFO)

Vault

類Vault是用戶所有操作的入口點。要實例化Vault對象，需要通過Vault的類方法，其中create_vault、get_vault_by_id和get_vault_by_name是簡單工廠方法，返回Vault對象，list_all_vaults返回Vault list。這些類方法都需要以OASAPI對象作為參數（參見低級接口概述部分）。

對於上傳操作，可以直接調用成員方法upload_archive，接口內部會根據文件大小自動選擇Normal Upload或Multipart Upload方式，並實現了多線程並行上傳和失敗重試。對於Multipart Upload任務，用戶也可調用成員方法initiate_uploader獲得Uploader對象再進行上傳（參見Uploader一節）。使用後一種方法，用戶可獲得時機保存Multipart Upload的任務ID，若任務沒有成功完成，可在之後調用成員方法recover_uploader傳入任務ID進行續傳。用戶應根據業務需要選擇合適的方法。

對於下載操作，可調用成員方法retrieve_inventory或retrieve_archive獲得Job對象再進行下載（參見Job一節）。

下麵按照功能分組，介紹Vault的接口。

成員變量

Vault對象包含了Vault的JSON描述中的所有字段，其中JSON標簽與變量之間的轉換關係如下表所示，各個字段的具體含義請參考API文檔4.1.3一節的返回體部分。

JSON標簽	變量名	類型
CreationDate	creation_date	string
LastInventoryDate	last_inventory_date	string
NumberOfArchives	number_of_archives	int
SizeInBytes	size	int
VaultId	id	string
VaultName	name	string

構造方法

類Vault包含了三個簡單工廠方法用於構造Vault對象，三個類方法均需OASAPI對象作為參數，OASAPI的構造請參閱低級接口的概述部分。

create_vault

類方法。新建指定名稱的Vault。

定義

def create_vault(cls, api, name)

參數

api：OASAPI
name：string

待新建的Vault的名稱，名稱應遵守API手冊4.1.1節中Vault命名規範。

返回值

Vault

get_vault_by_id

類方法。獲取指定ID的Vault。

定義

def get_vault_by_id(cls, api, vault_id)

參數

api：OASAPI
vault_id：string

待檢索的Vault的ID。

返回值

Vault

get_vault_by_name

類方法。獲取指定名稱的Vault。

定義

def get_vault_by_name(cls, api, vault_name)

參數

api：OASAPI
vault_name：string

待檢索的Vault的名稱。

返回值

Vault

Vault刪除

delete_vault_by_id

類方法。刪除指定ID的Vault。

定義

def delete_vault_by_id(cls, api, vault_id)

參數

api：OASAPI
vault_id：string

待刪除的Vault的ID。

返回值

None

delete_vault_by_name

類方法。刪除指定名稱的Vault。

定義

def delete_vault_by_name(cls, api, vault_name)

參數

api：OASAPI
vault_name：string

待刪除的Vault的名稱。

返回值

None

delete

刪除當前Vault。

定義

def delete(self)

參數

None

返回值

None

狀態查詢

所有查詢方法默認返回全部的檢索結果，用戶不需要對Marker標識進行處理。

list_all_vaults

類方法。返回用戶持有的所有Vault。

定義

def list_all_vaults(cls, api)

參數

api：OASAPI

返回值

Vault list

list_all_multipart_uploads

返回Vault下的全部Multipart Upload任務。

定義

def list_all_multipart_uploads(self)

參數

None

返回值

Uploader list

list_all_jobs

返回Vault下的所有Job任務。

定義

def list_all_jobs(self)

參數

None

返回值

Job list

Archive操作

upload_archive

上傳指定文件到當前Valut，成功上傳後返回相應的Archive ID。

定義

def upload_archive(self, file_path, desc=None)

參數

file_path：string

待上傳的文件路徑。
desc：string

可選參數。Archive的描述字段。

返回值

string：Archive ID

initiate_uploader

新建Multipart Upload任務。

定義

def initiate_uploader(self, file_path, desc=None)

參數

file_path：string

待上傳的文件路徑。
desc：string

可選參數。Archive的描述字段。

返回值

Uploader

recover_uploader

續傳指定的Multipart Upload任務。

定義

def recover_uploader(self, upload_id)

參數

upload_id：string

Multipart Upload任務的ID。

返回值

Uploader

delete_archive

刪除指定ID的Archive。

定義

def delete_archive(self, archive_id)

參數

archive_id：string

待刪除的Archive的ID。

返回值

None

Job操作

get_job

獲取指定ID的Job任務。

定義

def get_job(self, job_id)

參數

job_id：string

Job任務的ID。

返回值

Job

retrieve_archive

新建類型為archive-retrieval的Job任務。

定義

def retrieve_archive(self, archive_id, desc=None, byte_range=None):

參數

archive_id：string

待查詢的Archive的ID。
desc：string

可選參數。Job任務的描述字段。
byte_range：tuple

可選參數。長度為2，元素分別為字節長度的起點和終點（含）。

返回值

Job

retrieve_inventory

新建類型為inventory-retrieval的Job任務。

定義

def retrieve_inventory(self, desc=None)

參數

desc：string

可選參數。Job任務的描述字段。

返回值

Job

pull_from_oss

新建類型為pull-from-oss的Job任務。

定義

def pull_from_oss(self, osshost, bucket, object, desc=None)

參數

osshost：string

job的源oss域名
bucket：string

job任務的oss Bucket
object：string

job任務的oss Object
desc：string

可選參數。Job任務的描述字段。

返回值

Job

push_to_oss

新建類型為push-to-oss的Job任務。

定義

def push_to_oss(self, archive_id, osshost, bucket, object, desc=None)

參數

archive_id：string

待轉儲的archive_id

osshost：string

job的源oss域名
bucket：string

job任務的oss Bucket
object：string

job任務的oss Object
desc：string

可選參數。Job任務的描述字段。

返回值

Job

Uploader

Uploader是Multipart Upload任務的抽象。

要獲取Uploader對象，可通過Vault的三個成員方法，包括：

initiate_uploader
recover_uploader
list_all_multipart_uploads

其中，initiate_uploader、recover_uploader返回Uploader對象。

list_all_multipart_uploads返回Uploader list。

initiate_uploader用於新建Multipart Upload任務，可直接調用Uploader的成員方法start開始上傳。

recover_uploader和list_all_multipart_uploads返回的Uploader用於續傳Multipart Upload任務，應調用Uploader的成員方法resume繼續上傳。

成員變量

Uploader對象包含了Multipart Upload的JSON描述中的所有字段，其中JSON標簽與變量之間的轉換關係如下表所示，各個字段的具體含義請參考API文檔4.3.5一節的返回體部分。

JSON標簽	變量名	類型
ArchiveDescription	description	string
CreationDate	creation_date	string
MultipartUploadId	id	string
PartSizeInBytes	part_size	int

Property

size_completed

已上傳的字節數。

成員方法

start

開始上傳任務。

定義

def start(self)

參數

None

返回值

String：Archive ID

resume

恢複上傳任務。

定義

def resume(self, file_path)

參數

file_path：string

待上傳的文件路徑。

返回值

String：Archive ID

cancel

取消上傳任務。

定義

def cancel(self)

參數

None

返回值

None

Job

Job是Job任務的抽象。根據下載文件的大小，Job內部會自動進行分塊並行下載，並實現了斷點續傳和簡單的出錯重試。

在使用時，用戶需要注意Job任務並不是實時完成的（參見《OAS API文檔-1.1.6節》），用戶應調用Job的成員方法update_status更新任務狀態，並通過檢查成員變量completed確認任務是否完成。當任務完成時，可通過調用download_to_file或download_by_range開始下載。用戶也可直接設置download_to_file和download_by_range方法的block參數，當block為True時，接口內部會循環等待至Job完成再開始下載，用戶不需調用手工更新任務狀態。

對於未完成的下載任務，Job內部會自動創建一個進度存儲文件，該進度文件路徑為用戶指定的文件保存路徑加上.oas後綴。若用戶希望重新下載整個文件，不進行續傳，可以手動刪除該進度文件，否則應保留該文件，當任務完成時，該文件會自動刪除。

成員變量

Job對象包含了Job的JSON描述中的所有字段，其中JSON標簽與變量之間的轉換關係如下表所示，各個字段的具體含義請參考API文檔4.4.4一節的返回體部分。

JSON標簽	變量名	類型
Action	action	string
ArchiveContentEtag	etag	string
ArchiveId	archive_id	string
ArchiveSizeInBytes	archive_size	int
Completed	completed	boolean
CompletionDate	completion_date	string
CreationDate	creation_date	string
InventorySizeInBytes	inventory_size	int
JobDescription	description	string
JobId	id	string
StatusCode	status_code	string
StatusMessage	status_message	string

Property

size_completed

已下載的字節數

成員方法

update_status

更新Job的任務狀態。

定義

def update_status(self)

參數

None

返回值

None

download_by_range

下載指定字節範圍到文件。

定義

def download_by_range(self, byte_range, file_path=None, file_obj=None, chunk_size=None, block=True)

參數

byte_range：tuple

長度為2，兩個元素分別為字節長度的起點和終點（含）。
file_path：string
file_obj：file object

二選一參數，下載到指定的文件路徑或保存到指定的文件對象。當兩個參數均提供時，結果不確定。
chunk_size：int

可選參數。每次讀寫的塊大小，默認為1048576（1MB）。
block：boolean

可選參數。當block為False時，直接開始下載，若Job未完成會拋出異常。當block為True時，循環等待至Job完成，再開始下載。默認為True。

download_to_file

下載Job任務輸出到指定文件路徑。

定義

def download_to_file(self, file_path, chunk_size=None, block=True)

參數

file_path：string

文件保存的路徑。
chunk_size：int

可選參數。每次讀寫的塊大小，默認為1048576（1MB）。
block：int

可選參數。當block為False時，直接開始下載，若Job未完成會拋出異常。當block為True時，循環等待至Job完成，再開始下載。默認為True。

說明

Response

OASResponse是HttpResponse的簡單抽象。OASResponse是字典對象，HttpResponse中的頭部信息以鍵值對的形式存儲在OASResponse中。對於類型為JSON的響應，OASResponse會自動解析JSON數據並保存為字典。對於類型為二進製流的響應，可通過成員方法read讀取返回體中的數據。

Exceptions

根據出錯原因的不同，SDK把異常分為兩種不同類型，分別為OAServerError，和OASClientError。

OASServerError

OASServerError是指一次完整的HTTP請求中，服務器返回了錯誤響應。各個成員變量的含義見下表。具體錯誤信息請參閱API文檔第5節錯誤響應。

成員變量	類型	含義
headers	dict	HTTP響應中的頭部，以鍵值對存儲，所有鍵均為小寫
request_id	string	出錯的請求的ID值，見API文檔2.3.3節
status	int	HTTP狀態碼
code	string	錯誤代碼，見API文檔2.3.3節
type	string	錯誤類型，見API文檔2.3.3節
message	string	錯誤信息，見API文檔2.3.3節

OASClientErrror

OASClientError表示客戶端異常，可能原因包括網絡連接出錯、文件讀寫出錯等，具體出錯原因可通過查看成員變量message獲得。異常僅作為標記錯誤類型，沒有實現額外的方法。此外，UploadArchiveError、DownloadArchiveError和HashDoesNotMatchError均繼承於OASClientError，作為更細一級的異常分類，分別代表上傳出錯、下載出錯和校驗出錯。

Utils

utils中包含的是高級接口所使用的公共工具方法，用戶在開發時可直接使用這些方法。

文件操作

is_file_like

判斷指定對象是否支持read操作。

定義

def is_file_like(obj)

參數

obj：object

返回值

boolean

content_length

根據輸入類型的不同，自動獲取目標的長度。對於無法處理的類型，拋出ValueError異常。

定義

def content_length(content)

參數

content

返回值

int

open_file

當提供file_obj參數時，返回file_obj；否則以mode默認打開file_path。

定義

def open_file(file_path=None, file_obj=None, mode='r')

參數

file_path：string
file_obj：file object
mode：string

可選參數。打開模式，默認為'rb'。

返回值

file object

Range操作

range_size

計算指定字節範圍的長度。

定義

def range_size(byte_range)

參數

byte_range：tuple

長度為2，元素分別為字節長度的起點和終點（含）。

返回值

int

calc_num_part

計算長度為size_total的文件，以part_size長度進行分塊的總分塊數。

定義

def calc_num_part(part_size, size_total)

參數

part_size：int

Part的字節長度。
size_total：int

文件總字節長度。

返回值

int

calc_ranges

計算長度為size_total的文件，以part_size長度進行分塊的所有分塊字節範圍。

定義

def calc_ranges(part_size, size_total)

參數

part_size：int

Part的字節長度。
size_total：int

文件總字節長度。

返回值

tuple list：每個元組長度為2，分別為分塊的字節起點和終點（含）。

校驗碼計算

校驗碼是歸檔存儲用於判斷archive完整性的手段，etag與tree-etag是校驗碼的兩種方式。本節中compute_etag_from_string、compute_etag_from_file、compute_etag_from_file、compute_etag_from_file_obj三個函數中的任何一個函數可以用來計算etag校驗碼，、compute_tree_etag_from_file、compute_tree_etag_from_file_obj、compute_combine_tree_etag_from_list幾個函數都是用來計算tree-etag校驗碼的。

compute_hash_from_file、compute_hash_from_file_obj可以同時計算出etag、tree-etag兩個校驗碼，並通過數組返回。

compute_etag_from_string

計算指定字符串的etag。

定義

def compute_etag_from_string(content)

參數

content：string

待計算的字符串。

返回值

string

說明

compute_etag_from_file

計算指定文件的etag。

定義

def compute_etag_from_file(file_path, offset=0, size=None, chunk_size=1048576)

參數

file_path：string

待計算的文件路徑。
offset：int

可選參數。計算的字節起始點（含），默認為0。
size：int

可選參數。待計算的字節長度，默認為offset起的所有字節的長度。
chunk_size：int

可選參數。每次讀取的塊大小，默認為1048576（1MB）。

返回值

string

compute_etag_from_file_obj

計算指定文件對象的etag。

定義

def compute_etag_from_file_obj(file_obj, offset=0, size=None, chunk_size=1048576)

參數

file_obj：file object

待計算的文件對象。
offset：int

可選參數。計算的字節起始點（含），默認為0。
size：int

可選參數。待計算的字節長度，默認為offset起的所有字節的長度。
chunk_size：int

可選參數。每次讀取的塊大小，默認為1048576（1MB）。

返回值

string

compute_tree_etag_from_file

計算指定文件的tree-etag校驗碼。

定義

def compute_tree_etag_from_file(file_path, offset=0, size=None, chunk_size=1048576)

參數

file_path：string

待計算的文件路徑。
offset：int

可選參數。計算的字節起始點（含），默認為0。
size：int

可選參數。待計算的字節長度，默認為offset起的所有字節的長度。
chunk_size：int

可選參數。每次讀取的塊大小，默認為1048576（1MB）。

返回值

string

compute_tree_etag_from_file_obj

計算指定文件對象的tree-etag。

定義

def compute_tree_etag_from_file_obj(file_obj, offset=0, size=None, chunk_size=1048576)

參數

file_obj：file object

待計算的文件對象。
offset：int

可選參數。計算的字節起始點（含），默認為0。
size：int

可選參數。待計算的字節長度，默認為offset起的所有字節的長度。
chunk_size：int

可選參數。每次讀取的塊大小，默認為1048576（1MB）。

返回值

string

compute_combine_tree_etag_from_list

根據各個分塊的tree-etag所組成的list，計算整個文件的校驗碼。

定義

def compute_combine_tree_etag_from_list(tree_etag_list)

參數

tree_etag_list：list

列表元素為每個分塊的tree-etag。

返回值

string

compute_hash_from_file

計算指定文件的etag及tree-etag校驗碼。

定義

def compute_hash_from_file(file_path, offset=0, size=None, chunk_size=1048576)

參數

file_path：string

待計算的文件路徑。
offset：int

可選參數。計算的字節起始點（含），默認為0。
size：int

可選參數。待計算的字節長度，默認為offset起的所有字節的長度。
chunk_size：int

可選參數。每次讀取的塊大小，默認為1048576（1MB）。

返回值

(string,string)

返回的是兩個校驗碼數組：(etag，tree-etag)

compute_hash_from_file_obj

計算指定文件對象的etag及tree-etag校驗碼。

定義

def compute_hash_from_file_obj(file_obj, offset=0, size=None, chunk_size=1048576)

參數

file_obj：file object

待計算的文件對象。
offset：int

可選參數。計算的字節起始點（含），默認為0。
size：int

可選參數。待計算的字節長度，默認為offset起的所有字節的長度。
chunk_size：int

可選參數。每次讀取的塊大小，默認為1048576（1MB）。

返回值

(string, string)

返回的是兩個校驗碼數組：(etag，tree-etag)

最後更新：2016-11-23 16:03:56