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

类 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

定义

[backcolor=transparent] def create_vault(self, vault_name)

参数

[backcolor=transparent]vault_name：string
Vault的名称，名称应遵守API手册4.1.1节中Vault命名规范。

返回值

[backcolor=transparent] HTTPResponse

说明

创建指定名称的Vault，并返回Vault ID。可通过res.status检查调用是否成功，对于成功的操作，可通过res.getheader('x-oas-vault-id')获取成功创建的Vault的ID值。

删除Vault

定义

[backcolor=transparent] def delete_vault(self, vault_id)

参数

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

返回值

[backcolor=transparent] HTTPResponse

说明

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

获取Vault信息

定义

[backcolor=transparent] def get_vault_desc(self, vault_id)

参数

[backcolor=transparent]vault_id：string
Vault的ID。

返回值

[backcolor=transparent] HTTPResponse

说明

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

Vault列表

定义

[backcolor=transparent] def list_vault(self, marker=None, limit=None)

参数

[backcolor=transparent]marker：string
可选参数。指明所请求的列表起点，与API手册4.1.4节中的请求参数描述一致。
[backcolor=transparent]limit：int
可选参数。限制返回的Vault数量，与API手册4.1.4节中的请求参数描述一致。

返回值

[backcolor=transparent] HTTPResponse

说明

获取用户的Vault列表。对于成功的调用，可通过解析HTTP返回体中的JSON获取相关信息。可通过rjson['Marker']判断是否还有后续列表，该字段可用于下次请求的marker参数。rjson['VaultList']是Vault描述信息数组。关于JSON的各个字段的更详细解释见API手册4.1.4节中的返回体。

Archive操作

上传Archive

定义

[backcolor=transparent] def post_archive(self, vault_id, content, etag, tree_etag, desc=None)
[backcolor=transparent] def post_archive_from_reader(self, vault_id, reader, content_length, etag, tree_etag, desc=None)

参数

[backcolor=transparent]vault_id：string
指定保存Archive的Vault的ID。
[backcolor=transparent]content
待上传的字节流。
[backcolor=transparent]reader
实现了read接口的对象，如file object。
[backcolor=transparent]content_length：int
待上传的Archive的字节长度。
[backcolor=transparent]etag：string
待上传的文件的etag校验码，详细计算方法请参阅API文档2.5.1一节。
[backcolor=transparent]tree_etag：string
待上传文件的tree_etag校验码。
[backcolor=transparent]desc：string
可选参数。Archive的描述信息。

返回值

[backcolor=transparent] HTTPResponse

说明

上传Archive至指定的Vault，并返回Archive ID。对于已存在于内存的数据，可直接调用[backcolor=transparent]post_archive；对于文件上传，可使用[backcolor=transparent]post_archive_from_reader。所有超出[backcolor=transparent]content_length长度的数据会被忽略。对于成功的操作，可通过res.getheader('x-oas-archive-id')获取相应的Archive ID。关于Archive上传的限制，请参见《OAS API手册-4.2.1节》的描述。

删除Archive

定义

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

参数

[backcolor=transparent]vault_id：string
待删除的Archive所属Vault的ID。

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

返回值

[backcolor=transparent] HTTPResponse

说明

删除指定的Archive。可通过检查res.status判断调用是否成功。

Multipart Upload操作

关于Multipart Upload操作的完整流程请参考API手册1.1.4节。

初始化Multipart Upload任务

定义

[backcolor=transparent] def create_multipart_upload(self, vault_id, partsize, desc=None)

参数

[backcolor=transparent]vault_id：string
上传任务所属Vault的ID。
[backcolor=transparent]partsize：int
指定Part的字节长度，请参阅API手册4.3.1节中描述关于Part长度的限制。
[backcolor=transparent]desc：string
可选参数，Archive的描述信息。

返回值

[backcolor=transparent] HTTPResponse

说明

新建Multipart Upload任务，并返回Upload ID。对于成功的操作，可通过res.getheader('x-oas-multipart-upload-id')获得任务ID，用于后续的Part上传。

获取Multipart Upload任务列表

定义

[backcolor=transparent] def list_multipart_upload(self, vault_id, marker=None, limit=None)

参数

[backcolor=transparent]vault_id：string
待查询的目标Vault的ID。
[backcolor=transparent]marker：string
可选参数，指明所请求的列表起点，与API手册4.3.2节中的请求参数描述一致。
[backcolor=transparent]limit：int
可选参数，限制返回的任务数量，与API手册4.3.2节中的请求参数描述一致。

返回值

[backcolor=transparent] HTTPResponse

说明

获取指定Vault下Multipart Upload任务。对于成功地调用，可通过解析HTTP返回体中的JSON获取相关信息。可通过rjson['Marker']判断是否还有后续列表，该字段可用于下次请求的marker参数。rjson['UploadsList']是任务描述信息数组。关于JSON的各个字段的更详细解释见API手册4.3.2节中的返回体。

删除Multipart Upload任务

定义

[backcolor=transparent] def delete_multipart_upload(self, vault_id, upload_id)

参数

[backcolor=transparent]vault_id：string
待删除的任务所属Vault的ID。
[backcolor=transparent]upload_id：string
待删除任务的ID。

返回值

[backcolor=transparent] HTTPResponse

说明

删除指定任务。可通过res.status检查调用是否成功。

Part上传

定义

[backcolor=transparent] def post_multipart(self, vault_id, upload_id, content, prange, etag, tree_etag)
[backcolor=transparent] def post_multipart_from_reader(self, vault_id, upload_id, reader, content_length, prange, etag, tree_etag)

参数

[backcolor=transparent]vault_id：string
上传任务所属Vault的ID。
[backcolor=transparent]upload_id：string
待上传的Part所属的任务ID。
[backcolor=transparent]content：string
待上传的字节流。
[backcolor=transparent]reader
实现了read接口的对象，如file object。
[backcolor=transparent]partsize：int
待上传的Part的字节长度。
[backcolor=transparent]prange：string
待上传的Part在整个Archive中的字节范围，字节以0开始计数，格式为start-end。prange所指定范围的长度应与partsize一致，所有超出partsize长度的数据会被忽略。除最后一个Part外，partsize应与初始化Multipart Upload任务时所指定的partsize一致。参数定义与API手册4.3.4一节中描述部分一致。
[backcolor=transparent]etag：string
待上传的Part的etag校验码，详细计算方法请参阅API文档2.5.2一节。
[backcolor=transparent]tree_etag：string
待上传Part的tree_etag校验码。

返回值

[backcolor=transparent] HTTPResponse

说明

上传Archive中指定字节范围的Part，注意prange定义应符合API手册指定的规范。对于已存在于内存的数据，可直接调用[backcolor=transparent]post_multipart；对于文件上传，可使用[backcolor=transparent]post_multipart_from_reader。可通过res.status检查上传是否成功。

获取Part列表

定义

[backcolor=transparent] def list_multipart(self, vault_id, upload_id, marker=None, limit=None)

参数

[backcolor=transparent]vault_id：string
上传任务所属Vault的ID。
[backcolor=transparent]upload_id：string
待查询的目标Multipart Upload任务的ID。
[backcolor=transparent]marker：string
可选参数。指明所请求的Part列表起点，与API手册4.3.5节中的请求参数描述一致。
[backcolor=transparent]limit：int

可选参数。限制返回的Part数量，与API手册4.3.5节中的请求参数描述一致。

返回值

[backcolor=transparent] HTTPResponse

说明

获取目标Vault下指定Multipart Upload任务已上传完成的Part列表。对于成功的调用，可通过解析HTTP返回体中的JSON获取相关信息。可通过rjson['Marker']判断是否还有后续列表，该字段可用于下次请求的marker参数。rjson['Parts']是Part描述信息数组。关于JSON的各个字段的更详细解释见API手册4.3.5节中的返回体。

Part合并

定义

[backcolor=transparent] def complete_multipart_upload(self, vault_id, upload_id, filesize, tree_etag)

参数

[backcolor=transparent]vault_id：string
上传任务所属Vault的ID。
[backcolor=transparent]upload_id：string
所要进行合并的Multipart Upload任务ID。
[backcolor=transparent]filesize：int
所要进行合并的Archive总字节大小。
[backcolor=transparent]tree_etag：string
待上传文件的tree-etag校验码。

返回值

[backcolor=transparent] HTTPResponse

说明

对某个已完成所有Part上传的任务进行合并。可通过res.status检查合并是否成功。对于成功的操作，可通过res.getheader('x-oas-archive-id')获取成功合并后创建的Archive ID。

Job操作

初始化Job任务

定义

[backcolor=transparent] def create_job(self, vault_id, job_type, archive_id=None, desc=None, byte_range=None)
[backcolor=transparent] def create_oss_transfer_job(self, vault_id, job_type, osshost, bucket, object, archive_id=None, desc=None)

参数

[backcolor=transparent]vault_id
Job任务所属Vault的ID。
[backcolor=transparent]job_type
任务类型。可选值为archive-retrieval和inventory-retrieval。与API文档4.4.1一节中的请求体中的Type描述一致。
[backcolor=transparent]archive_id
当job_type为inventory-retrieval时，忽略该参数。当 job_type为archive-retrieval时，该参数是指待下载的Archive的ID。
[backcolor=transparent]desc
可选参数。Job任务的描述信息。
[backcolor=transparent]byte_range
可选参数。待下载的Archive字节范围，与API文档4.4.1一节中的请求体中得RetrievalByteRange描述一致。
[backcolor=transparent]osshost
当job_type为pull-from-oss或push-to-oss时，该参数是指转储job的oss域名。
[backcolor=transparent]bucket
当job_type为pull-from-oss或push-to-oss时，该参数是指转储job的oss bucket。
[backcolor=transparent]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下载

定义

[backcolor=transparent] def fetch_job_output(self, vault_id, job_id, orange=None)

参数

[backcolor=transparent]vault_id：string
目标Job任务所属Vault的ID。
[backcolor=transparent]job_id：string
目标Job的ID。
[backcolor=transparent]orange：string
可选参数。所要下载的Job输出字节范围，格式为start-end，字节以0开始计数。参数定义与API手册5.4.3一节中描述部分一致。

返回值

[backcolor=transparent] HTTPResponse

说明

下载已完成的Job任务输出的结果。对于Job类型为[backcolor=transparent]inventory-retrieval的任务，rjson['ArchiveList']是所查询的Archive列表信息。关于JSON的各个字段的更详细解释见API手册5.4.2一节中返回体的描述。对于Job类型为[backcolor=transparent]archive-retrieval的任务，HTTP返回体是所请求范围的字节。对于大文件的下载，建议设置orange参数分块下载。

获取Job列表

定义

[backcolor=transparent] def list_job(self, vault_id, marker=None, limit=None)

参数

[backcolor=transparent]vault_id：string
待查询的Vault的ID。
[backcolor=transparent]marker：string
可选参数，指明所请求的Job列表起点，与API手册5.4.3节中的请求参数描述一致。
[backcolor=transparent]limit：int
可选参数，限制返回的Job数量，与API手册5.4.3节中的请求参数描述一致。

返回值

[backcolor=transparent] HTTPResponse

说明

获取指定Vault下的Job列表。对于成功的调用，可通过解析HTTP返回体中的JSON获取相关信息。可通过rjson['Marker']判断是否还有后续列表，该字段可用于下次请求的marker参数。rjson['JobList']是Job描述信息数组。关于JSON的各个字段的更详细解释见API手册5.4.3节中的返回体。

Job任务状态查询

定义

[backcolor=transparent] def get_jobdesc(self, vault_id, job_id)

参数