高级接口的使用-问答-阿里云开发者社区-阿里云

开发者社区> 问答> 正文

高级接口的使用

云栖大讲堂 2017-10-26 14:28:56 1910

高级接口中的所有方法均为阻塞操作,在操作没有完成之前不会返回。所有接口都可能会抛出两种异常,分别为 OASServerErrorOASClientError,具体描述请参阅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标签变量名类型
CreationDatecreation_datestring
LastInventoryDatelast_inventory_datestring
NumberOfArchivesnumber_of_archivesint
SizeInBytessizeint
VaultIdidstring
VaultNamenamestring


构造方法


Vault包含了三个简单工厂方法用于构造 Vault对象,三个类方法均需 OASAPI对象作为参数, OASAPI的构造请参阅低级接口的概述部分。

create_vault


类方法。新建指定名称的Vault。

定义


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

参数


  • [backcolor=transparent]apiOASAPI

  • [backcolor=transparent]namestring
    待新建的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]apiOASAPI

  • [backcolor=transparent]vault_idstring
    待检索的Vault的ID。


返回值


[backcolor=transparent] Vault

get_vault_by_name


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

定义


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

参数


  • [backcolor=transparent]apiOASAPI

  • [backcolor=transparent]vault_namestring
    待检索的Vault的名称。


返回值


[backcolor=transparent] Vault

Vault删除



delete_vault_by_id


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

定义


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

参数


  • [backcolor=transparent]apiOASAPI

  • [backcolor=transparent]vault_idstring
    待删除的Vault的ID。


返回值


[backcolor=transparent] None

delete_vault_by_name


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

定义


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

参数

  • [backcolor=transparent]apiOASAPI

  • [backcolor=transparent]vault_namestring
    待删除的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]apiOASAPI


返回值


[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_pathstring
    待上传的文件路径。

  • [backcolor=transparent]descstring
    可选参数。Archive的描述字段。


返回值


[backcolor=transparent] string:Archive ID

initiate_uploader


新建Multipart Upload任务。

定义


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

参数


  • [backcolor=transparent]file_pathstring
    待上传的文件路径。

  • [backcolor=transparent]descstring
    可选参数。Archive的描述字段。


返回值


[backcolor=transparent] Uploader

recover_uploader


续传指定的Multipart Upload任务。

定义


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

参数


  • [backcolor=transparent]upload_idstring
    Multipart Upload任务的ID。


返回值


[backcolor=transparent] Uploader

delete_archive


删除指定ID的Archive。

定义


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

参数


  • [backcolor=transparent]archive_idstring
    待删除的Archive的ID。


返回值


[backcolor=transparent] None

Job操作



get_job


获取指定ID的Job任务。

定义


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

参数


  • [backcolor=transparent]job_idstring
    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_idstring
    待查询的Archive的ID。

  • [backcolor=transparent]descstring
    可选参数。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]descstring
    可选参数。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]osshoststring
    job的源oss域名

  • [backcolor=transparent]bucketstring
    job任务的oss Bucket

  • [backcolor=transparent]objectstring
    job任务的oss Object

  • [backcolor=transparent]descstring
    可选参数。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_idstring

待转储的archive_id

  • [backcolor=transparent]osshoststring
    job的源oss域名

  • [backcolor=transparent]bucketstring
    job任务的oss Bucket

  • [backcolor=transparent]objectstring
    job任务的oss Object

  • [backcolor=transparent]descstring
    可选参数。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标签变量名类型
ArchiveDescriptiondescriptionstring
CreationDatecreation_datestring
MultipartUploadIdidstring
PartSizeInBytespart_sizeint


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_pathstring
    待上传的文件路径。


返回值


[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标签变量名类型
Actionactionstring
ArchiveContentEtagetagstring
ArchiveIdarchive_idstring
ArchiveSizeInBytesarchive_sizeint
Completedcompletedboolean
CompletionDatecompletion_datestring
CreationDatecreation_datestring
InventorySizeInBytesinventory_sizeint
JobDescriptiondescriptionstring
JobIdidstring
StatusCodestatus_codestring
StatusMessagestatus_messagestring


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_rangetuple
    长度为2,两个元素分别为字节长度的起点和终点(含)。

  • [backcolor=transparent]file_pathstring

  • [backcolor=transparent]file_objfile object
    二选一参数,下载到指定的文件路径或保存到指定的文件对象。当两个参数均提供时,结果不确定。

  • [backcolor=transparent]chunk_sizeint
    可选参数。每次读写的块大小,默认为1048576(1MB)。

  • [backcolor=transparent]blockboolean
    可选参数。当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_pathstring
    文件保存的路径。

  • [backcolor=transparent]chunk_sizeint
    可选参数。每次读写的块大小,默认为1048576(1MB)。

  • [backcolor=transparent]blockint
    可选参数。当block为False时,直接开始下载,若Job未完成会抛出异常。当block为True时,循环等待至Job完成,再开始下载。默认为True。


说明



Response


OASResponseHttpResponse的简单抽象。 OASResponse是字典对象, HttpResponse中的头部信息以键值对的形式存储在 OASResponse中。对于类型为JSON的响应, OASResponse会自动解析JSON数据并保存为字典。对于类型为二进制流的响应,可通过成员方法read读取返回体中的数据。

Exceptions


根据出错原因的不同,SDK把异常分为两种不同类型,分别为 OAServerError,和 OASClientError

OASServerError


OASServerError是指一次完整的HTTP请求中,服务器返回了错误响应。各个成员变量的含义见下表。具体错误信息请参阅API文档第5节错误响应。
成员变量类型含义
headersdictHTTP响应中的头部,以键值对存储,所有键均为小写
request_idstring出错的请求的ID值,见API文档2.3.3节
statusintHTTP状态码
codestring错误代码,见API文档2.3.3节
typestring错误类型,见API文档2.3.3节
messagestring错误信息,见API文档2.3.3节


OASClientErrror


OASClientError表示客户端异常,可能原因包括网络连接出错、文件读写出错等,具体出错原因可通过查看成员变量message获得。异常仅作为标记错误类型,没有实现额外的方法。此外, UploadArchiveErrorDownloadArchiveErrorHashDoesNotMatchError均继承于 OASClientError,作为更细一级的异常分类,分别代表上传出错、下载出错和校验出错。

Utils


utils中包含的是高级接口所使用的公共工具方法,用户在开发时可直接使用这些方法。

文件操作



is_file_like


判断指定对象是否支持read操作。

定义


[backcolor=transparent] def is_file_like(obj)

参数

  • [backcolor=transparent]objobject


返回值


[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_pathstring

  • [backcolor=transparent]file_objfile object

  • [backcolor=transparent]modestring
    可选参数。打开模式,默认为'rb'。


返回值


[backcolor=transparent] file object

Range操作



range_size


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

定义


[backcolor=transparent] def range_size(byte_range)

参数


  • [backcolor=transparent]byte_rangetuple
    长度为2,元素分别为字节长度的起点和终点(含)。


返回值


[backcolor=transparent] int

calc_num_part


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

定义


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

参数


  • [backcolor=transparent]part_sizeint
    Part的字节长度。

  • [backcolor=transparent]size_totalint
    文件总字节长度。


返回值


[backcolor=transparent] int

calc_ranges


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

定义


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

参数


  • [backcolor=transparent]part_sizeint
    Part的字节长度。

  • [backcolor=transparent]size_totalint
    文件总字节长度。


返回值


[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]contentstring
    待计算的字符串。


返回值


[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_pathstring
    待计算的文件路径。

  • [backcolor=transparent]offsetint
    可选参数。计算的字节起始点(含),默认为0。

  • [backcolor=transparent]sizeint
    可选参数。待计算的字节长度,默认为offset起的所有字节的长度。

  • [backcolor=transparent]chunk_sizeint
    可选参数。每次读取的块大小,默认为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_objfile object
    待计算的文件对象。

  • [backcolor=transparent]offsetint
    可选参数。计算的字节起始点(含),默认为0。

  • [backcolor=transparent]sizeint
    可选参数。待计算的字节长度,默认为offset起的所有字节的长度。

  • [backcolor=transparent]chunk_sizeint
    可选参数。每次读取的块大小,默认为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_pathstring
    待计算的文件路径。

  • [backcolor=transparent]offsetint
    可选参数。计算的字节起始点(含),默认为0。

  • [backcolor=transparent]sizeint
    可选参数。待计算的字节长度,默认为offset起的所有字节的长度。

  • [backcolor=transparent]chunk_sizeint
    可选参数。每次读取的块大小,默认为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_objfile object
    待计算的文件对象。

  • [backcolor=transparent]offsetint
    可选参数。计算的字节起始点(含),默认为0。

  • [backcolor=transparent]sizeint
    可选参数。待计算的字节长度,默认为offset起的所有字节的长度。

  • [backcolor=transparent]chunk_sizeint
    可选参数。每次读取的块大小,默认为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_listlist
    列表元素为每个分块的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_pathstring
    待计算的文件路径。

  • [backcolor=transparent]offsetint
    可选参数。计算的字节起始点(含),默认为0。

  • [backcolor=transparent]sizeint
    可选参数。待计算的字节长度,默认为offset起的所有字节的长度。

  • [backcolor=transparent]chunk_sizeint
    可选参数。每次读取的块大小,默认为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_objfile object
    待计算的文件对象。

  • [backcolor=transparent]offsetint
    可选参数。计算的字节起始点(含),默认为0。

  • [backcolor=transparent]sizeint
    可选参数。待计算的字节长度,默认为offset起的所有字节的长度。

  • [backcolor=transparent]chunk_sizeint
    可选参数。每次读取的块大小,默认为1048576(1MB)。


返回值


[backcolor=transparent] (string, string)
返回的是两个校验码数组:(etag,tree-etag)
存储 JSON API 开发工具 对象存储 数据格式 Python
分享到
取消 提交回答
全部回答(1)
开发与运维
使用钉钉扫一扫加入圈子
+ 订阅

集结各类场景实战经验,助你开发运维畅行无忧

推荐文章
相似问题