全部產品
Search

搜尋本產品

    Object Storage Service：Python設定對象標籤

    文件中心

    Object Storage Service：Python設定對象標籤

    更新時間：Jun 19, 2024

    OSS支援使用對象標籤（Object Tagging）對儲存空間（Bucket）中的檔案（Object）進行分類，您可以針對相同標籤的Object設定生命週期規則、存取權限等。

    注意事項

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

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

    • 要設定對象標籤，您必須具有oss:PutObjectTagging許可權。具體操作，請參見為RAM使用者授權自訂的權限原則。

    上傳Object時添加對象標籤

    • 簡單上傳時添加對象標籤

      以下代碼用於簡單上傳Object時添加對象標籤。

      # -*- coding: utf-8 -*-

import oss2
from oss2.headers import OSS_OBJECT_TAGGING
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完整路徑，Object完整路徑中不能包含Bucket名稱。例如exampledir/exampleobject.txt。
object_name = 'exampledir/exampleobject.txt'

# 設定tagging字串。
tagging = "k1=v1&k2=v2&k3=v3"

# 如果標籤中包含了任一字元，則需要對標籤的Key和Value做URL編碼。
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# 在HTTP header中設定標籤資訊。
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# 調用put_object介面時指定headers，將會為上傳的檔案添加標籤。
result = bucket.put_object(object_name, 'content', headers=headers)
print('http response status: ', result.status)

# 查看Object的標籤資訊。
result = bucket.get_object_tagging(object_name)
for key in result.tag_set.tagging_rule:
    print('tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

    • 分區上傳時添加對象標籤

      以下代碼用於通過multipart_upload方式上傳Object時添加對象標籤。 

      # -*- coding: utf-8 -*-

import os
import oss2
from oss2 import SizedFileAdapter, determine_part_size
from oss2.models import PartInfo
from oss2.headers import OSS_OBJECT_TAGGING
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完整路徑，Object完整路徑中不能包含Bucket名稱。例如exampledir/exampleobject.txt。
object_name = 'exampledir/exampleobject.txt'
# 填寫本地檔案的完整路徑，例如D:\\localpath\\examplefile.txt。
# 如果未指定本地路徑只填寫了檔案名稱（例如examplefile.txt），則預設從樣本程式所屬專案對應本地路徑中上傳檔案。
filename = 'D:\\localpath\\examplefile.txt'

total_size = os.path.getsize(filename)
# determine_part_size方法用於確定分區大小。
part_size = determine_part_size(total_size, preferred_size=100 * 1024)

# 設定tagging字串。
tagging = "k1=v1&k2=v2&k3=v3"

# 如果標籤中包含了任一字元，則需要對標籤的Key和Value做URL編碼。
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# 在HTTP header中設定標籤資訊。
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# 初始化分區。
# 調用init_multipart_upload介面時指定headers，將會給上傳的檔案添加標籤。
upload_id = bucket.init_multipart_upload(object_name, headers=headers).upload_id
parts = []

# 逐個上傳分區。
with open(filename, 'rb') as fileobj:
    part_number = 1
    offset = 0
    while offset < total_size:
        num_to_upload = min(part_size, total_size - offset)
        # SizedFileAdapter(fileobj, size)方法會產生一個新的檔案對象，重新計算起始追加位置。
        result = bucket.upload_part(object_name, upload_id, part_number,
                                    SizedFileAdapter(fileobj, num_to_upload))
        parts.append(PartInfo(part_number, result.etag))

        offset += num_to_upload
        part_number += 1

# 完成分區上傳。
result = bucket.complete_multipart_upload(object_name, upload_id, parts)
print('http response status: ', result.status)

# 查看Object的標籤資訊。
result = bucket.get_object_tagging(object_name)
for key in result.tag_set.tagging_rule:
    print('tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

# 驗證分區上傳。
with open(filename, 'rb') as fileobj:
    assert bucket.get_object(object_name).read() == fileobj.read()

    • 追加上傳時添加對象標籤

      以下代碼用於通過append_object方式上傳Object時添加對象標籤。 

      # -*- coding: utf-8 -*-

import oss2
from oss2.headers import OSS_OBJECT_TAGGING
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完整路徑，Object完整路徑中不能包含Bucket名稱。例如exampledir/exampleobject.txt。
object_name = 'exampledir/exampleobject.txt'

# 設定tagging字串。
tagging = "k1=v1&k2=v2&k3=v3"

# 如果標籤中包含了任一字元，則需要對標籤的Key和Value做URL編碼。
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# 在HTTP header中設定標籤資訊。
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# 追加上傳檔案。調用append_object介面時指定headers，將會給檔案設定標籤。
# 只有第一次調用append_object設定的標籤才會生效，後續使用此種方式添加的標籤不生效。
result = bucket.append_object(object_name, 0, '<yourContent>', headers=headers)

# 查看Object的標籤資訊。
result = bucket.get_object_tagging(object_name)
for key in result.tag_set.tagging_rule:
    print('tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

    • 斷點續傳上傳時添加對象標籤

      以下代碼用於通過resumable_upload方式上傳Object時添加對象標籤。

      # -*- coding: utf-8 -*-

import oss2
from oss2.headers import OSS_OBJECT_TAGGING
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完整路徑，Object完整路徑中不能包含Bucket名稱。例如exampledir/exampleobject.txt。
object_name = 'exampledir/exampleobject.txt'
# 填寫本地檔案的完整路徑。如果未指定本地路徑，則預設從樣本程式所屬專案對應本地路徑中上傳檔案。
local_file = 'D:\\localpath\\examplefile.txt'

# 設定tagging字串。
tagging = "k1=v1&k2=v2&k3=v3"

# 如果標籤中包含了任一字元，則需要對標籤的Key和Value做URL編碼。
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# 在HTTP header中設定標籤資訊。
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# 當檔案長度大於或等於選擇性參數multipart_threshold（預設值為10 MB）時使用分區上傳。如果未使用參數store指定目錄，則會在HOME目錄下建立.py-oss-upload目錄來儲存斷點資訊。
# 調用resumable_upload介面時指定headers，將會給上傳的檔案添加標籤。
oss2.resumable_upload(bucket, object_name, local_file, headers=headers)

result = bucket.get_object_tagging(object_name)
for key in result.tag_set.tagging_rule:
    print('object tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

    為已上傳Object添加或更改對象標籤

    如果上傳Object時未添加對象標籤或者添加的對象標籤不滿足使用需求，您可以在上傳Object後為Object添加或更改對象標籤。

    以下代碼用於為已上傳Object添加或更改對象標籤。 

    # -*- coding: utf-8 -*-

import oss2
from oss2.models import Tagging, TaggingRule
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完整路徑，Object完整路徑中不能包含Bucket名稱。例如exampledir/exampleobject.txt。
object_name = 'exampledir/exampleobject.txt'

# 建立標籤規則。
rule = TaggingRule()
rule.add('key1', 'value1')
rule.add('key2', 'value2')

# 建立標籤。
tagging = Tagging(rule)

# 設定標籤。
result = bucket.put_object_tagging(object_name, tagging)
# 查看HTTP返回碼。
print('http response status:', result.status)

    為Object指定版本添加或更改對象標籤

    在已開啟版本控制的Bucket中，通過指定Object的版本ID（versionId），您可以為Object指定版本添加或更改對象標籤。

    以下代碼用於為Object指定版本添加或更改對象標籤。

    說明

    關於擷取versionId的具體操作，請參見列舉檔案。

    # -*- coding: utf-8 -*-

import oss2
from oss2.models import Tagging
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完整路徑，Object完整路徑中不能包含Bucket名稱。例如exampledir/exampleobject.txt。
object_name = 'exampledir/exampleobject.txt'
# 填寫Object的版本ID，例如CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****。
version_id = 'CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****'

tagging = Tagging()
# 依次填寫對象標籤的鍵（例如owner）和值（例如John）。
tagging.tag_set.add('owner', 'John')
tagging.tag_set.add('type', 'document')

params = dict()
params['versionId'] = version_id

bucket.put_object_tagging(object_name, tagging, params=params)

    拷貝Object時設定對象標籤

    拷貝Object時，可以指定如何設定目標Object的對象標籤。取值如下：

    • Copy（預設值）：複製源Object的對象標籤到目標Object。

    • Replace：忽略源Object的對象標籤，直接採用請求中指定的對象標籤。

    以下分別提供了簡單拷貝1 GB以下的Object及分區拷貝1 GB以上的Object時設定對象標籤的詳細樣本。

    • 簡單拷貝時設定對象標籤

      以下代碼用於簡單拷貝1 GB以下的Object時設定對象標籤。

      # -*- coding: utf-8 -*-

import oss2
from oss2.headers import OSS_OBJECT_TAGGING, OSS_OBJECT_TAGGING_COPY_DIRECTIVE
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完整路徑，Object完整路徑中不能包含Bucket名稱。例如srcexampledir/exampleobject.txt。
src_object_name = 'srcexampledir/exampleobject.txt'
# 填寫目標Object完整路徑，Object完整路徑中不能包含Bucket名稱。例如destexampledir1/exampleobject.txt。
dest_object_name1 = 'destexampledir1/exampleobject.txt'
# 填寫目標Object完整路徑，Object完整路徑中不能包含Bucket名稱。例如destexampledir2/exampleobject.txt。
dest_object_name2 = 'destexampledir2/exampleobject.txt'

# 設定tagging字串。
tagging = "k1=v1&k2=v2&k3=v3"

# 如果標籤中包含了任一字元，則需要對標籤的Key和Value做URL編碼。
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# 在HTTP header中指定OSS_OBJECT_TAGGING_COPY_DIRECTIVE參數為COPY或者預設不指定，則dest_object_name1將擁有與源檔案相同的標籤資訊。
headers=dict()
headers[OSS_OBJECT_TAGGING_COPY_DIRECTIVE] = 'COPY'
bucket.copy_object(bucket.bucket_name, src_object_name, dest_object_name1, headers=headers)

# 在HTTP header中指定OSS_OBJECT_TAGGING_COPY_DIRECTIVE參數為REPLACE，則dest_object_name2的標籤資訊將會設定為headers[OSS_OBJECT_TAGGING]指定的標籤資訊。
headers[OSS_OBJECT_TAGGING_COPY_DIRECTIVE] = 'REPLACE'
headers[OSS_OBJECT_TAGGING] = tagging
bucket.copy_object(bucket.bucket_name, src_object_name, dest_object_name2, headers=headers)

# 查看src_object_name的標籤資訊。
result = bucket.get_object_tagging(src_object_name)
for key in result.tag_set.tagging_rule:
    print('src tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

# 查看dest_object_name1的標籤資訊。dest_object_name1的標籤資訊與src_object_name的標籤資訊相同。
result = bucket.get_object_tagging(dest_object_name1)
for key in result.tag_set.tagging_rule:
    print('dest1 object tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

# 查看dest_object_name2的標籤資訊。dest_object_name2的標籤資訊為headers[OSS_OBJECT_TAGGING]指定的標籤資訊。
result = bucket.get_object_tagging(dest_object_name2)
for key in result.tag_set.tagging_rule:
    print('dest2 object tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

    • 分區拷貝時設定對象標籤

      以下代碼用於分區拷貝1 GB以上的Object時設定對象標籤。

      # -*- coding: utf-8 -*-

import os
import oss2
from oss2 import determine_part_size
from oss2.models import PartInfo
from oss2.headers import OSS_OBJECT_TAGGING
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完整路徑，Object完整路徑中不能包含Bucket名稱。例如srcexampledir/exampleobject.txt。
src_object_name = 'srcexampledir/exampleobject.txt'
# 填寫目標Object完整路徑，Object完整路徑中不能包含Bucket名稱。例如destexampledir/exampleobject.txt。
dest_object_name = 'destexampledir/exampleobject.txt'

# 擷取源檔案的檔案大小。
head_info = 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)

# 設定tagging字串。
tagging = "k1=v1&k2=v2&k3=v3"

# 如果標籤中包含了任一字元，則需要對標籤的Key和Value做URL編碼。
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# 在HTTP header中設定標籤資訊。
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# 初始化分區。
# 調用init_multipart_upload介面時指定headers，將會給目標檔案添加標籤。
upload_id = bucket.init_multipart_upload(dest_object_name, headers=headers).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;
    result = bucket.upload_part_copy(bucket.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)

# 擷取檔案中繼資料。
head_info = bucket.head_object(dest_object_name)

# 查看目標檔案大小。
dest_object_size = head_info.content_length
print('dest object size:', dest_object_size)

# 對比源檔案大小。
assert dest_object_size == total_size

# 查看源檔案的標籤資訊。
result = bucket.get_object_tagging(src_object_name)
for key in result.tag_set.tagging_rule:
    print('src tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

# 查看目標檔案的標籤資訊。
result = bucket.get_object_tagging(dest_object_name)
for key in result.tag_set.tagging_rule:
    print('dest tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

    為軟連結檔案設定標籤

    以下代碼用於為軟連結檔案設定標籤。

    # -*- coding: utf-8 -*-

import oss2
from oss2.headers import OSS_OBJECT_TAGGING
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完整路徑，Object完整路徑中不能包含Bucket名稱。例如exampledir/exampleobject.txt。
object_name = 'exampledir/exampleobject.txt'
# 填寫軟連結完整路徑，例如shortcut/myobject.txt。
symlink_name = 'shortcut/myobject.txt'

# 設定tagging字串。
tagging = "k1=v1&k2=v2&k3=v3"

# 如果標籤中包含了任一字元，則需要對標籤的Key和Value做URL編碼。
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# 在HTTP header中設定標籤資訊。
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# 添加軟連結。
# 調用put_symlink介面時指定headers，將會給軟連結檔案添加標籤。
result = bucket.put_symlink(object_name, symlink_name, headers=headers)
print('http response status: ', result.status)

# 查看軟連結檔案的標籤資訊。
result = bucket.get_object_tagging(symlink_name)
for key in result.tag_set.tagging_rule:
    print('tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

    相關文檔

    • 關於設定對象標籤的完整範例程式碼，請參見GitHub樣本。

    • 關於設定對象標籤的API介面說明，請參見PutObjectTagging。