示例程序_对象存储服务 OBS_SDK参考_Python_华为云

(1)

Python SDK 开发指南

文档版本 11

发布日期 2021-06-07

(2)

非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。

商标声明

和其他华为商标均为华为技术有限公司的商标。

本文档提及的其他所有商标或注册商标，由各自的所有人拥有。

注意

您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示的声明或保证。

由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。

(3)

1 ^简介

本文档提供了对象存储服务OBS Python SDK所有接口的描述与使用方式、方法定义及参数说明等内容。

SDK API 概览

接口名定义方法功能描述

创建桶 ObsClient.createBucket 创建桶。

获取桶列表 ObsClient.listBuckets 查询桶列表，返回结果按

照桶名字典序排列。

判断桶是否存在 ObsClient.headBucket 判断桶是否存在。

删除桶 ObsClient.deleteBucket 删除桶，待删除的桶必须为空。

列举桶内对象 ObsClient.listObjects 列举桶内对象，默认返回

最大1000个对象。

列举桶内多版本对象 ObsClient.listVersions 列举桶内多版本对象，默

认返回最大1000个多版本对象。

列举分段上传任务 ObsClient.listMultipartUp

loads 列举指定桶中所有的初始

化后还未合并或还未取消的分段上传任务。

获取桶元数据 ObsClient.getBucketMeta

data 对桶发送HEAD请求，获

取桶的存储类型，CORS规则（若已设置）等信息。

获取桶区域位置 ObsClient.getBucketLoca

tion 获取桶所在的区域位置。

获取桶存量信息 ObsClient.getBucketStora

geInfo 获取桶的存量信息，包含

桶的空间大小以及对象个数。

(10)

设置桶配额 ObsClient.setBucketQuot

a 设置桶的配值，单位为字

节，支持的最大值为 2⁶³-1，配额值设为0表示桶的配额没有上限。

获取桶配额 ObsClient.getBucketQuot

a 获取桶的配额值，0代表配

额没有上限。

设置桶存储类型 ObsClient.setBucketStora

gePolicy 设置桶的存储类型，桶中

对象的存储类型默认将与桶的存储类型保持一致。

获取桶存储类型 ObsClient.getBucketStora

gePolicy 获取桶的存储类型。

设置桶ACL ObsClient.setBucketAcl 设置桶的访问权限。

获取桶ACL ObsClient.getBucketAcl 获取桶的访问权限。

设置桶日志管理配置 ObsClient.setBucketLoggi

ng 设置桶的访问日志配置。

获取桶日志管理配置 ObsClient.getBucketLogg

ing 获取桶的访问日志配置。

设置桶策略 ObsClient.setBucketPolic

y 配置桶的策略，如果桶已

经存在一个策略，那么当前请求中的策略将完全覆盖桶中现存的策略。

获取桶策略 ObsClient.getBucketPolic

y 获取桶的策略配置。

删除桶策略 ObsClient.deleteBucketP

olicy 删除桶的策略配置。

设置桶的生命周期配置 ObsClient.setBucketLifec

ycle 配置桶的生命周期规则，

实现定时转换桶中对象的存储类型，以及定时删除桶中对象的功能。

获取桶的生命周期配置 ObsClient.getBucketLifec

ycle 获取桶的生命周期规则。

删除桶的生命周期配置 ObsClient.deleteBucketLi

fecycle 删除桶所有的生命周期规

则。

设置桶的Website配置 ObsClient.setBucketWebs

ite 设置桶的Website配置。

获取桶的Website配置 ObsClient.getBucketWeb

site 获取桶的Website配置。

删除桶的Website 配置 ObsClient.deleteBucketW

ebsite 删除指定桶的Website配置。

(11)

设置桶的多版本状态 ObsClient.setBucketVersi

oning 设置桶的多版本状态。

获取桶的多版本状态 ObsClient.getBucketVersi

oning 获取桶的多版本状态。

设置桶的CORS配置 ObsClient.setBucketCors 设置桶的跨域资源共享规

则，以允许客户端浏览器进行跨域请求。

获取桶的CORS配置 ObsClient.getBucketCors 获取指定桶的跨域资源共

享规则。

删除桶的CORS配置 ObsClient.deleteBucketC

ors 删除指定桶的跨域资源共

享规则。

设置桶的事件通知配置 ObsClient.setBucketNotifi

cation 设置桶的事件通知配置，

桶上所发生的指定操作，

都能及时得到通知。

获取桶的事件通知配置 ObsClient.getBucketNotif

ication 获取指定桶的事件通知配

置信息。

设置桶标签 ObsClient.setBucketTaggi

ng 设置桶的标签。

获取桶标签 ObsClient.getBucketTagg

ing 获取指定桶的标签。

删除桶标签 ObsClient.deleteBucketTa

gging 删除指定桶的标签。

上传对象 ObsClient.putContent 上传对象到指定桶中。

上传文件 ObsClient.putFile 上传文件/文件夹到指定桶中。

追加上传 ObsClient.appendObject 对同一个对象追加数据内容。

下载对象 ObsClient.getObject 下载指定桶中的对象。

复制对象 ObsClient.copyObject 为指定桶中的对象创建一个副本。

删除对象 ObsClient.deleteObject 删除指定桶中的对象。

批量删除对象 ObsClient.deleteObjects 批量删除指定桶中的多个

对象。

获取对象元数据 ObsClient.getObjectMeta

data 对指定桶中的对象发送

HEAD请求，获取对象的元数据信息。

修改对象元数据 ObsClient.setObjectMeta

data 对指定桶中的对象的元数

据信息。

(12)

设置对象ACL ObsClient.setObjectAcl 设置指定桶中对象的访问

权限。

获取对象ACL ObsClient.getObjectAcl 获取指定桶中对象的访问

权限。

初始化分段上传任务 ObsClient.initiateMultipa

rtUpload 在指定桶中初始化分段上

传任务。

上传段 ObsClient.uploadPart 初始化分段上传任务后，

通过分段上传任务的ID，

上传段到指定桶中。

复制段 ObsClient.copyPart 初始化分段上传任务后，

通过分段上传任务的ID，

复制段到指定桶中。

列举已上传的段 ObsClient.listParts 通过分段上传任务的ID，

列举指定桶中已上传的段。

合并段 ObsClient.completeMulti

partUpload 通过分段上传任务的ID，

合并指定桶中已上传的段。

取消分段上传任务 ObsClient.abortMultipart

Upload 通过分段上传任务的ID，

取消指定桶中的分段上传任务。

取回归档存储对象 ObsClient.restoreObject 取回指定桶中的归档存储

对象。

生成带授权信息的URL ObsClient.createSignedU

rl 通过访问密钥、请求方法

类型、请求参数等信息生成一个在Query参数中携带鉴权信息的URL，以对 OBS服务进行特定操作。

生成带授权信息的表单上

传参数 ObsClient.createPostSign

ature 生成用于鉴权的请求参

数，以进行基于浏览器的 POST表单上传。

断点续传上传 ObsClient.uploadFile 对分段上传的封装和加

强，解决上传大文件时由于网络不稳定或程序崩溃导致上传失败的问题。

断点续传下载 ObsClient.downloadFile 对范围下载的封装和加

强，解决下载大对象到本地时由于网络不稳定或程序崩溃导致下载失败的问题。

(13)

创建工作流 WorkflowClient.createW

orkflow 根据模板创建工作流。

查询工作流 WorkflowClient.getWorkf

low 按名称查询工作流。

删除工作流 WorkflowClient.deleteW

orkflow 删除存在的工作流。

更新工作流 WorkflowClient.updateW

orkflow 更新工作流。

查询工作流列表 WorkflowClient.listWorkf

low 查询工作流列表。

API触发启动工作流 WorkflowClient.asyncAPI

StartWorkflow API触发启动工作流。

查询工作流实例列表 WorkflowClient.listWorkf

lowExecution 查询工作流实例列表。

查询工作流实例 WorkflowClient.getWorkf

lowExecution 查询工作流实例详细。

恢复失败状态的工作流实例

WorkflowClient.restoreFa

iledWorkflowExecution 当且仅当一个工作流实例是执行失败状态才能执行恢复操作。恢复后，工作流实例将从上次失败的状态处继续执行，而已经执行过的状态不会再执行。

配置桶触发器 WorkflowClient.putTrigg

erPolicy 在桶上绑定工作流触发

器。

查询桶触发器 WorkflowClient.getTrigg

erPolicy 查询桶上绑定工作流触发

器。

删除桶触发器 WorkflowClient.deleteTri

ggerPolicy 删除在桶上绑定工作流触发器。

(14)

2 ^{SDK 下载}

SDK 源码

● OBS Python SDK最新版本源码：最新源码下载

兼容性

● 版本修订记录信息：ChangeLog。

● 推荐使用的Python 2.x版本：Python 2.7.x版本。

● 推荐使用的Python 3.x版本：Python 3.3，Python 3.4，Python 3.5，Python 3.6。

● 命名空间：与旧版本（2.1.x）不兼容，所有模块都调整到obs包下。

● 接口函数：与旧版本（2.1.x）保持兼容。

(15)

3 ^示例程序

OBS Python SDK提供了丰富的示例程序，方便用户参考或直接使用。您可以从OBS Python SDK开发包中获取示例程序，如

eSDK_Storage_OBS_<VersionId>_Python.zip，解压后

eSDK_Storage_OBS_<VersionId>_Python/examples为示例程序。您也可以从下面表格中直接下载示例程序。

示例包括以下内容：

示例代码说明

bucket_operations_sample 展示了桶相关接口的用法 object_operations_sample 展示了对象相关接口的用法

download_sample 展示了下载对象的用法

create_folder_sample 展示了创建文件夹的用法

delete_objects_sample 展示了批量删除对象的用法

list_objects_sample 展示了列举对象的用法

list_versions_sample 展示了列举多版本对象的用法

list_objects_in_folder_sample 展示了列举文件夹内对象的用法

object_meta_sample 展示了自定义对象元数据的用法

simple_multipart_upload_sample 展示了分段上传的基本用法

restore_object_sample 展示了下载归档存储对象的用法

concurrent_copy_part_sample 展示了分段并发复制大对象的用法 concurrent_download_object_sample 展示了分段并发下载大对象的用法 concurrent_upload_part_sample 展示了分段并发上传大对象的用法

post_object_sample 展示了表单上传对象的用法

temporary_signature_sample 展示了使用URL进行授权访问的用法

(16)

4 ^{开发环境搭建}

● 从Python官网下载并安装合适的Python版本。

● 从PyCharm官网下载并安装最新社区版本。

(17)

5 ^{安装 SDK}

使用 pip 安装（推荐）

1. 运行pip -V命令查看pip版本并确保pip已安装。

2. 运行 pip install esdk-obs-python --trusted-host pypi.org命令执行安装。

说明

● 如果您的环境尚未安装pip，请参见pip官网安装。

● 如果您使用的是Windows操作系统，当运行pip命令时提示“不是内部或外部命令”，请在 Path环境变量中增加pip的安装目录（一般为Python所在目录的Scripts文件夹）。

● 您可能需要重启电脑使环境变量生效。

使用源码安装

以安装OBS Python SDK最新版本为例。

方式一：直接安装

1. 下载OBS Python SDK开发包。

2. 运行命令 pip install pycryptodome==3.10.1，安装加密库

3. 解压该开发包，可以看到其中包含src文件夹（SDK源码），examples文件夹（示例代码），README.md（SDK版本特性描述文件）和log.conf（SDK日志配置文件）。

4. 使用PyCharm新建工程，将解压后的全部内容拷贝至新建工程，并右击src文件夹选择“Mark Directory as > Sources Root”。

说明

配置完成后，您的目录结构应该像下面这样：

├── examples

├── src

├── log.conf

└── README.md

方式二：使用setuptools工具安装

1. 下载OBS Python SDK开发包并解压。

(18)

2. 下载和安装setuptools工具。

3. 命令行切换到SDK开发包解压目录下的src文件夹。

4. 运行python setup.py install命令安装SDK。

5. 安装完成后检查Python安装目录下的Lib/site-package文件夹下是否生成 esdk_obs_python-<versionId>-*.egg文件夹。

说明

● 如果您使用setuptools的安装方式来安装SDK，重新安装SDK时，请务必删除已安装的 esdk_obs_python-<versionId>-*.egg文件夹。

● 如果按照上述步骤安装完成后仍无法加载SDK的模块，请直接将OBS Python SDK中src 文件夹的绝对路径，加入到Python的模块搜索的路径集（sys.path列表）中。

(19)

6 ^{快速使用 SDK}

创建 AK、SK

OBS通过用户帐户中的AK和SK进行签名验证，确保通过授权的帐户才能访问指定的 OBS资源。以下是对AK和SK的解释说明：

● AK：Access Key ID，接入键标识，用户在对象存储服务系统中的接入键标识，一个接入键标识唯一对应一个用户，一个用户可以同时拥有多个接入键标识。对象存储服务系统通过接入键标识识别访问系统的用户。

● SK：Secret Access Key，安全接入键，用户在对象存储服务系统中的安全接入键，是用户访问对象存储服务系统的密钥，用户根据安全接入键和请求头域生成鉴权信息。安全接入键和接入键标识一一对应。

创建访问密钥的操作步骤如下：

1. 登录OBS控制台。

2. 单击页面右上角的用户名，并选择“我的凭证”。

3. 在“我的凭证”页面，单击左侧导航栏的“访问密钥”。

4. 在“访问密钥”页面，单击“新增访问密钥”。

5. 在弹出的“新增访问密钥”对话框中，输入登录密码和对应验证码。

说明

● 用户如果未绑定邮箱和手机，则只需输入登录密码。

● 用户如果同时绑定了邮箱和手机，可以选择其中一种方式进行验证。

6. 单击“确定”。

7. 在弹出的“下载确认”提示框中，单击“确定”后，密钥会直接保存到浏览器默认的下载文件夹中。

8. 打开下载下来的“credentials.csv”文件既可获取到访问密钥（AK和SK）。

说明

● 每个用户最多可创建两个有效的访问密钥。

● 为防止访问密钥泄露，建议您将其保存到安全的位置。如果用户在此提示框中单击“取消”，则不会下载密钥，后续也将无法重新下载。如果需要使用访问密钥，可以重新创建新的访问密钥。

(20)

获取服务地址

● 您可以从这里查看OBS当前开通的服务地址和区域信息。

须知

SDK支持带协议名和不带协议名两种方式传入服务地址，例如获取到的服务地址为

“your-endpoint”，则初始化OBS客户端时传入的服务地址可以为“http://your- endpoint”、“https://your-endpoint”和“your-endpoint”三种形式。

初始化 OBS 客户端

向OBS发送任一HTTP/HTTPS请求之前，必须先创建一个ObsClient实例：

# 引入模块

from obs import ObsClient

# 创建ObsClient实例 obsClient = ObsClient(

access_key_id='*** Provide your Access Key ***', secret_access_key='*** Provide your Secret Key ***', server='https://your-endpoint'

)# 使用访问OBS

# 关闭obsClient obsClient.close()

说明

更多关于OBS客户端初始化的内容请参考“初始化”章节。

创建桶

桶是OBS全局命名空间，相当于数据的容器、文件系统的根目录，可以存储若干对象。以下代码展示如何新建一个桶：

# 调用createBucket创建桶

resp = obsClient.createBucket('bucketname') if resp.status < 300:

# 输出请求Id

print('requestId:', resp.requestId) else:

# 输出错误码

print('errorCode:', resp.errorCode) # 输出错误信息

print('errorMessage:', resp.errorMessage)

(21)

说明

● 桶的名字是全局唯一的，所以您需要确保不与已有的桶名称重复。

● 桶命名规则如下：

● 3～63个字符，数字或字母开头，支持小写字母、数字、“-”、“.”。

● 禁止使用类IP地址。

● 禁止以“-”或“.”开头及结尾。

● 禁止两个“.”相邻（如：“my..bucket”）。

● 禁止“.”和“-”相邻（如：“my-.bucket”和“my.-bucket”）。

● 同一用户多次创建同名桶不会报错，创建的桶属性以第一次请求为准。

● 更多创建桶的信息，请参见创建桶。

须知

● 创建桶时，如果使用的终端节点归属于默认区域华北-北京一（cn-north-1），则可以不指定区域；如果使用的终端节点归属于其他区域，则必须指定区域，且指定的区域必须与终端节点归属的区域一致。当前有效的区域名称可从这里查询。

● 您可以使用带参数创建方式，在创建桶时，指定桶的区域位置，详情请参考创建桶

上传对象

以下代码展示如何上传对象至OBS：

# 调用putContent接口上传对象到桶内

resp = obsClient.putContent('bucketname', 'objectname', 'Hello OBS') if resp.status < 300:

# 输出请求Id

# 输出错误码

print('errorCode:', resp.errorCode) # 输出错误信息

print('errorMessage:', resp.errorMessage) 说明

更多上传对象的信息，请参见上传对象。

(22)

7 ^初始化

7.1 OBS 客户端初始化

功能说明

OBS客户端（ObsClient）是访问OBS服务的Python客户端，它为调用者提供一系列与 OBS服务进行交互的接口，用于管理桶和对象等OBS服务上的资源。

方法定义

ObsClient(

)

构造函数参数描述

参数描述建议值

access_key_id 访问密钥中的AK。默认为空字符串表示匿名用户。

N/A

secret_access_key 访问密钥中的SK。默认为空字符串表示匿名用户。

N/A

security_token 临时访问密钥中的SecurityToken N/A server 连接OBS的服务地址。可包含协议类

型、域名、端口号。示例：https://

your-endpoint:443。（出于安全性考虑，建议使用https协议）

N/A

max_retry_count HTTP/HTTPS连接异常时的请求重试

次数。默认为3次。 [1，5]

max_redirect_count HTTP/HTTPS请求重定向的最大次

数。默认为10次 [1, 10]

(23)

参数描述建议值 timeout HTTP/HTTPS请求超时时间（单位：

秒）。默认为60秒。 [10， 60]

ssl_verify 验证服务端证书参数。可能的取值：

● 服务端pem格式根证书文件路径。

● True：从操作系统根证书库中获取服务端证书列表并验证服务端证书

（仅支持Windows操作系统）。

● False：表示不验证服务端证书。

默认为False。

N/A

chunk_size 读写socket流时的块大小（单位：字

节）。默认为65536字节。默认 long_conn_mode 是否启用长连接模式。默认为False。 N/A proxy_host 代理服务器的主机地址。默认为空。

说明

请注意，代理服务器的主机地址不要指定 http://或https://；

N/A

proxy_port 代理服务器的端口号。默认为空。 N/A proxy_username 连接代理服务器时使用的用户名。默

认为空。

N/A

proxy_password 连接代理服务器时使用的用户密码。

默认为空。

N/A

is_cname 是否通过自定义域名访问OBS服务。

默认为False。 N/A

security_providers 指定允许的访问密钥搜索方式。默认为None。

说明security_providers参数必须采用列表形式，默认情况下security_providers为 None，此时默认提供从环境变量中获取访问密钥及从ECS服务器获取临时访问密钥两种方式作为security_providers的默认搜索方式。当指定了security_providers参数时，则不会提供默认搜索方式，此时仅可以使用security_providers中提供的搜索方式。

N/A

(24)

参数描述建议值 security_provider_po

licy 指定访问密钥搜索策略。默认为

None。

说明

● security_provider_policy参数用于设置搜索策略，默认为None，此时需要显示指定访问密钥；同时，在已经指定了访问密钥参数的情况下，

security_provider_policy参数将被忽略。

● security_provider_policy设置为 OBS_DEFAULT时采用链式搜索方式获取访问密钥；

● 设置security_provider_policy为预定义方式名（ENV，ECS）时采用对应方式获取访问密钥。

N/A

说明

● 建议值为N/A的表示需要根据实际情况进行设置。

● 如网络状况不佳，建议增大timeout的值。

● 如果设置的server不带协议类型，则默认使用HTTPS协议。

须知

● 如果启用了长连接模式，使用完OBS客户端后必须调用ObsClient.close方法显式关闭，回收连接资源。

● 出于DNS解析性能和OBS服务可靠性的考虑，不允许将server设置为IP，必须使用域名访问OBS服务。

代码样例

● 通过构造函数创建OBS客户端，永久访问密钥（AK/SK）创建OBS客户端代码如下：# 引入模块

)

# 使用访问OBS

● 临时访问密钥（AK/SK和SecurityToken）创建OBS客户端代码如下：

# 引入模块

(25)

access_key_id='*** Provide your Access Key ***', secret_access_key='*** Provide your Secret Key ***', security_token='*** Provide your Security Token ***', server='https://your-endpoint'

)

# 使用访问OBS

● 通过配置系统环境变量的方式或者通过访问ECS服务器获取临时访问密钥的方式创建OBS客户端。

– 使用ENV方式创建OBS客户端的代码如下：

# 引入模块

from obs import ObsClient from obs import loadtoken

# 创建ObsClient实例

# 提供ENV方式获取访问密钥 obsClient = ObsClient(

server='https://your-endpoint', security_provider_policy='ENV' )

# 使用访问OBS

说明

以上方式会从当前系统的环境变量中寻找访问密钥，需要对应在环境变量中定义 OBS_ACCESS_KEY_ID、OBS_SECRET_ACCESS_KEY字段。同时如果采用临时访问密钥时，还需要在环境变量中定义OBS_SECURITY_TOKEN字段。

– 使用ECS方式创建OBS客户端的代码如下：

# 引入模块

# 提供ECS方式获取临时访问密钥 obsClient = ObsClient(

server='https://your-endpoint', security_provider_policy='ECS' )

# 使用访问OBS

说明

当应用程序部署在ECS服务器上时，可以采用以上方式从ECS服务器上自动获取临时访问密钥和定期自动刷新。

须知

在使用该方式获取临时访问密钥时，请确保服务端和应用程序部署所在环境的UTC时间一致，否则可能会导致临时访问密钥无法及时刷新的问题。

(26)

● 除了上述指定一种方式获取访问密钥外，还可以以链式的形式从环境变量及ECS服务器上进行搜索以获取对应的访问密钥。

– 通过设定security_provider_policy参数为OBS_DEFAULT来指定OBS客户端以链式的方式搜索访问密钥：

# 引入模块

# 以链式的方式从环境变量和ECS中搜索访问密钥 obsClient = ObsClient(

server='https://your-endpoint',

security_provider_policy='OBS_DEFAULT' )

# 使用访问OBS

说明

以上方式通过设定security_provider_policy为OBS_DEFAULT，可以指定以链式的方式从预定义方式列表中搜索访问密钥。当前默认提供从环境变量中以及从ECS服务器上获取访问密钥两种预定义搜索方式，并按照先从环境变量，再从ECS服务器的顺序进行搜索。链式搜索方式会以第一组成功获取到的访问密钥创建OBS客户端。

说明

● 工程中可以有多个ObsClient，也可以只有一个ObsClient。

● ObsClient是线程安全的，可在并发场景下使用。

7.2 桶客户端初始化

功能说明

桶客户端包含除ObsClient.listBuckets、ObsClient.createSignedUrl和

ObsClient.createPostSignature外所有OBS客户端的接口，且除省略桶名参数外，桶客户端和OBS客户端的接口保持一致，即两者包含同样的函数名和参数列表。

方法定义

obsClient.bucketClient(

bucketName='*** Your Bucket Name ***' )

构造函数参数描述

字段名类型约束说明

bucket_name str 必选创建桶客户端的桶名。

代码样例

# 引入模块

(27)

)# 创建桶客户端

bucketClient = obsClient.bucketClient('bucketname')

# 创建桶

resp = bucketClient.createBucket() if resp.status < 300:

print('errorCode:', resp.errorCode) print('errorMessage:', resp.errorMessage)

说明

桶客户端包含除ObsClient.listBuckets、ObsClient.createSignedUrl和

ObsClient.createPostSignature外所有OBS客户端的接口，且除省略桶名参数外，两者接口保持一致，即两者包含同样的函数名和参数列表。

7.3 日志初始化

功能说明

通过开启SDK日志功能，可将接口调用过程中产生的日志信息记录到日志文件，用于后续的数据分析或问题定位。具体步骤如下：

1. 找到OBS Python SDK开发包中的log.conf文件。

2. 根据实际情况修改log.conf中的配置参数。

3. 调用ObsClient.initLog开启日志功能。

说明

● 日志功能默认是关闭的，需要主动开启。

● 您可以从日志分析章节获取更多关于SDK日志的信息。

● 您可以根据实际需要在系统中修改日志文件的权限。

须知

OBS Python SDK的日志模块是线程安全非进程安全的，如果在多进程场景下使用 ObsClient请务必为每个ObsClient配置独立的日志路径，防止多个进程并发写日志时发生冲突。

方法定义

obsClient.initLog(

log_config='*** Your Log Configuration Parameters ***', log_name='*** Your Log Name ***'

)

(28)

构造函数参数描述

字段名类型约束说明

log_config LogConf 必选日志配置参数。

log_name str 可选日志名称。

代码样例

# 引入模块

)

# 引入日志模块

from obs import LogConf

# 指定日志配置文件路径，初始化ObsClient日志

obsClient.initLog(LogConf('./log.conf'), '*** Your Log Name ***')

# 使用ObsClient访问OBS服务

# 关闭ObsClient日志 obsClient.close()

7.4 SDK 公共结果对象

功能说明

调用ObsClient的相关接口完成后均会返回SDK公共结果对象

（ObsClient.createSignedUrl和ObsClient.createPostSignature接口除外），可从SDK 公共结果对象中获取HTTP状态码，判断操作是否成功。

参数描述

字段名类型说明

status int HTTP状态码，小于300表明操作成功；反之，表明操作失败。

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时为空。

(29)

字段名类型说明

resource str 发生错误时相关的桶或对象，当status小于300时为空。

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

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

(30)

8 ^{预定义常量}

8.1 权限类型

命名空间

obs.Permission

参数描述

常量值说明

READ 若有桶的读权限，则可以获取该桶内对象列表、桶内多段任务、桶的元数据、桶的多版本。

若有对象的读权限，则可以获取该对象内容和元数据。

WRITE 若有桶的写权限，则可以上传、覆盖和删除该桶内任何对象和段。

此权限在对象上不适用。

READ_ACP 若有读ACP的权限，则可以获取对应的桶或对象的权限控制列表（ACL）。

桶或对象的所有者永远拥有读对应桶或对象ACP的权限。

WRITE_ACP 若有写ACP的权限，则可以更新对应桶或对象的权限控制列表

（ACL）。

桶或对象的所有者永远拥有写对应桶或对象的ACP的权限。

拥有了写ACP的权限，由于可以更改权限控制策略，实际上意味着拥有了完全访问的权限。

FULL_CONTROL 若有桶的完全控制权限意味着拥有READ、WRITE、

READ_ACP和WRITE_ACP的权限。

若有对象的完全控制权限意味着拥有READ、READ_ACP和 WRITE_ACP的权限。

(31)

8.2 可被授权用户组

命名空间

obs.HeadPermission

参数描述

常量值说明

PRIVATE 私有读写。

PUBLIC_READ 公共读。

PUBLIC_READ_WRITE 公共读写。

PUBLIC_READ_DELIVERED 桶公共读，桶内对象公共读。

PUBLIC_READ_WRITE_DELIVERED 桶公共读写，桶内对象公共读写。

BUCKET_OWNER_FULL_CONTROL 桶或对象所有者拥有完全控制权限。

说明

PUBLIC_READ_DELIVERED和PUBLIC_READ_WRITE_DELIVERED不能应用于对象。

8.3 预定义访问策略

命名空间

obs.HeadPermission

参数描述

常量值说明

PRIVATE 私有读写。

PUBLIC_READ 公共读。

PUBLIC_READ_WRITE 公共读写。

PUBLIC_READ_DELIVERED 桶公共读，桶内对象公共读。

PUBLIC_READ_WRITE_DELIVERED 桶公共读写，桶内对象公共读写。

BUCKET_OWNER_FULL_CONTROL 桶或对象所有者拥有完全控制权限。

(32)

说明

PUBLIC_READ_DELIVERED和PUBLIC_READ_WRITE_DELIVERED不能应用于对象。

8.4 存储类型

命名空间

obs.StorageClass

参数描述

常量值类型说明

STANDARD 标准存储标准存储拥有低访问时延和较高的吞吐量，适用于有大量热点对象（平均一个月多次）或小对象（<1MB），且需要频繁访问数据的业务场景。

WARM 低频访问存储低频访问存储适用于不频繁访问（平均一

年少于12次）但在需要时也要求能够快速访问数据的业务场景。

COLD 归档存储归档存储适用于很少访问（平均一年访问

一次）数据的业务场景。

8.5 取回选项

命名空间

obs.RestoreTier

参数描述

常量值说明

EXPEDITED 快速取回，取回耗时1~5分钟。

STANDARD 标准取回，取回耗时3~5小时。

8.6 事件类型

命名空间

obs.EventType

(33)

参数描述

常量值说明

OBJECT_CREATED_ALL 所有创建对象操作的事件。

包含PUT上传对象、POST上传对象、复制对象、合并段。

OBJECT_CREATED_PUT PUT上传对象的事件。

OBJECT_CREATED_POST POST上传对象的事件。

OBJECT_CREATED_COPY 复制对象的事件。

OBJECT_CREATED_COMP LETE_MULTIPART_UPLOA D

合并段的事件。

OBJECT_REMOVED_ALL 所有调用删除、取消段接口的对象操作的事件。

包含指定对象版本号删除对象；多版本开启后，不指定对象版本号删除对象。

OBJECT_REMOVED_DELE

TE 指定对象版本号删除对象的事件。

OBJECT_REMOVED_DELE

TE_MARKER_CREATED 多版本开启后，不指定对象版本号删除对象的事件。

(34)

9 ^{桶相关接口}

9.1 创建桶

功能说明

按照用户指定的桶名创建一个新桶。新创建桶的桶名在OBS中必须是唯一的。同一用户在同一区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。如果是同一个用户重复创建同一区域的同名桶时返回HTTP状态码200。除此以外的其他场景重复创建同名桶返回HTTP状态码409，表明桶已存在。一个用户可以拥有的桶的数量不能超过100个。

方法定义

ObsClient.createBucket(bucketName, header, location)

请求参数

参数名类型约束说明

bucketName str 必选桶名。

桶命名规则如下：

● 3～63个字符，数字或字母开头，支持小写字母、数字、“-”、“.”。

● 禁止使用类IP地址。

● 禁止以“-”或“.”开头及结尾。

● 禁止两个“.”相邻（如：

“my..bucket”）。

● 禁止“.”和“-”相邻（如：

“my-.bucket”和“my.- bucket”）。

header CreateBuc ketHeade r

可选创建桶的附加头域。

(35)

参数名类型约束说明 location str 如果请求

的OBS服务地址所在区域为默认区域，则可为空，否则为必选。

桶所在的区域。该参数定义了桶将会被创建在哪个区域。

该参数与您所使用的终端节点一致。

● 使用华北-北京一的终端节点

（endpoint）创桶时

– 不携带Location，桶将默认创建在华北-北京一（cn-north-1）

– 在Location中指定其它区域，例如华北-北京四（cn-north-4），

桶将创建在指定区域

● 使用华北-北京一以外其它区域的终端节点（endpoint）创桶时，必须携带Location，并且Location只能指定为该终端节点对应的区域。

例如使用obs.cn-

north-4.myhuaweicloud.com终端节点创桶时，必须指定Location为 cn-north-4。

有关OBS区域和终端节点的更多信息，

请参考地区和终端节点。

返回结果

类型说明

GetResult SDK公共结果对象。

代码样例

使用默认区域华北-北京一（cn-north-1）的终端节点（endpoint）创桶时，不需要指定 Location，桶默认创建在华北-北京一。

try: from obs import CreateBucketHeader from obs import ObsClient

from obs import StorageClass ak = '*** Provide your Access Key ***' sk = '*** Provide your Secret Key ***'

server='https://obs.cn-north-1.myhuaweicloud.com'

obsClient = ObsClient(access_key_id=ak, secret_access_key=sk, server=server) resp = obsClient.createBucket(bucketName='bucketname',

header=CreateBucketHeader(aclControl='private', storageClass=StorageClass.WARM))

if resp.status < 300:

(36)

except:

import traceback

print(traceback.format_exc())

使用除华北-北京一（cn-north-1）以外的其他终端节点（endpoint）创桶时，必须指定Location，且Location必须与endpoint中的区域一致。桶会创建在location指定的区域。try:

from obs import CreateBucketHeader from obs import ObsClient

ak = '*** Provide your Access Key ***' sk = '*** Provide your Secret Key ***' # 使用非默认region的endpoint

server = 'https://obs.other-region.myhuaweicloud.com'

obsClient = ObsClient(access_key_id=ak, secret_access_key=sk, server=server) resp = obsClient.createBucket(bucketName='bucketname', location="other-region")

print('errorCode:', resp.errorCode) print('errorMessage:', resp.errorMessage) except:

import traceback

9.2 获取桶列表

功能说明

查询桶列表，返回结果按照桶名字典序排列。

方法定义

ObsClient.listBuckets(isQueryLocation)

请求参数

isQueryLocati

on bool 可选是否同时查询桶的区域位置。

返回结果

类型说明

GetResult.body类型 说明

ListBucketsResponse 获取桶列表响应结果。

(37)

代码样例

try: resp = obsClient.listBuckets(True) if resp.status < 300:

print('requestId:', resp.requestId) print('name:', resp.body.owner.owner_id)

print('create_date:', resp.body.owner.owner_name) index = 1

for bucket in resp.body.buckets:

print('bucket [' + str(index) + ']') print('name:', bucket.name)

print('create_date:', bucket.create_date) print('location:', bucket.location) index += 1

else:

import traceback

9.3 判断桶是否存在

功能说明

判断桶是否存在，返回的结果中HTTP状态码为200表明桶存在，否则返回404表明桶不存在。

方法定义

ObsClient.headBucket(bucketName)

请求参数

返回结果

类型说明

代码样例

try: resp = obsClient.headBucket('bucketname')

print('Bucket exists') elif resp.status == 404:

print('Bucket does not exist') except:

import traceback

(38)

9.4 删除桶

功能说明

删除桶，待删除的桶必须为空（不包含对象、历史版本对象或分段上传碎片）。删除桶非幂等操作，删除不存在的桶会失败。

方法定义

ObsClient.deleteBucket(bucketName)

请求参数

返回结果

类型说明

代码样例

try: resp = obsClient.deleteBucket('bucketname')

import traceback

9.5 列举桶内对象

功能说明

列举桶内对象，默认返回最大1000个对象。

方法定义

ObsClient.listObjects(bucketName, prefix, marker, max_keys, delimiter)

(39)

请求参数

prefix str 可选限定返回的对象名必须带有prefix前缀。

marker str 可选列举对象的起始位置，返回的对象

列表将是对象名按照字典序排序后该参数以后的所有对象。

max_keys int 可选列举对象的最大数目，取值范围为

1~1000，当超出范围时，按照默认的1000进行处理。

delimiter str 可选用于对对象名进行分组的字符。对于对象名中包含delimiter的对象，

其对象名（如果请求中指定了 prefix，则此处的对象名需要去掉 prefix）中从首字符至第一个 delimiter之间的字符串将作为一个分组并作为commonPrefix返回。

返回结果

类型说明

ListObjectsResponse 列举桶内对象响应结果。

代码样例

try: resp = obsClient.listObjects('bucketname', prefix='prefix', max_keys=100)

print('requestId:', resp.requestId) print('name:', resp.body.name) print('prefix:', resp.body.prefix) print('max_keys:', resp.body.max_keys) print('is_truncated:', resp.body.is_truncated) index = 1

for content in resp.body.contents:

print('object [' + str(index) + ']') print('key:', content.key)

print('lastModified:', content.lastModified) print('etag:', content.etag)

print('size:', content.size)

(40)

print('storageClass:', content.storageClass) print('owner_id:', content.owner.owner_id) print('owner_name:', content.owner.owner_name) index += 1

else:

import traceback

9.6 列举桶内多版本对象

功能说明

列举桶内多版本对象，默认返回最大1000个多版本对象。

方法定义

ObsClient.listVersions(bucketName, version)

请求参数

version Versions 可选列举多版本对象请求参数。

返回结果

类型说明

ObjectVersions 列举桶内多版本对象响应结果。

代码样例

try: from obs import Versions

resp = obsClient.listVersions('bucketname', version=Versions(prefix='prefix',max_keys=100))

print('requestId:', resp.requestId) print('name:', resp.body.head.name) print('prefix:', resp.body.head.prefix) print('maxKeys:', resp.body.head.maxKeys) print('isTruncated:', resp.body.head.isTruncated)

(41)

index = 1

for version in resp.body.versions:

print('version [' + str(index) + ']') print('key:', version.key)

print('versionId:', version.versionId) print('lastModified:', version.lastModified) print('etag:', version.etag)

print('size:', version.size)

print('storageClass:', version.storageClass) print('owner_id:', version.owner.owner_id) print('owner_name:', version.owner.owner_name) index += 1

index = 1

for marker in resp.body.markers:

print('marker [' + str(index) + ']') print('key:', marker.key)

print('versionId:', marker.versionId) print('lastModified:', marker.lastModified) print('owner_id:', marker.owner.owner_id) print('owner_name:', marker.owner.owner_name) index += 1

else:

import traceback

9.7 获取桶元数据

功能说明

对桶发送HEAD请求，获取桶的存储类型，CORS规则（若已设置）等信息。

方法定义

ObsClient.getBucketMetadata(bucketName, origin, requestHeaders)

请求参数

origin str 可选预请求指定的跨域请求Origin（通常为域名）。

requestHeaders str 可选跨域请求可以使用的HTTP头域。

返回结果

类型说明

(42)

GetBucketMetadataResponse 获取桶元数据响应结果。

代码样例

try: resp = obsClient.getBucketMetadata('bucketname', 'http://www.a.com', 'x-obs-header')

print('requestId:', resp.requestId)

print('storageClass:', resp.body.storageClass)

print('accessContorlAllowOrigin:', resp.body.accessContorlAllowOrigin) print('accessContorlMaxAge:', resp.body.accessContorlMaxAge)

print('accessContorlExposeHeaders:', resp.body.accessContorlExposeHeaders) print('accessContorlAllowMethods:', resp.body.accessContorlAllowMethods) print('accessContorlAllowHeaders:', resp.body.accessContorlAllowHeaders) else:

print('status:', resp.status) except:

import traceback

9.8 获取桶区域位置

功能说明

获取桶所在的区域位置。

方法定义

ObsClient.getBucketLocation(bucketName)

请求参数

返回结果

类型说明

LocationResponse 桶区域位置响应结果。

(43)

代码样例

try: resp = obsClient.getBucketLocation('bucketname')

print('requestId:', resp.requestId) print('location:', resp.body.location) else:

import traceback

9.9 获取桶存量信息

功能说明

获取桶的存量信息，包含桶的空间大小以及对象个数。

方法定义

ObsClient.getBucketStorageInfo(bucketName)

请求参数

返回结果

类型说明

GetBucketStorageInfoResponse 桶存量信息响应结果。

代码样例

try: resp = obsClient.getBucketStorageInfo('bucketname')

print('requestId:', resp.requestId) print('size:', resp.body.size)

print('objectNumber:', resp.body.objectNumber) else:

(44)

except:

import traceback

9.10 设置桶配额

功能说明

设置桶的配值，单位为字节，桶配额值必须为非负整数，支持的最大值为2⁶³-1，配额值设为0表示桶的配额没有上限。

方法定义

ObsClient.setBucketQuota(bucketName, quota)

请求参数

quota int 必选桶的配额值，非负整数。

返回结果

类型说明

代码样例

try: resp = obsClient.setBucketQuota('bucketname', 1024 * 1024 * 1024)

import traceback

9.11 获取桶配额

功能说明

获取桶的配额值，0代表配额没有上限。

方法定义

ObsClient.getBucketQuota(bucketName)

(45)

请求参数

返回结果

类型说明

GetBucketQuotaResponse 桶配额响应结果。

代码样例

try: resp = obsClient.getBucketQuota('bucketname')

print('requestId:', resp.requestId) print('quota:', resp.body.quota) else:

import traceback

9.12 设置桶存储类型

功能说明

设置桶的存储类型，桶中对象的存储类型默认将与桶的存储类型保持一致。

方法定义

ObsClient.setBucketStoragePolicy(bucketName, storageClass)

请求参数

storageClass str 必选桶的存储类型。

(46)

返回结果

类型说明

代码样例

try:

resp = obsClient.setBucketStoragePolicy('bucketname', StorageClass.STANDARD) if resp.status < 300:

import traceback

9.13 获取桶存储类型

功能说明

获取桶的存储类型。

方法定义

ObsClient.getBucketStoragePolicy(bucketName)

请求参数

返回结果

类型说明

GetBucketStoragePolicyRespons

e 桶存储类型响应结果。

示例程序_对象存储服务 OBS_SDK参考_Python_华为云

Python SDK 开发指南

目 录

1 简介...1

2 SDK 下载... 6

3 示例程序...7

4 开发环境搭建... 8

5 安装 SDK... 9

6 快速使用 SDK... 11

7 初始化... 14

8 预定义常量...22

9 桶相关接口...26

10 对象相关接口...61

11 多段相关接口...91

12 客户端加密相关接口...102

13 服务编排接口... 108

14 其他接口... 130

15 数据类型... 140

16 异常处理... 189

17 常见问题... 198

A 修订记录... 201

1 简介

SDK API 概览

2 SDK 下载

SDK 源码

兼容性

3 示例程序

4 开发环境搭建

5 安装 SDK

使用 pip 安装（推荐）

使用源码安装

6 快速使用 SDK

创建 AK、SK

获取服务地址

初始化 OBS 客户端

创建桶

上传对象

7 初始化

7.1 OBS 客户端初始化

功能说明

方法定义

构造函数参数描述

代码样例

7.2 桶客户端初始化

功能说明

方法定义

构造函数参数描述

代码样例

7.3 日志初始化

功能说明

方法定义

构造函数参数描述

代码样例

7.4 SDK 公共结果对象

功能说明

参数描述

8 预定义常量

8.1 权限类型

命名空间

参数描述

8.2 可被授权用户组

命名空间

参数描述

8.3 预定义访问策略

命名空间

参数描述

8.4 存储类型

命名空间

参数描述

8.5 取回选项

命名空间

参数描述

8.6 事件类型

命名空间

参数描述

9 桶相关接口

9.1 创建桶

功能说明

方法定义

请求参数

目录

1 ^简介

2 ^{SDK 下载}

3 ^示例程序

4 ^{开发环境搭建}

5 ^{安装 SDK}

6 ^{快速使用 SDK}

7 ^初始化

8 ^{预定义常量}

9 ^{桶相关接口}