华为云用户手册

响应示例 状态码：400 错误响应 { "errCode" : "SFS.TURBO.0123", "errMsg" : "feature invalid" } 状态码：404 错误响应 { "errCode" : "SFS.TURBO.0124", "errMsg" : "task_id not found" } 状态码：500 错误响应 { "errCode" : "SFS.TURBO.0005", "errMsg" : "Internal server error" }

请求示例 ID为"77ba6f4b-6365-4895-8dda-bc7142af4dde"的文件系统，删除任务ID为"11abef677ac40f46644d1d5cfc2424a4"的DU任务 DELETE HTTPS://{endpoint}/v1/{project_id}/sfs-turbo/shares/77ba6f4b-6365-4895-8dda-bc7142af4dde/fs/dir-usage/tasks/11abef677ac40f46644d1d5cfc2424a4

URI DELETE /v1/{project_id}/sfs-turbo/shares/{share_id}/fs/{feature}/tasks/{task_id} 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 项目ID share_id 是 String 文件系统ID feature 是 String 任务类型。例，DU任务取值为dir-usage task_id 是 String 任务ID

响应示例 状态码：200 请求已被接受 { "jobId" : "72362dxxxxa04d419dbd5e6d9fe5xxxx" } 状态码：400 客户端错误 { "errCode" : "SFS.TURBO.0001", "errMsg" : "Invalid rule id" } 状态码：500 内部错误 { "errCode" : "SFS.TURBO.0005", "errMsg" : "Internal server error" }

响应示例 状态码：202 Accepted { "task_id" : "7bd2a9b6-xxxx-4605-xxxx-512d636001b0" } 状态码：400 客户端错误 { "errCode" : "SFS.TURBO.0001", "errMsg" : "parameter error" } 状态码：500 内部错误 { "errCode" : "SFS.TURBO.0005", "errMsg" : "Internal server error" }

接口约束 在2023年8月1号之后创建的文件系统支持该API操作。如果存在10个正在执行的任务，则不允许创建新任务。该接口并发请求数过大可能会影响文件系统性能，建议同时提交的查询请求不要超过4 个。查询超大目录耗时较久，请不要重复提交。API请求路径的feature仅支持以下取值： dir-usage 该接口仅适用于以下类型: 20MB/s/TiB 40MB/s/TiB 125MB/s/TiB 250MB/s/TiB 500MB/s/TiB 1000MB/s/TiB HPC缓存型文件系统 标准型、标准型-增强版、性能型、性能型-增强版类型的SFS Turbo文件系统，请使用“查询目录资源使用情况”接口。

响应示例 状态码：202 Accepted { "task_id" : "d651ea2b-2b20-4c6d-8bbf-2adcec18dac9" } 状态码：400 错误响应 { "errCode" : "SFS.TURBO.0123", "errMsg" : "feature invalid" } 状态码：500 错误响应 { "errCode" : "SFS.TURBO.0005", "errMsg" : "internal server error" }

响应参数 状态码：202 表4 响应Header参数 参数 参数类型 描述 X-request-id String 请求ID 表5 响应Body参数 参数 参数类型 描述 task_id String 任务ID 状态码：400 表6 响应Header参数 参数 参数类型 描述 X-request-id String 请求ID 表7 响应Body参数 参数 参数类型 描述 errCode String 错误码 errMsg String 错误描述 状态码：500 表8 响应Header参数 参数 参数类型 描述 X-request-id String 请求ID 表9 响应Body参数 参数 参数类型 描述 errCode String 错误码 errMsg String 错误描述

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 是 String 账号的token Content-Type 是 String MIME类型 表3 请求Body参数 参数 是否必选 参数类型 描述 change_name 是 ShareName object 需要修改的SFS Turbo文件系统 表4 ShareName 参数 是否必选 参数类型 描述 name 是 String 需要修改的SFS Turbo文件系统的名字

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 是 String 账号的token Content-Type 是 String MIME类型 表3 请求Body参数 参数 是否必选 参数类型 描述 change_security_group 是 ChangeSecurityGroup object change_security_group对象 表4 ChangeSecurityGroup 参数 是否必选 参数类型 描述 security_group_id 是 String 需要修改的目标安全组ID。

请求示例 批量添加共享标签，第一个标签的键为“key1”，值为“value1”；第二个标签的键为“key2”，值为“value1”。 { "action" : "create", "tags" : [ { "key" : "key1", "value" : "value1" }, { "key" : "key2", "value" : "value1" } ] }

开机自动挂载并行文件系统 以下内容以CentOS 7操作系统为例，介绍如何配置开机自动挂载。 使用root用户登录Linux运行机。 执行以下命令，创建一个/home/startobsfs.sh脚本文件。 vi /home/startobsfs.sh 按i进入编辑模式，将以下命令写入/home/startobsfs.sh脚本文件。 #!/bin/bash cd obsfs所在的绝对路径 ./obsfs 并行文件系统名 本地挂载目录 -o url=区域终端节点地址 -o passwd_file=密钥文件路径 -o big_writes -o max_write=131072 -o use_ino 挂载参数 挂载命令参数说明请参见“手动挂载并行文件系统”部分的步骤3。 按Esc键，输入:wq，保存并退出脚本文件。 执行以下命令，赋予root用户对脚本的可执行权限。 chmod +x /home/startobsfs.sh 执行以下命令，赋予root用户对rc.local文件的执行权限。 chmod +x /etc/rc.d/rc.local 不同操作系统的rc.local文件位置不同，在CentOS 7中，该文件位置为/etc/rc.d/rc.local。 编辑/etc/rc.d/rc.local文件，将以下命令添加至文件末尾，保存并退出。 bash /home/startobsfs.sh 如果/etc/rc.d/rc.local中有退出的命令，例如“exit 0”，请将本步骤中的命令添加至退出命令之前。 重启后验证。 在重启Linux后，执行以下命令，查看OBS并行文件系统是否挂载成功。 df -h 后续如果想取消开机自动挂载并行文件系统，删除rc.local文件中执行obsfs挂载命令的脚本文件即可。

命令示例 此处以挂载一个华北-北京一区域的“filesystem001”并行文件系统、obsfs密钥文件路径为“/etc/passwd-obsfs”作为前提条件提供如下挂载命令示例，介绍挂载OBS并行文件系统时的一些参数配置。 将并行文件系统“filesystem001”挂载至“/mnt/mount_path/”目录，并允许该目录为非空： ./obsfs filesystem001 /mnt/mount_path/ -o url=obs.cn-north-1.myhuaweicloud.com -o passwd_file=/etc/passwd-obsfs -o big_writes -o max_write=131072 -o nonempty -o use_ino 将并行文件系统“filesystem001”挂载至“/mnt/mount_path/”目录，并设置写缓存大小： ./obsfs filesystem001 /mnt/mount_path/ -o url=obs.cn-north-1.myhuaweicloud.com -o passwd_file=/etc/passwd-obsfs -o big_writes -o max_write=131072 -o max_background=100 -o use_ino 将并行文件系统“filesystem001”挂载至“/mnt/mount_path/”目录，并允许其他用户访问该目录： ./obsfs filesystem001 /mnt/mount_path/ -o url=obs.cn-north-1.myhuaweicloud.com -o passwd_file=/etc/passwd-obsfs -o big_writes -o max_write=131072 -o allow_other -o use_ino

约束与限制 obsfs只支持挂载OBS并行文件系统，不支持挂载对象存储桶。 本地挂载目录可以不为空，但是挂载后此目录下原有的内容将不可用，取消挂载后即可恢复。建议使用空目录作为挂载目录。 挂载目录中的文件或文件夹不支持硬链接命令。 创建的目录深度不超过45层。 每次通过命令手动挂载的并行文件系统，在Linux重启后，都需要重新挂载。 并行文件系统的容量请以实际使用情况为准。 您也可以设置开机自动挂载并行文件系统，具体操作请参见开机自动挂载并行文件系统。 一个并行文件系统支持挂载到多台云服务器，但数据一致性需由您自行维护，避免出现多台云服务器同时对一个文件并发写入的情况。 桶级的桶策略和 IAM 策略对obsfs挂载方式生效，目录级的桶策略和IAM策略对obsfs挂载方式访问不生效。

手动挂载并行文件系统 打开命令行终端。 使用cd命令进入obsfs所在目录。 按照以下格式执行挂载命令。 ./obsfs 并行文件系统名 本地挂载目录 -o url=区域终端节点地址 -o passwd_file=密钥文件路径 -o big_writes -o max_write=131072 -o use_ino 其他挂载参数 并行文件系统名：输入待挂载的并行文件系统名称。 支持将并行文件系统中特定目录挂载到本地。用户使用此种方式挂载，进入本地挂载目录后，仅能访问并行文件系统中的特定目录。挂载命令如下： ./obsfs 并行文件系统名:/目录名 本地挂载目录 -o url=区域终端节点地址 -o passwd_file=密钥文件路径 -o big_writes -o max_write=131072 -o use_ino 其他挂载参数 本地挂载目录：输入待挂载目录的绝对路径或相对路径。 区域终端节点地址：根据待挂载并行文件系统所在区 域名 称获取对应的终端节点地址，具体信息请参见地区和终端节点。 挂载参数 挂载参数（除passwd_file、use_ino外）为可选项，根据需求选择合适的参数组合，格式为：-o 参数名称=参数值。在不需要设置参数值的情况下，直接使用-o 参数名称 即可。OBS支持的挂载参数及说明如表1所示。 关于obsfs挂载时的参数设置，可执行./obsfs --help命令了解更多。 表1 挂载参数说明 参数名称 参数值 说明 passwd_file 类型：String 取值：根据初始化obsfs配置的密钥文件路径进行设置。 密钥文件路径，使用obsfs时将从此路径中获取AK和SK信息，以对用户身份进行验证。 use_ino 需要 使用该选项，由obsfs分配inode编号。 big_writes 不需要 配置后可更改写缓存最大值大小。 max_write 类型：int 推荐取值：128KB 仅配置big_writes的情况下才生效，默认写大小为4KB，推荐使用128KB。 nonempty 不需要 允许挂载目录非空。 allow_other 不需要 允许其他用户访问并行文件系统。 max_background 类型：int 推荐取值：100 可配置后台最大等待请求数。 use_path_request_style 不需要 当采用路径式（使用legacy API 调用风格）访问OBS时，请使用该参数。 说明： 当url参数值为IP地址时，挂载命令必须携带此参数，否则会报域名解析错误。 umask 不需要 配置文件权限的掩码，使用此参数会覆盖并行文件系统内所有文件的权限。 说明： 使用umask配置后，挂载目录下文件权限会被覆盖为777 - umask 使用示例：-o umask=xxx 设置umask为777：文件系统中所有文件权限为000 设置umask为000：文件系统中所有文件权限为777 设置umask为002：文件系统中所有文件权限为775 obsfslog 不需要 从配置文件加载日志配置参数，包括日志模式、级别等。使用此参数可以在不重启进程的情况下，更改日志级别。 说明： 配置文件路径固定为：/etc/obsfsconfig，如果要使用此参数，需要手动在本地创建此路径并参照以下示例及注释写入内容。 配置文件内容示例： //日志模式。值为0，日志模式为前台显示。值为1，模式为生成日志文件，路径：/var/log/obsfs，以进程号命名。值为2，模式为日志写入系统日志。 dbglogmode=1 //日志级别。dbg、info、warn、err、crit。日志级别为dbg或info时，会打印业务详细信息，例如：桶名、文件名等。 dbglevel=info 执行以下命令，检查挂载结果。 df -h 当界面显示如下类似回显信息时，表示OBS并行文件系统挂载成功。 Filesystem Size Used Avail Use% Mounted on obsfs 256T 0 256T 0% /path/to/mountpoint 并行文件系统的容量请以实际使用情况为准。 如果没有显示以上类似回显信息，表示OBS并行文件系统挂载失败。此时可在执行的挂载命令后面添加以下参数，用以在回显中输出挂载过程以及详细调试日志： -d -d -f -o f2 -o curldbg 然后再根据具体的错误信息进行问题定位，常见异常处理请参考挂载并行文件系统失败。

功能说明 使用多段上传特性时，用户必须首先调用创建多段上传任务接口创建任务，系统会给用户返回一个全局唯一的多段上传任务号，作为任务标识。后续用户可以根据这个标识发起相关的请求，如：上传段、合并段、列举段等。创建多段上传任务不影响已有的同名对象；同一个对象可以同时存在多个多段上传任务；每个多段上传任务在初始化时可以附加消息头信息，包括acl、用户自定义元数据和通用的HTTP消息头contentType、contentEncoding等，这些附加的消息头信息将先记录在多段上传任务元数据中。 在指定桶中初始化分段上传任务。

返回结果 表8 返回结果 类型 说明 GetResult 参数解释： SDK公共结果对象。 表9 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时为空。该值根据调用接口的不同而不同，参见“桶相关接口”章节和“对象相关接口”章节的详细描述。 默认取值： 无

接口约束 您必须是桶拥有者或拥有初始化分段上传任务的权限，才能初始化分段上传任务。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject权限，如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。 OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。 初始化上传段任务并上传一个或多个段之后，您必须合并段或取消多段上传任务，才能停止收取已上传的段的存储费用。仅当在合并段或取消多段上传任务之后，OBS才释放段存储并停止向您收取段存储费用。

接口约束 您必须是桶拥有者或拥有创建文件夹的权限，才能创建文件夹。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject权限，如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。 OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。 创建文件夹本质上来说是创建了一个大小为0且对象名以“/”结尾的对象。 OBS在创建多层级文件夹时，只会创建最后一级文件夹。例如，创建多层级文件夹“src1/src2/src3/”时，不会自动创建文件夹“src1/”、“src1/src2/”，只会创建一个名为“src1/src2/src3/”的文件夹。

返回结果 表9 返回结果 类型 说明 GetResult 参数解释： SDK公共结果对象。 表10 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时为空。该值根据调用接口的不同而不同，参见“桶相关接口”章节和“对象相关接口”章节的详细描述。 默认取值： 无 表11 GetResult.body GetResult.body类型 说明 PutContentResponse 参数解释： 上传对象响应结果，参考PutContentResponse。 表12 PutContentResponse 参数名称 参数类型 描述 storageClass str 参数解释： 对象的存储类型。 取值范围： 当对象存储类型是标准存储时，该值为空。 可选择的存储类型参见StorageClass。 默认取值： 无 versionId str 参数解释： 对象的版本号。如果桶的多版本状态为开启，则会返回对象的版本号。 取值范围： 长度为32的字符串。 默认取值： 无 etag str 参数解释： 对象的etag值，即base64编码的128位MD5摘要。etag是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。比如上传对象时etag为A，下载对象时etag为B，则说明对象内容发生了变化。etag只反映变化的内容，而不是其元数据。上传的对象或拷贝操作创建的对象，都有唯一的etag。 约束限制： 当对象是服务端加密的对象时，etag值不是对象的MD5值。 取值范围： 长度为32的字符串。 默认取值： 无 sseKms str 参数解释： SSE-KMS方式的算法。 取值范围： kms，即以SSE-KMS方式加密对象。 默认取值： 无 sseKmsKey str 参数解释： SSE-KMS加密方式下使用的KMS主密钥的ID值。 取值范围： 有效值支持两种格式： regionID:domainID(账号ID):key/key_id key_id 其中： regionID是使用密钥所属region的ID，可在地区和终端节点页面获取； domainID是使用密钥所属账号的账号ID，获取方法参见如何获取账号ID和用户ID?(Python SDK)； key_id是从 数据加密 服务创建的密钥ID，获取方法请参见查看密钥。 默认取值： 如果用户没有提供该头域，那么默认的主密钥将会被使用。 如果默认主密钥不存在，将默认创建并使用。 sseC str 参数解释： SSE-C方式的算法。 取值范围： AES256。 默认取值： 无 sseCKeyMd5 str 参数解释： SSE-C方式下加密使用密钥的MD5值，该值用于验证密钥传输过程中是否出错。 约束限制： 由密钥值经过MD5加密再经过Base64编码后得到，示例：4XvB3tbNTN+tIEVa0/fGaQ== 默认取值： 无 objectUrl str 参数解释： 对象的全路径。 默认取值： 无

请求参数 表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的字符串。 默认取值： 无 content str 或 readable object 可选 参数解释： 待上传对象的内容。 取值范围： 字符串或者可读对象。 说明： 如果content是可读对象（包含“read”属性），则从中读取数据，否则作为字符串处理。 默认取值： 无 metadata dict 可选 参数解释： 待上传对象的自定义元数据。OBS支持用户使用以“x-obs-meta-”开头的消息头来加入自定义的元数据，以便对对象进行自定义管理。当用户获取此对象或查询此对象元数据时，加入的自定义元数据将会在返回的消息头中出现。 约束限制： 所有自定义元数据大小的总和不超过8K。单个自定义元数据大小的计算方式为：每个键和值的UTF-8 编码中的字节总数。 自定义元数据的key值不区分大小写，OBS统一转为小写进行存储。value值区分大小写。 自定义元数据key-value对都必须符合US-ASCII标准。如果一定要使用非ASCII码或不可识别字符，需要客户端自行做编解码处理，可以采用URL编码或者Base64编码，服务端不会做解码处理。例如x-obs-meta-中文：中文 经URL编码后发送，“中文”的URL编码为：%E4%B8%AD%E6%96%87，则响应为x-obs-meta-%E4%B8%AD%E6%96%87: %E4%B8%AD%E6%96%87 默认取值： 无 headers PutObjectHeader 可选 参数解释： 上传对象的头域，用于设置对象的基本信息，包括存储类别、冗余策略等。 取值范围： 参考PutObjectHeader。 默认取值： 无 progressCallback callable 可选 参数解释： 获取上传进度的回调函数。 默认取值： 无 说明： 该回调函数依次包含三个参数：已上传的字节数、总字节数、已使用的时间（单位：秒），示例代码参考上传对象-获取上传进度。 上传进度回调功能仅支持流式上传、文件上传、上传段、追加上传和断点续传上传。 autoClose bool 可选 参数解释： 上传完成后，自动关闭数据流。 取值范围： True：自动关闭数据流。 False：不开启自动关闭数据流。 默认取值： True extensionHeaders dict 可选 参数解释： 接口的拓展头域。 取值范围： 参考自定义头域。 默认取值： 无

返回结果 表9 返回结果 类型 说明 GetResult 参数解释： SDK公共结果对象。 表10 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时为空。该值根据调用接口的不同而不同，参见“桶相关接口”章节和“对象相关接口”章节的详细描述。 默认取值： 无 表11 GetResult.body GetResult.body类型 说明 PutContentResponse 参数解释： 上传对象响应结果，参考PutContentResponse。 表12 PutContentResponse 参数名称 参数类型 描述 storageClass str 参数解释： 对象的存储类型。 取值范围： 当对象存储类型是标准存储时，该值为空。 可选择的存储类型参见StorageClass。 默认取值： 无 versionId str 参数解释： 对象的版本号。如果桶的多版本状态为开启，则会返回对象的版本号。 取值范围： 长度为32的字符串。 默认取值： 无 etag str 参数解释： 对象的etag值，即base64编码的128位MD5摘要。etag是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。比如上传对象时etag为A，下载对象时etag为B，则说明对象内容发生了变化。etag只反映变化的内容，而不是其元数据。上传的对象或拷贝操作创建的对象，都有唯一的etag。 约束限制： 当对象是服务端加密的对象时，etag值不是对象的MD5值。 取值范围： 长度为32的字符串。 默认取值： 无 sseKms str 参数解释： SSE-KMS方式的算法。 取值范围： kms，即以SSE-KMS方式加密对象。 默认取值： 无 sseKmsKey str 参数解释： SSE-KMS加密方式下使用的KMS主密钥的ID值。 取值范围： 有效值支持两种格式： regionID:domainID(账号ID):key/key_id key_id 其中： regionID是使用密钥所属region的ID，可在地区和终端节点页面获取； domainID是使用密钥所属账号的账号ID，获取方法参见如何获取账号ID和用户ID?(Python SDK)； key_id是从数据加密服务创建的密钥ID，获取方法请参见查看密钥。 默认取值： 如果用户没有提供该头域，那么默认的主密钥将会被使用。 如果默认主密钥不存在，将默认创建并使用。 sseC str 参数解释： SSE-C方式的算法。 取值范围： AES256。 默认取值： 无 sseCKeyMd5 str 参数解释： SSE-C方式下加密使用密钥的MD5值，该值用于验证密钥传输过程中是否出错。 约束限制： 由密钥值经过MD5加密再经过Base64编码后得到，示例：4XvB3tbNTN+tIEVa0/fGaQ== 默认取值： 无 objectUrl str 参数解释： 对象的全路径。 默认取值： 无

接口约束 您必须是桶拥有者或拥有上传对象的权限，才能上传对象。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject权限，如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。 OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。 单次上传对象大小范围是[0, 5GB]。 如果需要上传超过5GB的大文件，需要通过多段操作来分段上传。

返回结果 表10 返回结果 类型 说明 GetResult 参数解释： SDK公共结果对象。 表11 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时为空。该值根据调用接口的不同而不同，参见“桶相关接口”章节和“对象相关接口”章节的详细描述。 默认取值： 无 表12 GetResult.body GetResult.body类型 说明 AppendObjectResponse 参数解释： 追加上传的响应结果，参考AppendObjectResponse。 表13 AppendObjectResponse 参数名称 参数类型 描述 storageClass str 参数解释： 对象的存储类型。 取值范围： 当对象存储类型是标准存储时，该值为空。 可选择的存储类型参见StorageClass。 默认取值： 无 etag str 参数解释： 对象的etag值，即base64编码的128位MD5摘要。etag是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。比如上传对象时etag为A，下载对象时etag为B，则说明对象内容发生了变化。etag只反映变化的内容，而不是其元数据。上传的对象或拷贝操作创建的对象，都有唯一的etag。 约束限制： 当对象是服务端加密的对象时，etag值不是对象的MD5值。 取值范围： 长度为32的字符串。 默认取值： 无 nextPosition int 参数解释： 下次追加上传的位置。 取值范围： 大于等于0的整型数，单位：字节。 默认取值： 无 sseKms str 参数解释： SSE-KMS方式的算法。 取值范围： kms，即以SSE-KMS方式加密对象。 默认取值： 无 sseKmsKey str 参数解释： SSE-KMS加密方式下使用的KMS主密钥的ID值。 取值范围： 有效值支持两种格式： regionID:domainID(账号ID):key/key_id key_id 其中： regionID是使用密钥所属region的ID，可在地区和终端节点页面获取； domainID是使用密钥所属账号的账号ID，获取方法参见如何获取账号ID和用户ID?(Python SDK)； key_id是从数据加密服务创建的密钥ID，获取方法请参见查看密钥。 默认取值： 如果用户没有提供该头域，那么默认的主密钥将会被使用。 如果默认主密钥不存在，将默认创建并使用。 sseC str 参数解释： SSE-C方式的算法。 取值范围： AES256。 默认取值： 无 sseCKeyMd5 str 参数解释： SSE-C方式下加密使用密钥的MD5值，该值用于验证密钥传输过程中是否出错。 约束限制： 由密钥值经过MD5加密再经过Base64编码后得到，示例：4XvB3tbNTN+tIEVa0/fGaQ== 默认取值： 无 objectUrl str 参数解释： 对象的全路径。 默认取值： 无

接口约束 您必须是桶拥有者或拥有上传对象的权限，才能上传对象。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject权限，如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。 OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。 用户上传的对象存储在桶中。用户必须对桶有WRITE权限，才可以在桶中上传对象。同一个桶中存储的对象名必须是唯一的。 每次追加上传都会更新该对象的最后修改时间。 服务端加密SSE-C方式，那么追加上传和初始化段一样，设置诸如x-obs-server-side-encryption之类的请求Header，后续追加上传也必须携带。 服务端加密SSE-KMS方式，有且只有第一次上传且桶内不存在同名对象时，才设置诸如x-obs-server-side-encryption之类的请求Header，后续追加上传不携带。 每次追加上传的长度不能超过对象长度上限5G的限制。 每个Appendable对象追加写次数最多为10000次。 如果对象存储类型为COLD（归档存储）或深度归档存储，则不能调用该接口。 如果桶设置了跨区域复制配置，则不能调用该接口。 并行文件系统不支持追加写对象。

返回结果 表9 返回结果 类型 说明 GetResult 参数解释： SDK公共结果对象。 表10 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时为空。该值根据调用接口的不同而不同，参见“桶相关接口”章节和“对象相关接口”章节的详细描述。 默认取值： 无 表11 GetResult.body GetResult.body类型 说明 PutContentResponse 参数解释： 上传对象响应结果，参考PutContentResponse。 默认取值： 无 如果file_path是文件夹，则返回结果为包含一组GetResult的列表。 表12 PutContentResponse 参数名称 参数类型 描述 storageClass str 参数解释： 对象的存储类型。 取值范围： 当对象存储类型是标准存储时，该值为空。 可选择的存储类型参见StorageClass。 默认取值： 无 versionId str 参数解释： 对象的版本号。如果桶的多版本状态为开启，则会返回对象的版本号。 取值范围： 长度为32的字符串。 默认取值： 无 etag str 参数解释： 对象的etag值，即base64编码的128位MD5摘要。etag是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。比如上传对象时etag为A，下载对象时etag为B，则说明对象内容发生了变化。etag只反映变化的内容，而不是其元数据。上传的对象或拷贝操作创建的对象，都有唯一的etag。 约束限制： 当对象是服务端加密的对象时，etag值不是对象的MD5值。 取值范围： 长度为32的字符串。 默认取值： 无 sseKms str 参数解释： SSE-KMS方式的算法。 取值范围： kms，即以SSE-KMS方式加密对象。 默认取值： 无 sseKmsKey str 参数解释： SSE-KMS加密方式下使用的KMS主密钥的ID值。 取值范围： 有效值支持两种格式： regionID:domainID(账号ID):key/key_id key_id 其中： regionID是使用密钥所属region的ID，可在地区和终端节点页面获取； domainID是使用密钥所属账号的账号ID，获取方法参见如何获取账号ID和用户ID?(Python SDK)； key_id是从数据加密服务创建的密钥ID，获取方法请参见查看密钥。 默认取值： 如果用户没有提供该头域，那么默认的主密钥将会被使用。 如果默认主密钥不存在，将默认创建并使用。 sseC str 参数解释： SSE-C方式的算法。 取值范围： AES256。 默认取值： 无 sseCKeyMd5 str 参数解释： SSE-C方式下加密使用密钥的MD5值，该值用于验证密钥传输过程中是否出错。 约束限制： 由密钥值经过MD5加密再经过Base64编码后得到，示例：4XvB3tbNTN+tIEVa0/fGaQ== 默认取值： 无 objectUrl str 参数解释： 对象的全路径。 默认取值： 无

功能说明 您可以将本地文件直接通过Internet上传至OBS指定的桶中。待上传的文件可以是任何类型：文本文件、图片、视频等。 OBS本身是没有文件夹的概念的，桶中存储的元素只有对象。创建文件夹实际上是创建了一个大小为0且对象名以“/”结尾的对象，这类对象与其他对象无任何差异，可以进行下载、删除等操作，只是OBS控制台会将这类以“/”结尾的对象以文件夹的方式展示。 如果开启了多版本控制，上传对象时，OBS自动为每个对象创建唯一的版本号。上传同名的对象将以不同的版本号同时保存在OBS中。如果未开启多版本控制，向同一个文件夹中上传同名的对象时，新上传的对象将覆盖原有的对象。 调用接口时，支持在extensionHeaders参数中以字典形式传入指定的头域，详情请参见自定义头域(Python SDK)。

接口约束 您必须是桶拥有者或拥有上传对象的权限，才能上传对象。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject权限，如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。 OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。 单次上传对象大小范围是[0, 5GB]。 如果需要上传超过5GB的大文件，需要通过多段操作来分段上传。

请求参数 表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的字符串。 默认取值： 无 file_path str 必选 参数解释： 待上传文件或者文件夹的完整路径，如aa/bb.txt，或aa/。 默认取值： 无 说明： 如果file_path是文件夹，则headers中的contentLength，md5和contentType会被忽略。 metadata dict 可选 参数解释： 待上传对象的自定义元数据。OBS支持用户使用以“x-obs-meta-”开头的消息头来加入自定义的元数据，以便对对象进行自定义管理。当用户获取此对象或查询此对象元数据时，加入的自定义元数据将会在返回的消息头中出现。 约束限制： 所有自定义元数据大小的总和不超过8K。单个自定义元数据大小的计算方式为：每个键和值的UTF-8 编码中的字节总数。 自定义元数据的key值不区分大小写，OBS统一转为小写进行存储。value值区分大小写。 自定义元数据key-value对都必须符合US-ASCII。如果一定要使用非ASCII码或不可识别字符，需要客户端自行做编解码处理，可以采用URL编码或者Base64编码，服务端不会做解码处理。例如x-obs-meta-中文：中文 经URL编码后发送，“中文”的URL编码为：%E4%B8%AD%E6%96%87，则响应为x-obs-meta-%E4%B8%AD%E6%96%87: %E4%B8%AD%E6%96%87 默认取值： 无 headers PutObjectHeader 可选 参数解释： 上传对象的头域，用于设置对象的基本信息，包括存储类别、冗余策略等。 取值范围： 参考PutObjectHeader。 默认取值： 无 progressCallback callable 可选 参数解释： 获取上传进度的回调函数。 约束限制： 不支持获取上传文件夹的上传进度。 默认取值： 无 说明： 该回调函数依次包含三个参数：已上传的字节数、总字节数、已使用的时间（单位：秒），示例代码参考上传对象-获取上传进度。 上传进度回调功能仅支持流式上传、文件上传、上传段、追加上传和断点续传上传。 extensionHeaders dict 可选 参数解释： 接口的拓展头域。 取值范围： 参考自定义头域。 默认取值： 无

接口约束 您必须是桶拥有者或拥有下载对象的权限，才能下载对象。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:GetObject权限，如果使用桶策略则需授予GetObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。 OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。 对于存储类别为归档存储或深度归档存储的对象，需要确认对象的状态为“已恢复”才能对其进行下载。 如果指定的范围无效（比如开始位置、结束位置为负数，大于文件大小），则会返回整个对象。 可以利用范围下载并发下载大对象，详细代码示例请参考concurrent_download_object_sample。