全部產品
Search

搜尋本產品

    Object Storage Service：Python簡單上傳

    文件中心

    Object Storage Service：Python簡單上傳

    更新時間：Apr 12, 2025

    簡單上傳是指通過put_object方法上傳單個檔案（Object）。簡單上傳包括上傳字串、上傳Bytes、上傳Unicode字元、上傳網路流和上傳本地檔案五種形式。

    注意事項

    • 本文以華東1（杭州）外網Endpoint為例。如果您希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint。關於OSS支援的Region與Endpoint的對應關係，請參見OSS地區和訪問網域名稱。

    • 本文以OSS網域名稱建立OSSClient為例。如果您希望通過自訂網域名、STS等方式建立OSSClient，請參見初始化。

    • 如果儲存空間（Bucket）中已存在同名檔案且使用者對該檔案具有存取權限，則新上傳的檔案將覆蓋原檔案。

    許可權說明

    阿里雲帳號預設擁有全部許可權。阿里雲帳號下的RAM使用者或RAM角色預設沒有任何許可權，需要阿里雲帳號或帳號管理員通過RAM Policy或Bucket Policy授予操作許可權。

    公用參數說明

    上傳檔案時涉及填寫的公用參數如下：

    參數

    說明

    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.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
region = "cn-hangzhou"

# yourBucketName填寫儲存空間名稱。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# 上傳檔案。
# 如果需要在上傳檔案時設定檔案儲存體類型（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.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
region = "cn-hangzhou"

# yourBucketName填寫儲存空間名稱。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# 填寫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.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
region = "cn-hangzhou"

# yourBucketName填寫儲存空間名稱。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# 填寫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.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
region = "cn-hangzhou"

# yourBucketName填寫儲存空間名稱。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# 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。

    # -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
region = "cn-hangzhou"
# 填寫Bucket名稱，例如examplebucket。
bucketName = "examplebucket"
# 建立Bucket執行個體，指定儲存空間的名稱和Region資訊。
bucket = oss2.Bucket(auth, endpoint, bucketName, region=region)

# 本地檔案的完整路徑
local_file_path = 'D:\\localpath\\examplefile.txt'  

# 填寫Object完整路徑，完整路徑中不能包含Bucket名稱。例如exampleobject.txt。
objectName = 'exampleobject.txt'

# 使用put_object_from_file方法將本地檔案上傳至OSS
bucket.put_object_from_file(objectName, local_file_path)

    如果您希望從本地檔案的指定位元組位置上傳，可以使用seek()方法跳到目標位元組位置，以下是從1000位元組位置開始上傳的範例程式碼。

    # -*- coding: utf-8 -*-
import oss2
import os
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
region = "cn-hangzhou"

# yourBucketName填寫儲存空間名稱，例如examplebucket
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# 必須以二進位的方式開啟檔案。
# 填寫本地檔案的完整路徑。如果未指定本地路徑，則預設從樣本程式所屬專案對應本地路徑中上傳檔案。
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)

    常見問題

    檔案上傳後，如何擷取檔案URL？

    通過SDK上傳檔案後，結果中不會返迴文件URL。關於如何擷取檔案URL的具體步驟，請參見使用預簽名URL下載檔案。

    如何檢查上傳後檔案大小與本地檔案大小是否一致？

    1. OSS在上傳和下載檔案時預設開啟CRC資料校正，確保上傳和下載過程的資料完整性。如果上傳後檔案大小與本地檔案大小不一致，則報錯InconsistentError。

    2. 但是CRC資料校正的過程是傳輸與計算同時進行的，會影響檔案的上傳速度。當您的業務情境更傾向於快速傳輸時，可參考以下代碼關閉CRC校正。

      # -*- coding: utf-8 -*-
import oss2
import os
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
region = "cn-hangzhou"

# yourBucketName填寫儲存空間名稱，並設定enable_crc=False來關閉CRC資料校正 
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", enable_crc=False, region=region)

    相關文檔

    • 關於簡單上傳的完整範例程式碼，請參見GitHub樣本。

    • 關於簡單上傳的API介面說明，請參見PutObject。