简单上传是指通过put_object
方法上传单个文件(Object)。简单上传包括上传字符串、上传Bytes、上传Unicode字符、上传网络流和上传本地文件五种形式。
注意事项
本文以华东1(杭州)外网Endpoint为例。如果您希望通过与OSS同地域的其他阿里云产品访问OSS,请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系,请参见访问域名和数据中心。
本文以OSS域名新建OSSClient为例。如果您希望通过自定义域名、STS等方式新建OSSClient,请参见初始化。
要简单上传,您必须有
oss:PutObject
权限。具体操作,请参见为RAM用户授权自定义的权限策略。
注意事项
上传文件(Object)时,如果存储空间(Bucket)中已存在同名文件且用户对该文件有访问权限,则新添加的文件将覆盖原有文件。
上传文件时涉及填写的公共参数如下:
参数 | 说明 |
bucket_name | Bucket名称。 Bucket名称的命名规范如下:
|
object_name | Object完整路径。Object完整路径中不能包含Bucket名称。 Object命名规范如下:
|
上传字符串
以下代码用于将字符串上传到目标存储空间examplebucket中的exampleobject.txt文件。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 上传文件。
# 如果需要在上传文件时设置文件存储类型(x-oss-storage-class)和访问权限(x-oss-object-acl),请在put_object中设置相关Header。
# headers = dict()
# headers["x-oss-storage-class"] = "Standard"
# headers["x-oss-object-acl"] = oss2.OBJECT_ACL_PRIVATE
# 填写Object完整路径和字符串。Object完整路径中不能包含Bucket名称。
# result = bucket.put_object('exampleobject.txt', 'Hello OSS', headers=headers)
result = bucket.put_object('exampleobject.txt', 'Hello OSS')
# HTTP返回码。
print('http status: {0}'.format(result.status))
# 请求ID。请求ID是本次请求的唯一标识,强烈建议在程序日志中添加此参数。
print('request_id: {0}'.format(result.request_id))
# ETag是put_object方法返回值特有的属性,用于标识一个Object的内容。
print('ETag: {0}'.format(result.etag))
# HTTP响应头部。
print('date: {0}'.format(result.headers['date']))
上传Bytes
以下代码用于将Bytes上传到目标存储空间examplebucket中的exampleobject.txt文件。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 填写Object完整路径和Bytes内容。Object完整路径中不能包含Bucket名称。
bucket.put_object('exampleobject.txt', b'Hello OSS')
上传Unicode字符
以下代码用于将Unicode字符上传到目标存储空间examplebucket中的exampleobject.txt文件。上传Unicode字符时,OSS会将Unicode字符自动转换为UTF-8编码的Bytes进行上传。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 填写Object完整路径和Unicode字符。Object完整路径中不能包含Bucket名称。
bucket.put_object('exampleobject.txt', u'Hello OSS')
上传网络流
以下代码用于将网络流上传到目标存储空间examplebucket中的exampleobject.txt文件。OSS将网络流视为可迭代对象(Iterable),并以Chunked Encoding的方式上传。
# -*- coding: utf-8 -*-
import oss2
import requests
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# requests.get返回的是一个可迭代对象(Iterable),此时Python SDK会通过Chunked Encoding方式上传。
# 填写网络流地址。
input = requests.get('http://www.aliyun.com')
# 填写Object完整路径。Object完整路径中不能包含Bucket名称。
bucket.put_object('exampleobject.txt', input)
上传本地文件
以下代码用于将本地文件examplefile.txt上传到目标存储空间examplebucket中的exampleobject.txt文件。OSS将本地文件视为文件对象(File Object),上传时必须以二进制方式打开(例如rb模式)。
# -*- coding: utf-8 -*-
import oss2
import os
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 必须以二进制的方式打开文件。
# 填写本地文件的完整路径。如果未指定本地路径,则默认从示例程序所属项目对应本地路径中上传文件。
with open('D:\\localpath\\examplefile.txt', 'rb') as fileobj:
# Seek方法用于指定从第1000个字节位置开始读写。上传时会从您指定的第1000个字节位置开始上传,直到文件结束。
fileobj.seek(1000, os.SEEK_SET)
# Tell方法用于返回当前位置。
current = fileobj.tell()
# 填写Object完整路径。Object完整路径中不能包含Bucket名称。
bucket.put_object('exampleobject.txt', fileobj)
Python SDK还提供了更便捷的方法用于上传本地文件。
# 填写Object完整路径和本地文件的完整路径。Object完整路径中不能包含Bucket名称。
# 如果未指定本地路径,则默认从示例程序所属项目对应本地路径中上传文件。
bucket.put_object_from_file('exampleobject.txt', 'D:\\localpath\\examplefile.txt')
常见问题
文件上传后,如何获取文件URL?
通过SDK上传文件后,结果中不会返回文件URL。关于如何获取文件URL的具体步骤,请参见使用文件URL分享文件。
如何检查上传后文件大小与本地文件大小是否一致?
OSS在上传和下载文件时默认开启CRC数据校验,确保上传和下载过程的数据完整性。如果上传后文件大小与本地文件大小不一致,则报错InconsistentError。