高级接口

高级接口中的所有方法均为阻塞操作，在操作没有完成之前不会返回。所有接口都可能会抛出两种异常，分别为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)