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

類OASAPI是歸檔存儲 API的基礎實現，其開放的接口和API手冊所描述的RESTful接口分別一一對應。

OASAPI的實例化需要提供服務器地址（參見《OAS API手冊-2.1.1服務地址》）和可選的端口，以及用戶認證信息，包括Access Key ID和Access Key Secret。

OASAPI所開放的所有接口均返回對象HTTPResponse，下文中res默認指HTTPResponse對象。用戶可通過res.status判斷調用是否成功，並通過res.getheader()獲取返回頭部參數或res.read()獲取返回體。對於HTTP返回體格式為JSON的數據，下文以rjson表示解析後的JSON數據。關於HTTPResponse的更詳細使用，請參見Python官方文檔關於httplib的說明。

Vault操作

創建Vault

定義

def create_vault(self, vault_name)

參數

vault_name：string

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

返回值

HTTPResponse

說明

創建指定名稱的Vault，並返回Vault ID。可通過res.status檢查調用是否成功，對於成功的操作，可通過res.getheader('x-oas-vault-id')獲取成功創建的Vault的ID值。

刪除Vault

定義

def delete_vault(self, vault_id)

參數

vault_id：string

待刪除Vault的ID。

返回值

HTTPResponse

說明

刪除指定ID的Vault。成功的調用要求給定的Vault ID存在，並且指定的Vault為空，即不包含任何Archive。可通過res.status檢查調用是否成功。

獲取Vault信息

定義

def get_vault_desc(self, vault_id)

參數

vault_id：string

Vault的ID。

返回值

HTTPResponse

說明

獲取指定ID的Vault描述。對於成功的調用，可通過解析HTTP返回體中的JSON獲取相關信息，JSON的各個字段解釋詳見API手冊4.1.3節中的返回體。

Vault列表

定義

def list_vault(self, marker=None, limit=None)

參數

marker：string

可選參數。指明所請求的列表起點，與API手冊4.1.4節中的請求參數描述一致。
limit：int

可選參數。限製返回的Vault數量，與API手冊4.1.4節中的請求參數描述一致。

返回值

HTTPResponse

說明

獲取用戶的Vault列表。對於成功的調用，可通過解析HTTP返回體中的JSON獲取相關信息。可通過rjson['Marker']判斷是否還有後續列表，該字段可用於下次請求的marker參數。rjson['VaultList']是Vault描述信息數組。關於JSON的各個字段的更詳細解釋見API手冊4.1.4節中的返回體。

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)

參數

vault_id：string

指定保存Archive的Vault的ID。
content

待上傳的字節流。
reader

實現了read接口的對象，如file object。
content_length：int

待上傳的Archive的字節長度。
etag：string

待上傳的文件的etag校驗碼，詳細計算方法請參閱API文檔2.5.1一節。
tree_etag：string

待上傳文件的tree_etag校驗碼。
desc：string

可選參數。Archive的描述信息。

返回值

HTTPResponse

說明

上傳Archive至指定的Vault，並返回Archive ID。對於已存在於內存的數據，可直接調用post_archive；對於文件上傳，可使用post_archive_from_reader。所有超出content_length長度的數據會被忽略。對於成功的操作，可通過res.getheader('x-oas-archive-id')獲取相應的Archive ID。關於Archive上傳的限製，請參見《OAS API手冊-4.2.1節》的描述。

刪除Archive

定義

def delete_archive(self, vault_id, archive_id)

參數

vault_id：string

待刪除的Archive所屬Vault的ID。

archive_id：string

待刪除的Archive的ID。

返回值

HTTPResponse

說明

刪除指定的Archive。可通過檢查res.status判斷調用是否成功。

Multipart Upload操作

關於Multipart Upload操作的完整流程請參考API手冊1.1.4節。

初始化Multipart Upload任務

定義

def create_multipart_upload(self, vault_id, partsize, desc=None)

參數

vault_id：string

上傳任務所屬Vault的ID。
partsize：int

指定Part的字節長度，請參閱API手冊4.3.1節中描述關於Part長度的限製。
desc：string

可選參數，Archive的描述信息。

返回值

HTTPResponse

說明

新建Multipart Upload任務，並返回Upload ID。對於成功的操作，可通過res.getheader('x-oas-multipart-upload-id')獲得任務ID，用於後續的Part上傳。

獲取Multipart Upload任務列表

定義

def list_multipart_upload(self, vault_id, marker=None, limit=None)

參數

vault_id：string

待查詢的目標Vault的ID。
marker：string

可選參數，指明所請求的列表起點，與API手冊4.3.2節中的請求參數描述一致。
limit：int

可選參數，限製返回的任務數量，與API手冊4.3.2節中的請求參數描述一致。

返回值

HTTPResponse

說明

獲取指定Vault下Multipart Upload任務。對於成功地調用，可通過解析HTTP返回體中的JSON獲取相關信息。可通過rjson['Marker']判斷是否還有後續列表，該字段可用於下次請求的marker參數。rjson['UploadsList']是任務描述信息數組。關於JSON的各個字段的更詳細解釋見API手冊4.3.2節中的返回體。

刪除Multipart Upload任務

定義

def delete_multipart_upload(self, vault_id, upload_id)

參數

vault_id：string

待刪除的任務所屬Vault的ID。
upload_id：string

待刪除任務的ID。

返回值

HTTPResponse

說明

刪除指定任務。可通過res.status檢查調用是否成功。

Part上傳

定義

def post_multipart(self, vault_id, upload_id, content, prange, etag, tree_etag)

def post_multipart_from_reader(self, vault_id, upload_id, reader, content_length, prange, etag, tree_etag)

參數

vault_id：string

上傳任務所屬Vault的ID。
upload_id：string

待上傳的Part所屬的任務ID。
content：string

待上傳的字節流。
reader

實現了read接口的對象，如file object。
partsize：int

待上傳的Part的字節長度。
prange：string

待上傳的Part在整個Archive中的字節範圍，字節以0開始計數，格式為start-end。prange所指定範圍的長度應與partsize一致，所有超出partsize長度的數據會被忽略。除最後一個Part外，partsize應與初始化Multipart Upload任務時所指定的partsize一致。參數定義與API手冊4.3.4一節中描述部分一致。
etag：string

待上傳的Part的etag校驗碼，詳細計算方法請參閱API文檔2.5.2一節。
tree_etag：string

待上傳Part的tree_etag校驗碼。

返回值

HTTPResponse

說明

上傳Archive中指定字節範圍的Part，注意prange定義應符合API手冊指定的規範。對於已存在於內存的數據，可直接調用post_multipart；對於文件上傳，可使用post_multipart_from_reader。可通過res.status檢查上傳是否成功。

獲取Part列表

定義

def list_multipart(self, vault_id, upload_id, marker=None, limit=None)

參數

vault_id：string

上傳任務所屬Vault的ID。
upload_id：string

待查詢的目標Multipart Upload任務的ID。
marker：string

可選參數。指明所請求的Part列表起點，與API手冊4.3.5節中的請求參數描述一致。
limit：int

可選參數。限製返回的Part數量，與API手冊4.3.5節中的請求參數描述一致。

返回值

HTTPResponse

說明

獲取目標Vault下指定Multipart Upload任務已上傳完成的Part列表。對於成功的調用，可通過解析HTTP返回體中的JSON獲取相關信息。可通過rjson['Marker']判斷是否還有後續列表，該字段可用於下次請求的marker參數。rjson['Parts']是Part描述信息數組。關於JSON的各個字段的更詳細解釋見API手冊4.3.5節中的返回體。

Part合並

定義

def complete_multipart_upload(self, vault_id, upload_id, filesize, tree_etag)

參數

vault_id：string

上傳任務所屬Vault的ID。
upload_id：string

所要進行合並的Multipart Upload任務ID。
filesize：int

所要進行合並的Archive總字節大小。
tree_etag：string

待上傳文件的tree-etag校驗碼。

返回值

HTTPResponse

說明

對某個已完成所有Part上傳的任務進行合並。可通過res.status檢查合並是否成功。對於成功的操作，可通過res.getheader('x-oas-archive-id')獲取成功合並後創建的Archive ID。

Job操作

初始化Job任務

定義

def create_job(self, vault_id, job_type, 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)

參數

vault_id

Job任務所屬Vault的ID。
job_type

任務類型。可選值為archive-retrieval和inventory-retrieval。與API文檔4.4.1一節中的請求體中的Type描述一致。
archive_id

當job_type為inventory-retrieval時，忽略該參數。當 job_type為archive-retrieval時，該參數是指待下載的Archive的ID。
desc

可選參數。Job任務的描述信息。
byte_range

可選參數。待下載的Archive字節範圍，與API文檔4.4.1一節中的請求體中得RetrievalByteRange描述一致。
osshost

當job_type為pull-from-oss或push-to-oss時，該參數是指轉儲job的oss域名。
bucket

當job_type為pull-from-oss或push-to-oss時，該參數是指轉儲job的oss bucket。
object

當job_type為pull-from-oss或push-to-oss時，該參數是指轉儲job的 oss Object。

說明

新建Job任務並返回Job ID，根據所要操作的類型選擇合適的job_type，當任務類型是archive-retrieval時，需要提供目標Archive的ID，以及可選的下載範圍byte_range。可通過res.status檢查新建是否成功。對於成功新建的Job任務，可通過res.getheader('x-oas-job-id')獲取Job ID，該ID可用於後續Job任務狀態查詢。 create_oss_transfer_job函數適用於在歸檔存儲與OSS產品之間的跨產品數據歸檔、提檔，幫助用戶在阿裏雲上實現無中轉的數據遷移。

Job Output下載

定義

def fetch_job_output(self, vault_id, job_id, orange=None)

參數

vault_id：string

目標Job任務所屬Vault的ID。
job_id：string

目標Job的ID。
orange：string

可選參數。所要下載的Job輸出字節範圍，格式為start-end，字節以0開始計數。參數定義與API手冊5.4.3一節中描述部分一致。

返回值

HTTPResponse

說明

下載已完成的Job任務輸出的結果。對於Job類型為inventory-retrieval的任務，rjson['ArchiveList']是所查詢的Archive列表信息。關於JSON的各個字段的更詳細解釋見API手冊5.4.2一節中返回體的描述。對於Job類型為archive-retrieval的任務，HTTP返回體是所請求範圍的字節。對於大文件的下載，建議設置orange參數分塊下載。

獲取Job列表

定義

def list_job(self, vault_id, marker=None, limit=None)

參數

vault_id：string

待查詢的Vault的ID。
marker：string

可選參數，指明所請求的Job列表起點，與API手冊5.4.3節中的請求參數描述一致。
limit：int

可選參數，限製返回的Job數量，與API手冊5.4.3節中的請求參數描述一致。

返回值

HTTPResponse

說明

獲取指定Vault下的Job列表。對於成功的調用，可通過解析HTTP返回體中的JSON獲取相關信息。可通過rjson['Marker']判斷是否還有後續列表，該字段可用於下次請求的marker參數。rjson['JobList']是Job描述信息數組。關於JSON的各個字段的更詳細解釋見API手冊5.4.3節中的返回體。

Job任務狀態查詢

定義

def get_jobdesc(self, vault_id, job_id)

參數

vault_id：string

目標Job任務所屬Vault的ID。
job_id：string

目標Job任務的ID。

返回值

HTTPResponse

說明

查看指定ID的Job任務狀態。對於成功的調用，可通過解析HTTP返回體中的JSON獲取相關信息，JSON的各個字段解釋詳見API手冊4.4.4節中的返回體。

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