文档

低级接口

更新时间:
一键部署

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_namestring

    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_idstring

    待删除Vault的ID。

返回值

HTTPResponse

说明

删除指定ID的Vault。成功的调用要求给定的Vault ID存在,并且指定的Vault为空,即不包含任何Archive。可通过res.status检查调用是否成功。

获取Vault信息

定义

def get_vault_desc(self, vault_id)

参数
  • vault_idstring

    Vault的ID。

返回值

HTTPResponse

说明

获取指定ID的Vault描述。对于成功的调用,可通过解析HTTP返回体中的JSON获取相关信息,JSON的各个字段解释详见API手册4.1.3节中的返回体。

Vault列表

定义

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

参数
  • markerstring

    可选参数。指明所请求的列表起点,与API手册4.1.4节中的请求参数描述一致。

  • limitint

    可选参数。限制返回的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_idstring

    指定保存Archive的Vault的ID。

  • content

    待上传的字节流。

  • reader

    实现了read接口的对象,如file object

  • content_lengthint

    待上传的Archive的字节长度。

  • etagstring

    待上传的文件的etag校验码,详细计算方法请参阅API文档2.5.1一节。

  • tree_etagstring

    待上传文件的tree_etag校验码。

  • descstring

    可选参数。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_idstring

    待删除的Archive所属Vault的ID。

  • archive_idstring

    待删除的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_idstring

    上传任务所属Vault的ID。

  • partsizeint

    指定Part的字节长度,请参阅API手册4.3.1节中描述关于Part长度的限制。

  • descstring

    可选参数,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_idstring

    待查询的目标Vault的ID。

  • markerstring

    可选参数,指明所请求的列表起点,与API手册4.3.2节中的请求参数描述一致。

  • limitint

    可选参数,限制返回的任务数量,与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_idstring

    待删除的任务所属Vault的ID。

  • upload_idstring

    待删除任务的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_idstring

    上传任务所属Vault的ID。

  • upload_idstring

    待上传的Part所属的任务ID。

  • contentstring

    待上传的字节流。

  • reader

    实现了read接口的对象,如file object

  • partsizeint

    待上传的Part的字节长度。

  • prangestring

    待上传的Part在整个Archive中的字节范围,字节以0开始计数,格式为start-end。prange所指定范围的长度应与partsize一致,所有超出partsize长度的数据会被忽略。除最后一个Part外,partsize应与初始化Multipart Upload任务时所指定的partsize一致。参数定义与API手册4.3.4一节中描述部分一致。

  • etagstring

    待上传的Part的etag校验码,详细计算方法请参阅API文档2.5.2一节。

  • tree_etagstring

    待上传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_idstring

    上传任务所属Vault的ID。

  • upload_idstring

    待查询的目标Multipart Upload任务的ID。

  • markerstring

    可选参数。指明所请求的Part列表起点,与API手册4.3.5节中的请求参数描述一致。

  • limitint

可选参数。限制返回的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_idstring

    上传任务所属Vault的ID。

  • upload_idstring

    所要进行合并的Multipart Upload任务ID。

  • filesizeint

    所要进行合并的Archive总字节大小。

  • tree_etagstring

    待上传文件的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_idstring

    目标Job任务所属Vault的ID。

  • job_idstring

    目标Job的ID。

  • orangestring

    可选参数。所要下载的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_idstring

    待查询的Vault的ID。

  • markerstring

    可选参数,指明所请求的Job列表起点,与API手册5.4.3节中的请求参数描述一致。

  • limitint

    可选参数,限制返回的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_idstring

    目标Job任务所属Vault的ID。

  • job_idstring

    目标Job任务的ID。

返回值

HTTPResponse

说明

查看指定ID的Job任务状态。对于成功的调用,可通过解析HTTP返回体中的JSON获取相关信息,JSON的各个字段解释详见API手册4.4.4节中的返回体。

  • 本页导读
文档反馈