更新时间:2024-03-26 GMT+08:00
分享

分段上传-复制段(Python SDK)

功能说明

初始化分段上传任务后,通过分段上传任务的ID,复制段到指定桶中。

多段上传任务创建后,用户可以通过指定多段上传任务号,为特定的任务上传段。添加段的方式还包括调用段拷贝接口。允许客户将已上传对象的一部分或全部拷贝为段。

将源对象object拷贝为一个段part1,如果在拷贝操作之前part1已经存在,拷贝操作执行之后,旧的段数据part1会被新拷贝的段数据覆盖。拷贝成功后,只能列举到最新的段part1,旧的段数据将会被删除。因此在使用拷贝段接口时请确保目标段不存在或者已无价值,避免因拷贝段导致数据误删除。拷贝过程中源对象object无任何变化。

接口约束

  • 您必须是桶拥有者或拥有复制段的权限,才能复制段。建议使用IAM或桶策略进行授权,如果使用IAM则需授予obs:object:PutObject权限,如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见OBS权限控制概述,配置方式详见使用IAM自定义策略配置对象策略
  • OBS支持的Region与Endpoint的对应关系,详细信息请参见地区与终端节点
  • 拷贝段的结果不能仅根据HTTP返回头域中的status_code来判断请求是否成功,头域中status_code返回200时表示服务端已经收到请求,且开始处理拷贝段请求。拷贝是否成功会在响应消息的body中,只有body体中有ETag标签才表示成功,否则表示拷贝失败。

方法定义

ObsClient.copyPart(bucketName, objectKey, partNumber, uploadId, copySource, copySourceRange, destSseHeader, sourceSseHeader)

请求参数

表1 请求参数列表

参数名称

参数类型

是否必选

描述

bucketName

str

必选

参数解释

目标桶名。

约束限制:

  • 桶的名字需全局唯一,不能与已有的任何桶名称重复,包括其他用户创建的桶。
  • 桶命名规则如下:
    • 3~63个字符,数字或字母开头,支持小写字母、数字、“-”、“.”。
    • 禁止使用IP地址。
    • 禁止以“-”或“.”开头及结尾。
    • 禁止两个“.”相邻(如:“my..bucket”)。
    • 禁止“.”和“-”相邻(如:“my-.bucket”和“my.-bucket”)。
  • 同一用户在同一个区域多次创建同名桶不会报错,创建的桶属性以第一次请求为准。

默认取值:

objectKey

str

必选

参数解释:

对象名。对象名是对象在存储桶中的唯一标识。对象名是对象在桶中的完整路径,路径中不包含桶名。

例如,您对象的访问地址为examplebucket.obs.cn-north-4.myhuaweicloud.com/folder/test.txt 中,对象名为folder/test.txt。

取值范围:

长度大于0且不超过1024的字符串。

默认取值:

说明:

对象链接地址格式为:https://桶名.域名/文件夹目录层级/对象名。如果该对象存在于桶的根目录下,则链接地址将不需要有文件夹目录层级。

partNumber

int

必选

参数解释:

段号。

取值范围:

[1,10000]

默认取值:

uploadId

str

必选

参数解释:

分段上传任务的ID,例如:000001648453845DBB78F2340DD460D8

取值范围:

长度为32的字符串。

默认取值:

copySource

str

必选

参数解释:

指定源桶、源对象和源对象版本号(可为空)的参数,格式:源桶名/源对象名?versionId=源对象版本号。

约束限制:

  • 桶的名字需全局唯一,不能与已有的任何桶名称重复,包括其他用户创建的桶。
  • 桶命名规则如下:
    • 3~63个字符,数字或字母开头,支持小写字母、数字、“-”、“.”。
    • 禁止使用IP地址。
    • 禁止以“-”或“.”开头及结尾。
    • 禁止两个“.”相邻(如:“my..bucket”)。
    • 禁止“.”和“-”相邻(如:“my-.bucket”和“my.-bucket”)。
  • 同一用户在同一个区域多次创建同名桶不会报错,创建的桶属性以第一次请求为准。
  • 对象名是对象在存储桶中的唯一标识。对象名是对象在桶中的完整路径,路径中不包含桶名。

    例如,您对象的访问地址为examplebucket.obs.cn-north-4.myhuaweicloud.com/folder/test.txt 中,对象名为folder/test.txt。

默认取值:

copySourceRange

str

可选

参数解释:

指定复制源对象的范围。例如:0-999,即对象的第1个字节到1000字节。

取值范围:

取值区间:[0,对象长度-1],格式:x-y,即对象的第x+1字节到第y+1字节。

约束限制:

如果range的最大长度超出对象长度-1,仍旧取对象长度-1。

默认取值:

destSseHeader

SseCHeader

SseKmsHeader

可选

参数解释:

服务端加密头域,用于加密目标对象。详见SseCHeaderSseKmsHeader

sourceSseHeader

SseCHeader

可选

参数解释:

服务端解密头域,用于解密源对象。详见SseCHeader

表2 SseCHeader

参数名称

参数类型

是否必选

描述

encryption

str

必选

参数解释:

以SSE-C方式加密对象。

取值范围:

AES256,即高级加密标准(Advanced Encryption Standard,AES)。

默认取值:

key

str

必选

参数解释:

SSE-C方式下加密的密钥,与加密方式对应,如encryption=‘AES256’,name密钥就是由AES256加密算法得到的密钥。

取值范围:

长度为32字符串。

默认取值:

表3 SseKmsHeader

参数名称

参数类型

是否必选

描述

encryption

str

必选

参数解释:

以SSE-KMS方式加密对象。

取值范围:

可选值:kms,即选择SSE-KMS方式加密对象。

默认取值:

key

str

可选

参数解释:

SSE-KMS方式下加密的主密钥。

取值范围:

支持两种格式的密钥描述方式:

  • regionID:domainID(租户ID):key/key_id
  • key_id

其中:

默认取值:

  • 如果用户没有提供该头域,那么默认的主密钥将会被使用。
  • 如果默认主密钥不存在,将默认创建并使用。

返回结果

表4 返回结果

类型

说明

GetResult

参数解释:

SDK公共结果对象。

表5 GetResult

参数名称

参数类型

描述

status

int

参数解释:

HTTP状态码。

取值范围:

状态码是一组从2xx(成功)到4xx或5xx(错误)的数字代码,状态码表示了请求响应的状态。完整的状态码列表请参见状态码

默认取值:

reason

str

参数解释:

HTTP文本描述。

默认取值:

errorCode

str

参数解释:

OBS服务端错误码,当status参数小于300时为空。

默认取值:

errorMessage

str

参数解释:

OBS服务端错误描述,当status参数小于300时为空。

默认取值:

requestId

str

参数解释:

OBS服务端返回的请求ID。

默认取值:

indicator

str

参数解释:

OBS服务端返回的错误定位码。

默认取值:

hostId

str

参数解释:

请求的服务端ID,当status参数小于300时为空。

默认取值:

resource

str

参数解释:

发生错误时相关的桶或对象,当status参数小于300时为空。

默认取值:

header

list

参数解释:

响应消息头列表,由多个元组构成。每个元组均包含两个元素,代表响应头的键值对。

默认取值:

body

object

参数解释:

操作成功后的结果数据,当status大于300时为空。该值根据调用接口的不同而不同,参见“桶相关接口”章节和“对象相关接口”章节的详细描述。

默认取值:

表6 GetResult.body

GetResult.body类型

说明

CopyPartResponse

参数解释:

复制段响应结果。详见CopyPartResponse

表7 CopyPartResponse

参数名称

参数类型

描述

etag

str

参数解释:

段的base64编码的128位MD5摘要。ETag是段内容的唯一标识,可以通过该值识别段内容是否有变化。

取值范围:

长度为32的字符串。

默认取值:

lastModified

str

参数解释:

对象的最近一次修改时间。

约束限制:

日期格式为GMT的格式。 例如:Wed, 25 Mar 2020 02:39:52 GMT。

默认取值:

sseKms

str

参数解释:

表示服务端加密是SSE-KMS方式。对象使用SSE-KMS方式加密。

取值范围:

可选值:kms,即选择SSE-KMS方式加密对象。

默认取值:

sseKmsKey

str

参数解释:

SSE-KMS加密方式下使用的KMS主密钥的ID值。

取值范围:

有效值支持两种格式:

  1. regionID:domainID(账号ID):key/key_id
  2. key_id

其中:

默认取值:

  • 如果用户没有提供该头域,那么默认的主密钥将会被使用。
  • 如果默认主密钥不存在,将默认创建并使用。

sseC

str

参数解释:

使用SSE-C方式加解密对象时,选择的加解密算法。

取值范围:

支持的值为AES256,即高级加密标准(Advanced Encryption Standard,AES)。

默认取值:

sseCKeyMd5

str

参数解释:

SSE-C方式下加密使用密钥的MD5值,该值用于验证密钥传输过程中是否出错。

约束限制:

由密钥值经过MD5加密再经过Base64编码后得到,示例:4XvB3tbNTN+tIEVa0/fGaQ==

默认取值:

代码样例

本示例用于复制段。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
from obs import ObsClient
import os
import traceback

# 推荐通过环境变量获取AKSK,这里也可以使用其他外部引入方式传入,如果使用硬编码可能会存在泄露风险。
# 您可以登录访问管理控制台获取访问密钥AK/SK,获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html。
ak = os.getenv("AccessKeyID")
sk = os.getenv("SecretAccessKey")
# 【可选】如果使用临时AKSK和SecurityToken访问OBS,则同样推荐通过环境变量获取
security_token = os.getenv("SecurityToken")
#  server填写Bucket对应的Endpoint, 这里以华北-北京四为例,其他地区请按实际情况填写。
server = "https://obs.cn-north-4.myhuaweicloud.com"
# 创建obsClient实例
# 如果使用临时AKSK和SecurityToken访问OBS,需要在创建实例时通过security_token参数指定securityToken值
obsClient = ObsClient(access_key_id=ak, secret_access_key=sk, server=server)
try:
    bucketName = "examplebucket"
    objectKey = "objectname"
    # 段号,取值范围:1~10000
    partNumber = "your partNumber"
    # 分段上传任务的ID
    uploadId = "your uploadid"
    # 指定源桶、源对象和源对象版本号(可为空)的参数,格式:源桶名/源对象名?versionId=源对象版本号
    copySource = 'sourcebucketname/sourceobjectkey'
    # 【可选】指定复制源对象的范围,取值区间:[0,源对象长度-1],格式:x-y
    # copySourceRange = '0-15'
    # 通过分段上传任务的ID,复制段到指定桶中
    resp = obsClient.copyPart(bucketName, objectKey, partNumber, uploadId, copySource)

    # 返回码为2xx时,接口调用成功,否则接口调用失败
    if resp.status < 300:
        print('Copy Part Succeeded')
        print('requestId:', resp.requestId)
        print('etagValue:', resp.body.etagValue)
        print('modifiedDate:', resp.body.modifiedDate)
    else:
        print('Copy Part Failed')
        print('requestId:', resp.requestId)
        print('errorCode:', resp.errorCode)
        print('errorMessage:', resp.errorMessage)
except:
    print('Copy Part Failed')
    print(traceback.format_exc())

相关链接

  • 关于分段上传-复制段的API说明,请参见拷贝段
  • 更多关于分段上传的示例代码,请参见Github示例
  • 分段上传过程中返回的错误码含义、问题原因及处理措施可参考OBS错误码
分享:

    相关文档

    相关产品