本文介紹如何將源Bucket中的文件(Object)復制到同一地域下相同或不同目標Bucket中。
注意事項
本文以華東1(杭州)外網Endpoint為例。如果您希望通過與OSS同地域的其他阿里云產品訪問OSS,請使用內網Endpoint。關于OSS支持的Region與Endpoint的對應關系,請參見OSS地域和訪問域名。
本文以從環境變量讀取訪問憑證為例。如何配置訪問憑證,請參見配置訪問憑證。
本文以OSS域名新建OSSClient為例。如果您希望通過自定義域名、STS等方式新建OSSClient,請參見初始化。
拷貝文件時,您必須擁有源文件的讀權限及目標Bucket的讀寫權限。
拷貝文件時,您需要確保源Bucket和目標Bucket均未設置合規保留策略,否則報錯The object you specified is immutable.。
不支持跨地域拷貝。例如不能將華東1(杭州)地域存儲空間中的文件拷貝到華北1(青島)地域。
拷貝小文件
對于小于1 GB的文件,您可以使用簡單拷貝。以下代碼用于通過簡單拷貝將源存儲空間srcexamplebucket中的srcexampleobject.txt文件拷貝到目標存儲空間destexamplebucket中的destexampleobject.txt文件。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# 填寫源Bucket名稱,例如srcexamplebucket。
src_bucket_name = 'srcexamplebucket'
# 填寫與源Bucket處于同一地域的目標Bucket名稱,例如destexamplebucket。
# 當在同一個Bucket內拷貝文件時,請確保源Bucket名稱和目標Bucket名稱相同。
dest_bucket_name = 'destexamplebucket'
# 填寫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 = oss2.Bucket(auth, endpoint, dest_bucket_name, region=region)
# 填寫不包含Bucket名稱在內源Object的完整路徑,例如srcexampleobject.txt。
src_object_name = 'srcexampleobject.txt'
# 填寫不包含Bucket名稱在內目標Object的完整路徑,例如destexampleobject.txt。
dest_object_name = 'destexampleobject.txt'
# headers = dict()
# 指定CopyObject操作時是否覆蓋同名目標Object。此處設置為true,表示禁止覆蓋同名Object。
# headers['x-oss-forbid-overwrite'] = 'true'
# 指定拷貝的源地址。
# headers[OSS_COPY_OBJECT_SOURCE] = '/example-bucket-by-util/recode-test.txt'
# 如果源Object的ETag值和您提供的ETag相等,則執行拷貝操作,并返回200 OK。
# headers['x-oss-copy-source-if-match'] = '5B3C1A2E053D763E1B002CC607C5****'
# 如果源Object的ETag值和您提供的ETag不相等,則執行拷貝操作,并返回200 OK。
# headers['x-oss-copy-source-if-none-match'] = '5B3C1A2E053D763E1B002CC607C5****'
# 如果指定的時間等于或者晚于文件實際修改時間,則正常拷貝文件,并返回200 OK。
# headers['x-oss-copy-source-if-unmodified-since'] = '2021-12-09T07:01:56.000Z'
# 如果源Object在指定時間后被修改過,則執行拷貝操作。
# headers['x-oss-copy-source-if-modified-since'] = '2021-12-09T07:01:56.000Z'
# 指定設置目標Object元數據的方式。此處設置為COPY,表示復制源Object的元數據到目標Object。
# headers[OSS_METADATA_DIRECTIVE] = 'COPY'
# 指定OSS創建目標Object時使用的服務器端加密算法。
# headers[OSS_SERVER_SIDE_ENCRYPTION] = 'KMS'
# 表示KMS托管的用戶主密鑰,該參數僅在x-oss-server-side-encryption為KMS時有效。
# headers['x-oss-server-side-encryption-key-id'] = '9468da86-3509-4f8d-a61e-6eab1eac****'
# 指定OSS創建目標Object時的訪問權限。此處設置為OBJECT_ACL_PRIVATE,表示只有Object的擁有者和授權用戶有該Object的讀寫權限,其他用戶沒有權限操作該Object。
# headers[OSS_OBJECT_ACL] = oss2.OBJECT_ACL_PRIVATE
# 指定Object的存儲類型。此處設置為BUCKET_STORAGE_CLASS_STANDARD,表示標準存儲類型。
# headers['x-oss-storage-class'] = oss2.BUCKET_STORAGE_CLASS_STANDARD
# 指定Object的對象標簽,可同時設置多個標簽。
# headers[OSS_OBJECT_TAGGING] = 'k1=v1&k2=v2&k3=v3'
# 指定設置目標Object對象標簽的方式。此處設置為COPY,表示復制源Object的對象標簽到目標Object。
# headers[OSS_OBJECT_TAGGING_COPY_DIRECTIVE] = 'COPY'
# result = bucket.copy_object(src_bucket_name, src_object_name, dest_object_name, headers=headers)
# 將源Bucket中的某個Object拷貝到目標Bucket。
result = bucket.copy_object(src_bucket_name, src_object_name, dest_object_name)
# 查看返回結果的狀態。如果返回值為200,表示執行成功。
print('result.status:', result.status)
拷貝大文件
對于大于1 GB的文件,需要使用分片拷貝(UploadPartCopy)。分片拷貝分為三步:
通過bucket.init_multipart_upload初始化分片拷貝任務。
通過bucket.upload_part_copy進行分片拷貝。除最后一個分片外,其它分片都要大于100 KB。
通過bucket.complete_multipart_upload提交分片拷貝任務。
以下代碼用于通過分片拷貝將源存儲空間srcexamplebucket中的srcexampleobject.txt文件拷貝到目標存儲空間destexamplebucket中的destexampleobject.txt文件。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from oss2.models import PartInfo
from oss2 import determine_part_size
# 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# 填寫源Bucket名稱,例如srcexamplebucket。
src_bucket_name = 'srcexamplebucket'
# 填寫與源Bucket處于同一地域的目標Bucket名稱,例如destexamplebucket。
# 當在同一Bucket內拷貝文件時,請確保源Bucket名稱和目標Bucket名稱相同。
dest_bucket_name = 'destexamplebucket'
# 填寫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內拷貝文件時,請注釋掉該行代碼,并將后面的src_bucket改為bucket即可。
bucket = oss2.Bucket(auth, endpoint, dest_bucket_name, region=region)
src_bucket = oss2.Bucket(auth, endpoint, src_bucket_name, region=region)
# 填寫不包含Bucket名稱在內源Object的完整路徑,例如srcexampleobject.txt。
src_object_name = 'srcexampleobject.txt'
# 填寫不包含Bucket名稱在內目標Object的完整路徑,例如destexampleobject.txt。
dest_object_name = 'destexampleobject.txt'
# 獲取源文件的大小。當在同一個Bucket內拷貝文件時,請將src_bucket改為bucket。
head_info = src_bucket.head_object(src_object_name)
total_size = head_info.content_length
print('src object size:', total_size)
# determine_part_size方法用來確定分片大小。
part_size = determine_part_size(total_size, preferred_size=100 * 1024)
print('part_size:', part_size)
# 初始化分片。
upload_id = bucket.init_multipart_upload(dest_object_name).upload_id
parts = []
# 逐個上傳分片。
part_number = 1
offset = 0
while offset < total_size:
num_to_upload = min(part_size, total_size - offset)
end = offset + num_to_upload - 1
# headers = dict()
# 指定拷貝的源地址。
# headers[OSS_COPY_OBJECT_SOURCE] = '/example-bucket-by-util/recode-test.txt'
# 指定源Object的拷貝范圍。例如設置bytes=0~1023,表示拷貝1~1024字節的內容。
# headers[OSS_COPY_OBJECT_SOURCE_RANGE] = 'bytes=0~1023'
# 如果源Object的ETag值和您提供的ETag相等,則執行拷貝操作,并返回200 OK。
# headers['x-oss-copy-source-if-match'] = '5B3C1A2E053D763E1B002CC6****'
# 如果源Object的ETag值和您提供的ETag不相等,則執行拷貝操作,并返回200 OK。
# headers['x-oss-copy-source-if-none-match'] = '5B3C1A2E053D763E1B002CC6****'
# 如果指定的時間等于或者晚于文件實際修改時間,則正常拷貝文件,并返回200 OK。
# headers['x-oss-copy-source-if-unmodified-since'] = '2021-12-09T07:01:56.000Z'
# 如果指定的時間早于文件實際修改時間,則正常拷貝文件,并返回200 OK。
# headers['x-oss-copy-source-if-modified-since'] = '2021-12-09T07:01:56.000Z'
# result = bucket.upload_part_copy(src_bucket_name, src_object_name, (offset, end), dest_object_name, upload_id, part_number, headers=headers)
result = bucket.upload_part_copy(src_bucket_name, src_object_name, (offset, end), dest_object_name, upload_id, part_number)
# 保存part信息。
parts.append(PartInfo(part_number, result.etag))
offset += num_to_upload
part_number += 1
# 完成分片拷貝。
result = bucket.complete_multipart_upload(dest_object_name, upload_id, parts)
# 查看拷貝返回狀態。
print('result :', result.status)
# 獲取文件元數據。
head_info = bucket.head_object(dest_object_name)
# 查看目標Object大小。
dest_object_size = head_info.content_length
print('dest object size:', dest_object_size)
# 對比源Object和目標Object的大小。
assert dest_object_size == total_size
相關文檔
拷貝小文件
關于拷貝小文件的完整示例代碼,請參見GitHub示例。
關于拷貝小文件的API接口說明,請參見CopyObject。
拷貝大文件
關于拷貝大文件的API接口說明,請參見UploadPartCopy。