Python SDK
<p> </p>
<p>1. 简介</p>
<ul>
<li>OBS Python SDK 适用于 Python3版本。</li>
<li>本文档主要介绍 OBS Python SDK 的接口使用及注意事项。</li>
<li>假设您是平安云用户,且已经开通了OBS服务。</li>
<li>如果您还没有开通或者还不了解平安云 OBS 服务,请登录<a href="https://pinganyun.com/ssr/products/OBS" target="_blank">OBS产品主页</a>进行了解。</li>
</ul>
<p>2. SDK下载</p>
<p>Python SDK 开发包最新版本<a href="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/sdk%2Fobs-python-sdk-1.1.0.zip?response-content-disposition=attachment%3Bfilename%3Dobs-python-sdk-1.1.0.zip" target="_blank"> v1.1.0</a>。</p>
<p>3. API概览</p>
<table>
<caption> </caption>
<thead>
<tr>
<th>
<p>API</p>
</th>
<th>
<p>描述</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>put_object</p>
</td>
<td>
<p>以字符串/文件/网络流作为上传对象,若该bucket下存在该object_key则更新该对象,并支持添加自定义元数据。</p>
</td>
</tr>
<tr>
<td>
<p>put_object_multipart</p>
</td>
<td>
<p>对于大文件上传,可以切分成片上传。在以下情况下,应该考虑使用分片上传:</p>
<ul>
<li>文件大于 100M</li>
<li>网络环境差,上传易导致失败</li>
</ul>
<p>需要支持断点续传</p>
</td>
</tr>
<tr>
<td>
<p>get_object</p>
</td>
<td>
<p>下载指定对象</p>
</td>
</tr>
</tbody>
</table>
<p>4. API描述</p>
<p><strong>(1) put_object(上传字符串)</strong></p>
<p><strong>接口描述</strong></p>
<p>以字符串为上传对象,若该bucket下存在该object_key则更新该对象,并支持添加自定义元数据。</p>
<p><strong>请求参数</strong></p>
<table>
<caption> </caption>
<thead>
<tr>
<th>
<p>参数名称</p>
</th>
<th>
<p>参数类型</p>
</th>
<th>
<p>是否必须</p>
</th>
<th>
<p>参数描述</p>
</th>
<th>
<p>备注</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>bucket_name</p>
</td>
<td>
<p>string</p>
</td>
<td>
<p>true</p>
</td>
<td>
<p>保存对象的 bucket名称</p>
</td>
<td>
<p>-</p>
</td>
</tr>
<tr>
<td>
<p>object_key</p>
</td>
<td>
<p>string</p>
</td>
<td>
<p>true</p>
</td>
<td>
<p>对象 key,需自行实现策略保证同一 bucket 下 object_key 唯一, 不能为空,首字符不能为路径符“/”</p>
</td>
<td>
<p>-</p>
</td>
</tr>
<tr>
<td>
<p>data</p>
</td>
<td>
<p>string</p>
</td>
<td>
<p>true</p>
</td>
<td>
<p>待上传的字符串</p>
</td>
<td>
<p>-</p>
</td>
</tr>
<tr>
<td>
<p>object_metadata</p>
</td>
<td>
<p>ObjectMetadata</p>
</td>
<td>
<p>false</p>
</td>
<td>
<p>可选参数,自定义元数据</p>
</td>
<td>
<p>-</p>
</td>
</tr>
</tbody>
</table>
<p><strong>响应参数</strong></p>
<table>
<caption> </caption>
<thead>
<tr>
<th>
<p>参数名称</p>
</th>
<th>
<p>参数类型</p>
</th>
<th>
<p>参数描述</p>
</th>
<th>
<p>备注</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>putObjectResult</p>
</td>
<td>
<p>PutObjectResult</p>
</td>
<td>
<p>PutObjectResult返回对象</p>
</td>
<td>
<p>-</p>
</td>
</tr>
</tbody>
</table>
<p><strong>实例</strong></p>
<pre>
bucket_name = “YourBucketName”
object_key = “YourObjectKey”
upload_content = “YourContent”
object_metadata = ObjectMetadata()
object_metadata.add_user_metadata(“MetadataKey”,“MetadataValue”)
ret = obs.put_object(bucket_name, object_key, upload_content,object_metadata)
print(ret.get_e_tag())</pre>
<p><strong>(2) put_object(上传文件)</strong></p>
<p><strong>接口描述</strong></p>
<p>以文件对象为上传对象,若对象存在则更新,并支持添加自定义元数据。</p>
<p><strong>请求参数</strong></p>
<table>
<caption> </caption>
<thead>
<tr>
<th>
<p>参数名称</p>
</th>
<th>
<p>参数类型</p>
</th>
<th>
<p>是否必须</p>
</th>
<th>
<p>参数描述</p>
</th>
<th>
<p>备注</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>bucket_name</p>
</td>
<td>
<p>string</p>
</td>
<td>
<p>true</p>
</td>
<td>
<p>保存对象的 bucket名称</p>
</td>
<td>
<p>-</p>
</td>
</tr>
<tr>
<td>
<p>object_key</p>
</td>
<td>
<p>string</p>
</td>
<td>
<p>true</p>
</td>
<td>
<p>对象 key,需自行实现策略保证同一 bucket 下 object_key 唯一, 不能为空,首字符不能为路径符“/”</p>
</td>
<td>
<p>-</p>
</td>
</tr>
<tr>
<td>
<p>data</p>
</td>
<td>
<p>file</p>
</td>
<td>
<p>true</p>
</td>
<td>
<p>待上传的文件对象</p>
</td>
<td>
<p>-</p>
</td>
</tr>
<tr>
<td>
<p>object_metadata</p>
</td>
<td>
<p>ObjectMetadata</p>
</td>
<td>
<p>false</p>
</td>
<td>
<p>可选参数,自定义元数据</p>
</td>
<td>
<p>-</p>
</td>
</tr>
</tbody>
</table>
<p><strong>响应参数</strong></p>
<table>
<caption> </caption>
<thead>
<tr>
<th>
<p>参数名称</p>
</th>
<th>
<p>参数类型</p>
</th>
<th>
<p>参数描述</p>
</th>
<th>
<p>备注</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>putObjectResult</p>
</td>
<td>
<p>PutObjectResult</p>
</td>
<td>
<p>PutObjectResult返回对象</p>
</td>
<td>
<p>-</p>
</td>
</tr>
</tbody>
</table>
<p><strong>实例</strong></p>
<p><strong>样例1:</strong></p>
<pre>
bucket_name = “YourBucketName”
object_key = “YourObjectKey”
local_file_upload_path = “YourLocalUploadFilePath”
with open(local_file_upload_path,<span style="color:#2a00ff">"rb"</span>) as from_file:
ret = obs.put_object(bucket_name, object_key, from_file)
</pre>
<p><strong>样例2: 使用简单接口上传本地文件</strong></p>
<pre>
bucket_name = “YourBucketName”
object_key = “YourObjectKey”
local_file_upload_path = “YourLocalUploadFilePath”
ret = obs.put_object_from_file(bucket_name, object_key, local_file_upload_path)
</pre>
<p><strong>(3) put_object(上传网络流)</strong></p>
<p><strong>接口描述</strong></p>
<p>以网络流为上传对象,若对象存在则更新,并支持添加自定义元数据。</p>
<p><strong>请求参数</strong></p>
<table>
<caption> </caption>
<thead>
<tr>
<th>
<p>参数名称</p>
</th>
<th>
<p>参数类型</p>
</th>
<th>
<p>是否必须</p>
</th>
<th>
<p>参数描述</p>
</th>
<th>
<p>备注</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>bucket_name</p>
</td>
<td>
<p>string</p>
</td>
<td>
<p>true</p>
</td>
<td>
<p>保存对象的 bucket名称</p>
</td>
<td>
<p>-</p>
</td>
</tr>
<tr>
<td>
<p>object_key</p>
</td>
<td>
<p>string</p>
</td>
<td>
<p>true</p>
</td>
<td>
<p>对象 key,需自行实现策略保证同一 bucket 下 object_key 唯一, 不能为空,首字符不能为路径符“/”</p>
</td>
<td>
<p>-</p>
</td>
</tr>
<tr>
<td>
<p>data</p>
</td>
<td>
<p>Input_stream</p>
</td>
<td>
<p>true</p>
</td>
<td>
<p>待上传的文件对象</p>
</td>
<td>
<p>-</p>
</td>
</tr>
<tr>
<td>
<p>object_metadata</p>
</td>
<td>
<p>ObjectMetadata</p>
</td>
<td>
<p>false</p>
</td>
<td>
<p>可选参数,自定义元数据</p>
</td>
<td>
<p>-</p>
</td>
</tr>
</tbody>
</table>
<p><strong>响应参数</strong></p>
<table>
<caption> </caption>
<thead>
<tr>
<th>
<p>参数名称</p>
</th>
<th>
<p>参数类型</p>
</th>
<th>
<p>参数描述</p>
</th>
<th>
<p>备注</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>putObjectResult</p>
</td>
<td>
<p>PutObjectResult</p>
</td>
<td>
<p>PutObjectResult返回对象</p>
</td>
<td>
<p>-</p>
</td>
</tr>
</tbody>
</table>
<p><strong>实例</strong></p>
<pre>
<strong>import</strong> requests
bucket_name = “YourBucketName”
object_key = “YourObjectKey”
input_stream = requests.get(<span style="color:#2a00ff">"http://alm.paic.com.cn/project/2008/board/"</span>, stream=True)
ret = obs.put_object(bucket_name, object_key, input_stream)
</pre>
<p><strong>(4) put_object_multipart(分片上传)</strong></p>
<p><strong>接口描述</strong></p>
<p>对于大文件上传,可以切分成片上传。在以下情况下,应该考虑使用分片上传:</p>
<ul>
<li>文件大于 100M</li>
<li>网络环境差,上传易导致失败</li>
</ul>
<p>需要支持断点续传</p>
<p><strong>请求参数</strong></p>
<table>
<caption> </caption>
<thead>
<tr>
<th>
<p>参数名称</p>
</th>
<th>
<p>参数类型</p>
</th>
<th>
<p>是否必须</p>
</th>
<th>
<p>参数描述</p>
</th>
<th>
<p>备注</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>upload_file_request</p>
</td>
<td>
<p>MutilpartUploadFileRequest</p>
</td>
<td>
<p>true</p>
</td>
<td>
<p>分片上传参数 upload_file_request的说明:</p>
<p>每个分片(除了最后一个分片)的大小必须不小于 5M,最后一个分片的大小无限制;</p>
<p>若任何一个分片(非最后一个分片)小于 5M,每个分片的上传不会失败,然而分片完成操作(complete)会失败。</p>
<p>enable_checkpoint 用于设置是否启用断点续传。默认启用。通过调用 upload_file_request.set_enable_checkpoint(False) 关闭断点续传功能。</p>
<p>checkpoint_file_path 用于设置断点续传 ucp 文件的保存位置。默认与待上传文件位于同一个目录下面。若非特殊需求,不需要更改此设置。</p>
<p>upload_notifier 用于设置分片上传的通知接收者。可以实现一个 mutilpart_upload_notifier,并调用 upload_file_request.set_upload_notifier 来接收分片上传的进展的通知,以达到如进度感知等目的。</p>
</td>
<td>
<p>-</p>
</td>
</tr>
</tbody>
</table>
<p><strong>响应参数</strong></p>
<p>无</p>
<p><strong>实例</strong></p>
<pre>
def notify_upload(upload_id, state, total_parts, finish_parts):
bucket_name = “YourBucketName”
object_key = “YourObjectKey”
multipart_upload_file_path = “UploadFilePath”
multipart_request = MultipartUploadFileRequest()
multipart_request.set_bucket_name(bucket_name)
multipart_request.set_object_key(object_key)
multipart_request.set_upload_file_path(multipart_upload_file_path)
multipart_request.set_upload_notifier(notify_upload)
obs.put_object_multipart(multipart_request)</pre>
<p><strong>(5) get_object(下载文件)</strong></p>
<p><strong>接口描述</strong></p>
<p>下载指定对象。</p>
<p><strong>请求参数</strong></p>
<table>
<caption> </caption>
<thead>
<tr>
<th>
<p>参数名称</p>
</th>
<th>
<p>参数类型</p>
</th>
<th>
<p>是否必须</p>
</th>
<th>
<p>参数描述</p>
</th>
<th>
<p>备注</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>bucket_name</p>
</td>
<td>
<p>string</p>
</td>
<td>
<p>true</p>
</td>
<td>
<p>保存对象的 bucket名称</p>
</td>
<td>
<p>-</p>
</td>
</tr>
<tr>
<td>
<p>object_key</p>
</td>
<td>
<p>string</p>
</td>
<td>
<p>true</p>
</td>
<td>
<p>对象 key</p>
</td>
<td>
<p>-</p>
</td>
</tr>
</tbody>
</table>
<p><strong>响应参数</strong></p>
<table>
<caption> </caption>
<thead>
<tr>
<th>
<p>参数名称</p>
</th>
<th>
<p>参数类型</p>
</th>
<th>
<p>参数描述</p>
</th>
<th>
<p>备注</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>s3Object</p>
</td>
<td>
<p>S3Object</p>
</td>
<td>
<p>S3Object 返回对象,可以获取对象流自己保存,也可以传入文件对象直接存储</p>
</td>
<td>
<p>-</p>
</td>
</tr>
</tbody>
</table>
<p><strong>实例</strong></p>
<pre>
bucket_name = “YourBucketName”
object_key = “YourObjectKey”
to_file_path = “DownloadFilePath”
s3_object = obs.get_object(bucket_name, object_key)
#读取对象流自己存储
with open(to_file_path, <span style="color:#2a00ff">"wb"</span>) as to_file:
shutil.copyfileobj(s3_object.get_object_stream(), to_file)
#传入文件对象直接存储
with open(to_file_path, <span style="color:#2a00ff">"wb"</span>) as to_file:
s3_object.to_file(to_file)
#获取自定义元数据
print(s3_object.get_object_metadata().get_user_metadata())
</pre>
提交成功!非常感谢您的反馈,我们会继续努力做到更好!