全部产品
Search
文档中心

对象存储 OSS:Python简单上传

更新时间:Dec 20, 2023

简单上传是指通过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名称的命名规范如下:

  • 只能包括小写字母、数字和短划线(-)。

  • 必须以小写字母或者数字开头和结尾。

  • 长度必须在3~63字符之间。

object_name

Object完整路径。Object完整路径中不能包含Bucket名称。

Object命名规范如下:

  • 使用UTF-8编码。

  • 长度必须在1~1023字符之间。

  • 不能以正斜线(/)或者反斜线(\)开头。

上传字符串

以下代码用于将字符串上传到目标存储空间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

相关文档

  • 关于简单上传的完整示例代码,请参见GitHub示例

  • 关于简单上传的API接口说明,请参见PutObject