Configurar tags de objetos (OSS SDK for Python 1.0) - Object Storage Service: Central de Documentação do Alibaba Cloud

O Object Storage Service (OSS) permite configurar tags de objetos para classificá-los. É possível definir regras de ciclo de vida e controlar o acesso a objetos com base nessas tags.

Observações

Antes de configurar as tags de objetos, certifique-se de conhecer bem o recurso. Para mais informações, consulte Object tagging.
Este tópico usa o endpoint público da região China (Hangzhou). Para acessar o OSS a partir de outros serviços do Alibaba Cloud na mesma região, use um endpoint interno. Para mais informações sobre regiões e endpoints do OSS, consulte Regions and endpoints.
Este tópico demonstra como criar uma instância OSSClient com um endpoint do OSS. Para configurações alternativas, como usar um domínio personalizado ou autenticar com credenciais do Security Token Service (STS), consulte Initialization.
Para adicionar uma tag a um objeto, é necessária a permissão oss:PutObjectTagging. Para mais informações, consulte Grant a custom policy.

Adicionar tags a um objeto durante o upload

Adicionar tags a um objeto durante o upload simples

O código a seguir mostra como adicionar tags a um objeto durante o upload simples:

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

import oss2
from oss2.headers import OSS_OBJECT_TAGGING
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Specify the full path of the object. Do not include the bucket name in the full path. Example: exampledir/exampleobject.txt. 
object_name = 'exampledir/exampleobject.txt'

# Configure the tagging string. 
tagging = "k1=v1&k2=v2&k3=v3"

# If tags contain characters, you must encode the keys and values of the tags by using URL encoding. 
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# Add the tagging configurations to the HTTP headers. 
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# Specify the headers when you call the put_object operation so that the tags are added to the object when the object is uploaded. 
result = bucket.put_object(object_name, 'content', headers=headers)
print('http response status: ', result.status)

# Display the tags added to the 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]))

Adicionar tags a um objeto durante o multipart upload

O exemplo abaixo demonstra como adicionar tags a um objeto durante o multipart upload:

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

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Specify the full path of the object. Do not include the bucket name in the full path. Example: exampledir/exampleobject.txt. 
object_name = 'exampledir/exampleobject.txt'
# Specify the full path of the local file. Example: D:\\localpath\\examplefile.txt. 
# By default, if you specify only the name of the local file such as examplefile.txt without specifying the local path, the local file is uploaded from the path of the project to which the sample program belongs. 
filename = 'D:\\localpath\\examplefile.txt'

total_size = os.path.getsize(filename)
# Use the determine_part_size method to determine the part size. 
part_size = determine_part_size(total_size, preferred_size=100 * 1024)

# Configure the tagging string. 
tagging = "k1=v1&k2=v2&k3=v3"

# If tags contain characters, you must encode the keys and values of the tags by using URL encoding. 
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# Add the tagging configurations to the HTTP headers. 
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# Initiate a multipart upload task. 
# Specify the headers when you call the init_multipart_upload operation so that the tags are added to the object that you want to upload. 
upload_id = bucket.init_multipart_upload(object_name, headers=headers).upload_id
parts = []

# Upload the 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)
        # The SizedFileAdapter(fileobj, size) method generates a new object and recalculates the position from which the append operation starts. 
        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

# Complete the multipart upload task. 
result = bucket.complete_multipart_upload(object_name, upload_id, parts)
print('http response status: ', result.status)

# Display the tags added to the 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]))

# Verify the result of the multipart upload task. 
with open(filename, 'rb') as fileobj:
    assert bucket.get_object(object_name).read() == fileobj.read()

Adicionar tags a um objeto durante o append upload

Confira a seguir como adicionar tags a um objeto durante o append upload:

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

import oss2
from oss2.headers import OSS_OBJECT_TAGGING
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Specify the full path of the object. Do not include the bucket name in the full path. Example: exampledir/exampleobject.txt. 
object_name = 'exampledir/exampleobject.txt'

# Configure the tagging string. 
tagging = "k1=v1&k2=v2&k3=v3"

# If tags contain characters, you must encode the keys and values of the tags by using URL encoding. 
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# Add the tagging configurations to the HTTP headers. 
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# Append the object. Specify the headers when you call the append_object operation so that the tags are added to the object. 
# Only the tags configured when the object is appended for the first time are added to the object. 
result = bucket.append_object(object_name, 0, '<yourContent>', headers=headers)

# Display the tags added to the 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]))

Adicionar tags a um objeto durante o resumable upload

O código a seguir ilustra a adição de tags a um objeto durante o resumable upload:

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

import oss2
from oss2.headers import OSS_OBJECT_TAGGING
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Specify the full path of the object. Do not include the bucket name in the full path. Example: exampledir/exampleobject.txt. 
object_name = 'exampledir/exampleobject.txt'
# Specify the full path of the local file. By default, if you do not specify the full path of the local file, the local file is uploaded from the path of the project to which the sample program belongs. 
local_file = 'D:\\localpath\\examplefile.txt'

# Configure the tagging string. 
tagging = "k1=v1&k2=v2&k3=v3"

# If tags contain characters, you must encode the keys and values of the tags by using URL encoding. 
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# Add the tagging configurations to the HTTP headers. 
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# When the object length is greater than or equal to the value of the multipart_threshold parameter, multipart upload is used. The multipart_threshold parameter is optional. The default value of multipart_threshold is 10 MB. If you do not specify a directory by using the store parameter, the .py-oss-upload directory is created in the HOME directory to store the checkpoint information. 
# Specify the headers when you call the resumable_upload operation so that the tags are added to the object that you want to upload. 
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]))

Adicionar ou modificar tags de um objeto existente

Caso um objeto não tenha tags ou as tags atuais não atendam aos seus requisitos, adicione novas tags ou modifique as existentes.

O exemplo a seguir ensina como adicionar ou modificar as tags de um objeto existente:

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

import oss2
from oss2.models import Tagging, TaggingRule
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Specify the full path of the object. Do not include the bucket name in the full path. Example: exampledir/exampleobject.txt. 
object_name = 'exampledir/exampleobject.txt'

# Create a tagging rule. 
rule = TaggingRule()
rule.add('key1', 'value1')
rule.add('key2', 'value2')

# Create tags. 
tagging = Tagging(rule)

# Add the tags to the object. 
result = bucket.put_object_tagging(object_name, tagging)
# Query the HTTP status code. 
print('http response status:', result.status)

Adicionar tags a uma versão específica do objeto ou modificar as tags da versão

Se o versionamento estiver ativado para um bucket, especifique o ID da versão do objeto para adicionar ou modificar as tags de uma versão específica.

O código abaixo demonstra como adicionar tags a uma versão específica de um objeto ou modificar as tags existentes.

Nota

Para mais informações sobre como obter os IDs de versão, consulte List objects.

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

import oss2
from oss2.models import Tagging
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Specify the full path of the object. Do not include the bucket name in the full path. Example: exampledir/exampleobject.txt. 
object_name = 'exampledir/exampleobject.txt'
# Specify the version ID of the object. Example: CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****. 
version_id = 'CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****'

tagging = Tagging()
# Specify the key and the value of the object tag. In this example, the key is set to owner and the value is set to 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)

Adicionar tags a um objeto ao copiá-lo

Ao copiar um objeto, use um dos seguintes métodos para configurar as tags:

Copy: copia a tag do objeto de origem para o objeto de destino.
Replace: o objeto de destino recebe a tag especificada na solicitação, substituindo a tag do objeto de origem.

Os exemplos a seguir descrevem como adicionar tags a um objeto menor que 1 GB no modo de cópia simples e maior que 1 GB no modo de multipart copy:

Adicionar tags a um objeto durante a cópia simples

O exemplo a seguir mostra como adicionar tags a um objeto menor que 1 GB durante a cópia simples:

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

import oss2
from oss2.headers import OSS_OBJECT_TAGGING, OSS_OBJECT_TAGGING_COPY_DIRECTIVE
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Specify the full path of the source object. Do not include the bucket name in the full path. Example: srcexampledir/exampleobject.txt. 
src_object_name = 'srcexampledir/exampleobject.txt'
# Specify the full path of the destination object. Do not include the bucket name in the full path. Example: destexampledir1/exampleobject.txt. 
dest_object_name1 = 'destexampledir1/exampleobject.txt'
# Specify the full path of the destination object. Do not include the bucket name in the full path. Example: destexampledir2/exampleobject.txt. 
dest_object_name2 = 'destexampledir2/exampleobject.txt'

# Configure the tagging string. 
tagging = "k1=v1&k2=v2&k3=v3"

# If tags contain characters, you must encode the keys and values of the tags by using URL encoding. 
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# Set OSS_OBJECT_TAGGING_COPY_DIRECTIVE to COPY or keep the default value in the HTTP headers, so that the tags of the source object are added to the dest_object_name1 object. 
headers=dict()
headers[OSS_OBJECT_TAGGING_COPY_DIRECTIVE] = 'COPY'
bucket.copy_object(bucket.bucket_name, src_object_name, dest_object_name1, headers=headers)

# Set OSS_OBJECT_TAGGING_COPY_DIRECTIVE to REPLACE in the HTTP headers, so that the tags specified in OSS_OBJECT_TAGGING are added to the dest_object_name2 object. 
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)

# Display the tags of the src_object_name object. 
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]))

# Display the tags added to the dest_object_name1 object. The tags of the dest_object_name1 object are the same as those of the src_object_name object. 
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]))

# Display the tags added to the dest_object_name2 object. The tags added to the dest_object_name2 object are those specified in 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]))

Adicionar tags a um objeto durante o multipart copy

O código a seguir ilustra como adicionar tags a um objeto maior que 1 GB durante o multipart copy:

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

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Specify the full path of the source object. Do not include the bucket name in the full path. Example: srcexampledir/exampleobject.txt. 
src_object_name = 'srcexampledir/exampleobject.txt'
# Specify the full path of the destination object. Do not include the bucket name in the full path. Example: destexampledir/exampleobject.txt. 
dest_object_name = 'destexampledir/exampleobject.txt'

# Display the size of the source object. 
head_info = bucket.head_object(src_object_name)
total_size = head_info.content_length
print('src object size:', total_size)

# Use the determine_part_size method to determine the part size. 
part_size = determine_part_size(total_size, preferred_size=100 * 1024)
print('part_size:', part_size)

# Configure the tagging string. 
tagging = "k1=v1&k2=v2&k3=v3"

# If tags contain characters, you must encode the keys and values of the tags by using URL encoding. 
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# Add the tagging configurations to the HTTP headers. 
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# Initiate a multipart upload task. 
# Specify the headers when you call the init_multipart_upload operation so that the tags are added to the destination object. 
upload_id = bucket.init_multipart_upload(dest_object_name, headers=headers).upload_id
parts = []

# Upload the 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)
    # Save the information about each part.
    parts.append(PartInfo(part_number, result.etag))

    offset += num_to_upload
    part_number += 1

# Complete the multipart upload task. 
result = bucket.complete_multipart_upload(dest_object_name, upload_id, parts)

# Obtain the metadata of the destination object. 
head_info = bucket.head_object(dest_object_name)

# Query the size of the destination object. 
dest_object_size = head_info.content_length
print('dest object size:', dest_object_size)

# Compare the size of the destination object with that of the source object. 
assert dest_object_size == total_size

# Display the tags of the source object. 
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]))

# Display the tags added to the destination object. 
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]))

Adicionar tags a um link simbólico

Confira o exemplo a seguir para adicionar tags a um link simbólico:

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

import oss2
from oss2.headers import OSS_OBJECT_TAGGING
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Specify the full path of the destination object. Do not include the bucket name in the full path. Example: exampledir/exampleobject.txt. 
object_name = 'exampledir/exampleobject.txt'
# Specify the full path of the symbolic link object. Example: shortcut/myobject.txt. 
symlink_name = 'shortcut/myobject.txt'

# Configure the tagging string. 
tagging = "k1=v1&k2=v2&k3=v3"

# If tags contain characters, you must encode the keys and values of the tags by using URL encoding. 
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# Add the tagging configurations to the HTTP headers. 
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# Create a symbolic link. 
# Specify the headers when you call the put_symlink operation so that the tags are added to the symbolic link. 
result = bucket.put_symlink(object_name, symlink_name, headers=headers)
print('http response status: ', result.status)

# Display the tags added to the symbolic link. 
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]))

Referências

Para acessar o código de exemplo completo de configuração de tags de objetos, visite o GitHub.
Para mais informações sobre a operação de API usada para configurar tags de objetos, consulte PutObjectTagging.