高级接口的使用

高级接口中的所有方法均为阻塞操作，在操作没有完成之前不会返回。所有接口都可能会抛出两种异常，分别为 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的类方法，其中[backcolor=transparent]create_vault、[backcolor=transparent]get_vault_by_id和[backcolor=transparent]get_vault_by_name是简单工厂方法，返回 Vault对象，[backcolor=transparent]list_all_vaults返回 Vault list。这些类方法都需要以 OASAPI对象作为参数（参见低级接口概述部分）。
对于上传操作，可以直接调用成员方法[backcolor=transparent]upload_archive，接口内部会根据文件大小自动选择Normal Upload或Multipart Upload方式，并实现了多线程并行上传和失败重试。对于Multipart Upload任务，用户也可调用成员方法[backcolor=transparent]initiate_uploader获得 Uploader对象再进行上传（参见Uploader一节）。使用后一种方法，用户可获得时机保存Multipart Upload的任务ID，若任务没有成功完成，可在之后调用成员方法[backcolor=transparent]recover_uploader传入任务ID进行续传。用户应根据业务需要选择合适的方法。
对于下载操作，可调用成员方法[backcolor=transparent]retrieve_inventory或[backcolor=transparent]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。

定义


[backcolor=transparent] def create_vault(cls, api, name)

参数

• 
  [backcolor=transparent]api：OASAPI
• 
  [backcolor=transparent]name：string
  待新建的Vault的名称，名称应遵守API手册4.1.1节中Vault命名规范。

返回值


[backcolor=transparent] Vault

get_vault_by_id


类方法。获取指定ID的Vault。

定义


[backcolor=transparent] def get_vault_by_id(cls, api, vault_id)

参数

• 
  [backcolor=transparent]api：OASAPI
• 
  [backcolor=transparent]vault_id：string
  待检索的Vault的ID。

返回值


[backcolor=transparent] Vault

get_vault_by_name


类方法。获取指定名称的Vault。

定义


[backcolor=transparent] def get_vault_by_name(cls, api, vault_name)

参数

• 
  [backcolor=transparent]api：OASAPI
• 
  [backcolor=transparent]vault_name：string
  待检索的Vault的名称。

返回值


[backcolor=transparent] Vault

Vault删除



delete_vault_by_id


类方法。删除指定ID的Vault。

定义


[backcolor=transparent] def delete_vault_by_id(cls, api, vault_id)

参数

• 
  [backcolor=transparent]api：OASAPI
• 
  [backcolor=transparent]vault_id：string
  待删除的Vault的ID。

返回值


[backcolor=transparent] None

delete_vault_by_name


类方法。删除指定名称的Vault。

定义


[backcolor=transparent] def delete_vault_by_name(cls, api, vault_name)

参数

• [backcolor=transparent]api：OASAPI
• 
  [backcolor=transparent]vault_name：string
  待删除的Vault的名称。

返回值


[backcolor=transparent] None

delete


删除当前Vault。

定义


[backcolor=transparent] def delete(self)

参数


[backcolor=transparent] None

返回值


[backcolor=transparent] None

状态查询


所有查询方法默认返回全部的检索结果，用户不需要对Marker标识进行处理。

list_all_vaults


类方法。返回用户持有的所有Vault。

定义


[backcolor=transparent] def list_all_vaults(cls, api)

参数

• [backcolor=transparent]api：OASAPI

返回值


[backcolor=transparent] Vault list

list_all_multipart_uploads


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

定义


[backcolor=transparent] def list_all_multipart_uploads(self)

参数


[backcolor=transparent] None

返回值


[backcolor=transparent] Uploader list

list_all_jobs


返回Vault下的所有Job任务。

定义


[backcolor=transparent] def list_all_jobs(self)

参数


[backcolor=transparent] None

返回值


[backcolor=transparent] Job list

Archive操作



upload_archive


上传指定文件到当前Valut，成功上传后返回相应的Archive ID。

定义


[backcolor=transparent] def upload_archive(self, file_path, desc=None)

参数

• 
  [backcolor=transparent]file_path：string
  待上传的文件路径。
• 
  [backcolor=transparent]desc：string
  可选参数。Archive的描述字段。

返回值


[backcolor=transparent] string：Archive ID

initiate_uploader


新建Multipart Upload任务。

定义


[backcolor=transparent] def initiate_uploader(self, file_path, desc=None)

参数

• 
  [backcolor=transparent]file_path：string
  待上传的文件路径。
• 
  [backcolor=transparent]desc：string
  可选参数。Archive的描述字段。

返回值


[backcolor=transparent] Uploader

recover_uploader


续传指定的Multipart Upload任务。

定义


[backcolor=transparent] def recover_uploader(self, upload_id)

参数

• 
  [backcolor=transparent]upload_id：string
  Multipart Upload任务的ID。

返回值


[backcolor=transparent] Uploader

delete_archive


删除指定ID的Archive。

定义


[backcolor=transparent] def delete_archive(self, archive_id)

参数

• 
  [backcolor=transparent]archive_id：string
  待删除的Archive的ID。

返回值


[backcolor=transparent] None

Job操作



get_job


获取指定ID的Job任务。

定义


[backcolor=transparent] def get_job(self, job_id)

参数

• 
  [backcolor=transparent]job_id：string
  Job任务的ID。

返回值


[backcolor=transparent] Job

retrieve_archive


新建类型为[backcolor=transparent]archive-retrieval的Job任务。

定义


[backcolor=transparent] def retrieve_archive(self, archive_id, desc=None, byte_range=None):

参数

• 
  [backcolor=transparent]archive_id：string
  待查询的Archive的ID。
• 
  [backcolor=transparent]desc：string
  可选参数。Job任务的描述字段。
• 
  [backcolor=transparent]byte_range：tuple
  可选参数。长度为2，元素分别为字节长度的起点和终点（含）。

返回值


[backcolor=transparent] Job

retrieve_inventory


新建类型为[backcolor=transparent]inventory-retrieval的Job任务。

定义


[backcolor=transparent] def retrieve_inventory(self, desc=None)

参数

• 
  [backcolor=transparent]desc：string
  可选参数。Job任务的描述字段。

返回值


[backcolor=transparent] Job

pull_from_oss


新建类型为[backcolor=transparent]pull-from-oss的Job任务。

定义


[backcolor=transparent] def pull_from_oss(self, osshost, bucket, object, desc=None)

参数

• 
  [backcolor=transparent]osshost：string
  job的源oss域名
• 
  [backcolor=transparent]bucket：string
  job任务的oss Bucket
• 
  [backcolor=transparent]object：string
  job任务的oss Object
• 
  [backcolor=transparent]desc：string
  可选参数。Job任务的描述字段。

返回值


[backcolor=transparent] Job

push_to_oss


新建类型为[backcolor=transparent]push-to-oss的Job任务。

定义


[backcolor=transparent] def push_to_oss(self, archive_id, osshost, bucket, object, desc=None)

参数

• [backcolor=transparent]archive_id：string

待转储的archive_id

• 
  [backcolor=transparent]osshost：string
  job的源oss域名
• 
  [backcolor=transparent]bucket：string
  job任务的oss Bucket
• 
  [backcolor=transparent]object：string
  job任务的oss Object
• 
  [backcolor=transparent]desc：string
  可选参数。Job任务的描述字段。

返回值


[backcolor=transparent] Job

Uploader


Uploader是Multipart Upload任务的抽象。
要获取 Uploader对象，可通过 Vault的三个成员方法，包括：

• [backcolor=transparent]initiate_uploader
• [backcolor=transparent]recover_uploader
• [backcolor=transparent]list_all_multipart_uploads

其中，[backcolor=transparent]initiate_uploader、[backcolor=transparent]recover_uploader返回 Uploader对象。
[backcolor=transparent]list_all_multipart_uploads返回 Uploader list。
[backcolor=transparent]initiate_uploader用于新建Multipart Upload任务，可直接调用 Uploader的成员方法[backcolor=transparent]start开始上传。
[backcolor=transparent]recover_uploader和[backcolor=transparent]list_all_multipart_uploads返回的Uploader用于续传Multipart Upload任务，应调用 Uploader的成员方法[backcolor=transparent]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

• 
  [backcolor=transparent]size_completed
  已上传的字节数。

成员方法



start


开始上传任务。

定义


[backcolor=transparent] def start(self)

参数


[backcolor=transparent] None

返回值


[backcolor=transparent] String：Archive ID

resume


恢复上传任务。

定义


[backcolor=transparent] def resume(self, file_path)

参数

• 
  [backcolor=transparent]file_path：string
  待上传的文件路径。

返回值


[backcolor=transparent] String：Archive ID

cancel


取消上传任务。

定义


[backcolor=transparent] def cancel(self)

参数


[backcolor=transparent] None

返回值


[backcolor=transparent] None

Job


Job是Job任务的抽象。根据下载文件的大小， Job内部会自动进行分块并行下载，并实现了断点续传和简单的出错重试。
在使用时，用户需要注意Job任务并不是实时完成的（参见 《OAS API文档-1.1.6节》），用户应调用 Job的成员方法[backcolor=transparent]update_status更新任务状态，并通过检查成员变量completed确认任务是否完成。当任务完成时，可通过调用[backcolor=transparent]download_to_file或[backcolor=transparent]download_by_range开始下载。用户也可直接设置[backcolor=transparent]download_to_file和[backcolor=transparent]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

• 
  [backcolor=transparent]size_completed
  已下载的字节数

成员方法



update_status


更新Job的任务状态。

定义


[backcolor=transparent] def update_status(self)

参数


[backcolor=transparent] None

返回值


[backcolor=transparent] None

download_by_range


下载指定字节范围到文件。

定义


[backcolor=transparent] def download_by_range(self, byte_range, file_path=None, file_obj=None, chunk_size=None, block=True)

参数

• 
  [backcolor=transparent]byte_range：tuple
  长度为2，两个元素分别为字节长度的起点和终点（含）。
• 
  [backcolor=transparent]file_path：string
• 
  [backcolor=transparent]file_obj：file object
  二选一参数，下载到指定的文件路径或保存到指定的文件对象。当两个参数均提供时，结果不确定。
• 
  [backcolor=transparent]chunk_size：int
  可选参数。每次读写的块大小，默认为1048576（1MB）。
• 
  [backcolor=transparent]block：boolean
  可选参数。当block为False时，直接开始下载，若Job未完成会抛出异常。当block为True时，循环等待至Job完成，再开始下载。默认为True。

download_to_file


下载Job任务输出到指定文件路径。

定义


[backcolor=transparent] def download_to_file(self, file_path, chunk_size=None, block=True)

参数

• 
  [backcolor=transparent]file_path：string
  文件保存的路径。
• 
  [backcolor=transparent]chunk_size：int
  可选参数。每次读写的块大小，默认为1048576（1MB）。
• 
  [backcolor=transparent]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操作。

定义


[backcolor=transparent] def is_file_like(obj)

参数

• [backcolor=transparent]obj：object

返回值


[backcolor=transparent] boolean

content_length


根据输入类型的不同，自动获取目标的长度。对于无法处理的类型，抛出 ValueError异常。

定义


[backcolor=transparent] def content_length(content)

参数

• [backcolor=transparent]content

返回值


[backcolor=transparent] int

open_file


当提供file_obj参数时，返回file_obj；否则以mode默认打开file_path。

定义


[backcolor=transparent] def open_file(file_path=None, file_obj=None, mode='r')

参数

• 
  [backcolor=transparent]file_path：string
• 
  [backcolor=transparent]file_obj：file object
• 
  [backcolor=transparent]mode：string
  可选参数。打开模式，默认为'rb'。

返回值


[backcolor=transparent] file object

Range操作



range_size


计算指定字节范围的长度。

定义


[backcolor=transparent] def range_size(byte_range)

参数

• 
  [backcolor=transparent]byte_range：tuple
  长度为2，元素分别为字节长度的起点和终点（含）。

返回值


[backcolor=transparent] int

calc_num_part


计算长度为size_total的文件，以part_size长度进行分块的总分块数。

定义


[backcolor=transparent] def calc_num_part(part_size, size_total)

参数

• 
  [backcolor=transparent]part_size：int
  Part的字节长度。
• 
  [backcolor=transparent]size_total：int
  文件总字节长度。

返回值


[backcolor=transparent] int

calc_ranges


计算长度为size_total的文件，以part_size长度进行分块的所有分块字节范围。

定义


[backcolor=transparent] def calc_ranges(part_size, size_total)

参数

• 
  [backcolor=transparent]part_size：int
  Part的字节长度。
• 
  [backcolor=transparent]size_total：int
  文件总字节长度。

返回值


[backcolor=transparent] 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。

定义


[backcolor=transparent] def compute_etag_from_string(content)

参数

• 
  [backcolor=transparent]content：string
  待计算的字符串。

返回值


[backcolor=transparent] string

说明



compute_etag_from_file


计算指定文件的etag。

定义


[backcolor=transparent] def compute_etag_from_file(file_path, offset=0, size=None, chunk_size=1048576)

参数

• 
  [backcolor=transparent]file_path：string
  待计算的文件路径。
• 
  [backcolor=transparent]offset：int
  可选参数。计算的字节起始点（含），默认为0。
• 
  [backcolor=transparent]size：int
  可选参数。待计算的字节长度，默认为offset起的所有字节的长度。
• 
  [backcolor=transparent]chunk_size：int
  可选参数。每次读取的块大小，默认为1048576（1MB）。

返回值


[backcolor=transparent] string

compute_etag_from_file_obj


计算指定文件对象的etag。

定义


[backcolor=transparent] def compute_etag_from_file_obj(file_obj, offset=0, size=None, chunk_size=1048576)

参数

• 
  [backcolor=transparent]file_obj：file object
  待计算的文件对象。
• 
  [backcolor=transparent]offset：int
  可选参数。计算的字节起始点（含），默认为0。
• 
  [backcolor=transparent]size：int
  可选参数。待计算的字节长度，默认为offset起的所有字节的长度。
• 
  [backcolor=transparent]chunk_size：int
  可选参数。每次读取的块大小，默认为1048576（1MB）。

返回值


[backcolor=transparent] string

compute_tree_etag_from_file


计算指定文件的tree-etag校验码。

定义


[backcolor=transparent] def compute_tree_etag_from_file(file_path, offset=0, size=None, chunk_size=1048576)

参数

• 
  [backcolor=transparent]file_path：string
  待计算的文件路径。
• 
  [backcolor=transparent]offset：int
  可选参数。计算的字节起始点（含），默认为0。
• 
  [backcolor=transparent]size：int
  可选参数。待计算的字节长度，默认为offset起的所有字节的长度。
• 
  [backcolor=transparent]chunk_size：int
  可选参数。每次读取的块大小，默认为1048576（1MB）。

返回值


[backcolor=transparent] string

compute_tree_etag_from_file_obj


计算指定文件对象的tree-etag。

定义


[backcolor=transparent] def compute_tree_etag_from_file_obj(file_obj, offset=0, size=None, chunk_size=1048576)

参数

• 
  [backcolor=transparent]file_obj：file object
  待计算的文件对象。
• 
  [backcolor=transparent]offset：int
  可选参数。计算的字节起始点（含），默认为0。
• 
  [backcolor=transparent]size：int
  可选参数。待计算的字节长度，默认为offset起的所有字节的长度。
• 
  [backcolor=transparent]chunk_size：int
  可选参数。每次读取的块大小，默认为1048576（1MB）。

返回值


[backcolor=transparent] string

compute_combine_tree_etag_from_list


根据各个分块的tree-etag所组成的list，计算整个文件的校验码。

定义


[backcolor=transparent] def compute_combine_tree_etag_from_list(tree_etag_list)

参数

• 
  [backcolor=transparent]tree_etag_list：list
  列表元素为每个分块的tree-etag。

返回值


[backcolor=transparent] string

compute_hash_from_file


计算指定文件的etag及tree-etag校验码。

定义


[backcolor=transparent] def compute_hash_from_file(file_path, offset=0, size=None, chunk_size=1048576)

参数

• 
  [backcolor=transparent]file_path：string
  待计算的文件路径。
• 
  [backcolor=transparent]offset：int
  可选参数。计算的字节起始点（含），默认为0。
• 
  [backcolor=transparent]size：int
  可选参数。待计算的字节长度，默认为offset起的所有字节的长度。
• 
  [backcolor=transparent]chunk_size：int
  可选参数。每次读取的块大小，默认为1048576（1MB）。

返回值


[backcolor=transparent] (string,string)
返回的是两个校验码数组：(etag，tree-etag)

compute_hash_from_file_obj


计算指定文件对象的etag及tree-etag校验码。

定义


[backcolor=transparent] def compute_hash_from_file_obj(file_obj, offset=0, size=None, chunk_size=1048576)

参数

• 
  [backcolor=transparent]file_obj：file object
  待计算的文件对象。
• 
  [backcolor=transparent]offset：int
  可选参数。计算的字节起始点（含），默认为0。
• 
  [backcolor=transparent]size：int
  可选参数。待计算的字节长度，默认为offset起的所有字节的长度。
• 
  [backcolor=transparent]chunk_size：int
  可选参数。每次读取的块大小，默认为1048576（1MB）。

返回值


[backcolor=transparent] (string, string)
返回的是两个校验码数组：(etag，tree-etag)