全部产品
Search
文档中心

对象存储 OSS:对象标签

更新时间:Feb 26, 2024

OSS支持使用标签对存储空间(Bucket)中的对象(Object)进行分类,您可以针对同标签的Object设置生命周期规则、访问权限等。

标签规则

Object标签使用一组键值对(Key-Value)标记Object,您可以在上传Object时添加标签,也可以为已有Object添加标签。

  • 单个Object最多可设置10个标签,Key不可重复。

  • 每个Key长度不超过128字符,每个Value长度不超过256字符。

  • Key和Value区分大小写。

  • 标签合法字符集包括大小写字母、数字、空格和以下符号:

    +‑=._:/

    通过HTTP Header的方式设置标签且标签中包含任意字符时,您需要对标签的Key和Value进行URL编码。

注意事项

  • 只有Bucket拥有者以及被授予oss:PutObjectTagging权限的用户拥有读写Object标签的权限。

  • 您可以在简单上传、分片上传、追加上传以及拷贝文件过程中为Object设置标签,也可以对已上传Object设置标签。

  • Object添加标签后,OSS会按照每小时内统计的标签数量收取标签费用。更多信息,请参见对象标签费用

  • 更改标签信息不会更新Object的Last‑Modified时间。

  • 跨区域复制时,源Object标签也会复制到目标Bucket。

使用场景

  • Object标签结合生命周期

    对于周期性生成且无需长期保存的Object,可以在上传时设置指定的标签,之后通过生命周期规则,将拥有该标签的文件定期删除,从而节省存储费用。例如,通过生命周期规则指定前缀为dir1且拥有Key为key1、Value为value1标签的Object在距离最后一次更新时间30天后删除,配置示例如下:

    <LifecycleConfiguration>
     <Rule>
      <ID>rule1</ID>
      <Prefix>dir1</Prefix>
      <Tag><Key>key1</Key><Value>value1</Value></Tag>
      <Status>Enabled</Status>
      <Expiration>
        <Days>30</Days>
      </Expiration>
     </Rule>
    </LifecycleConfiguration>
  • 授权RAM用户访问指定标签的Object

    例如,您可以通过RAM Policy授权RAM用户访问Key为key2、Value为value2的所有Object,RAM Policy配置示例如下。

    {
      "Version": "1",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "oss:GetObject",
          "Resource": "*",
          "Condition": {
            "StringEquals": {
              "oss:ExistingObjectTag/key2": [
                "value2"
              ]
            }
          }
        }
      ]
    }

    您还可以授予该用户其他操作权限(Action),例如向拥有指定标签的Object写入数据、查看Object相关信息等。关于RAM Policy支持的Action信息,请参见RAM Policy

操作步骤

使用OSS控制台

  1. 登录OSS管理控制台

  2. 单击Bucket 列表,然后单击目标Bucket名称。

  3. 在左侧导航栏,选择文件管理>文件列表

  4. 为Object设置标签。

    1. 选择需要设置标签的Object。

      • Bucket未开启版本控制

        在目标Object右侧操作栏下,选择more > 标签

      • Bucket已开启版本控制

        在指定版本Object右侧操作栏下,选择more > 标签

    2. 标签面板,按标签使用规则说明指定标签的

  5. 单击确定

使用阿里云SDK

以下仅列举常见SDK在简单上传过程中设置Object标签的代码示例。关于其他SDK在简单上传、分片上传、追加上传、拷贝文件过程中设置Object标签的代码示例,请参见SDK简介

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;
import java.io.ByteArrayInputStream;
import java.util.HashMap;
import java.util.Map;

public class Demo {
    public static void main(String[] args) throws Exception {
        // Endpoint以华东1(杭州)为例,其它Region请按实际情况填写。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填写Bucket名称,例如examplebucket。
        String bucketName = "examplebucket";
        // 填写Object完整路径,Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
        String objectName = "exampledir/exampleobject.txt";

        // 创建OSSClient实例。
        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);

        try {
            Map<String, String> tags = new HashMap<String, String>();
            // 依次填写对象标签的键(例如owner)和值(例如John)。
            tags.put("owner", "John");
            tags.put("type", "document");

            // 在HTTP header中设置标签信息。
            ObjectMetadata metadata = new ObjectMetadata();
            metadata.setObjectTagging(tags);

            // 上传文件的同时设置标签信息。
            String content = "<yourtContent>";
            ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()), metadata);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}
<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\CoreOssException;

// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 
$provider = new EnvironmentVariableCredentialsProvider();
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
$endpoint = "yourEndpoint";
// 填写Bucket名称,例如examplebucket。
$bucket = "examplebucket";
// 填写Object完整路径,Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
$object = "exampledir/exampleobject.txt";
// 填写待上传的字符串。
$content = "hello world";

$config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
    );
    $ossClient = new OssClient($config);

// 设置对象标签。
$options = array(
      OssClient::OSS_HEADERS => array(
              'x-oss-tagging' => 'key1=value1&key2=value2&key3=value3',
));
  
try {
      // 通过简单上传的方式上传Object。
      $ossClient->putObject($bucket, $object, $content, $options);
} catch (OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}

print(__FUNCTION__ . ": OK" . "\n");  
const OSS = require('ali-oss')

const client = new OSS({
  // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
  region: 'yourregion',
  // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // 填写存储空间名称。
  bucket: 'yourbucketname'
});

// 填写Object完整路径,Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
const objectName = 'exampledir/exampleobject.txt'
// 填写本地文件的完整路径,例如D:\\localpath\\examplefile.txt。
// 如果未指定本地路径只填写了本地文件名称(例如examplefile.txt),则默认从示例程序所属项目对应本地路径中上传文件。
const localFilepath = 'D:\\localpath\\examplefile.txt'

// 设置请求头信息。
const headers = {
  // 依次填写对象标签的键(例如owner)和值(例如John)。
  'x-oss-tagging': 'owner=John&type=document', 
}

client.put(objectName, localFilepath, {
  headers
})
# -*- 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]))
using System.Text;
using Aliyun.OSS;
using System.Text;
using Aliyun.OSS.Util;

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
var endpoint = "yourEndpoint";
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// 填写Bucket名称。
var bucketName = "examplebucket";
// 填写Object完整路径。Object完整路径中不能包含Bucket名称。
var objectName = "exampleobject.txt";
var objectContent = "More than just cloud.";

String UrlEncodeKey(String key)
{
const string CharsetName = "utf-8";
const char separator = '/';
var segments = key.Split(separator);

var encodedKey = new StringBuilder();
encodedKey.Append(HttpUtils.EncodeUri(segments[0], CharsetName));
for (var i = 1; i < segments.Length; i++)
    encodedKey.Append(separator).Append(HttpUtils.EncodeUri(segments[i], CharsetName));

    if (key.EndsWith(separator.ToString()))
    {
        // String#split ignores trailing empty strings, e.g., "a/b/" will be split as a 2-entries array,
        // so we have to append all the trailing slash to the uri.
        foreach (var ch in key)
        {
            if (ch == separator)
                encodedKey.Append(separator);
            else
                break;
        }
    }

return encodedKey.ToString();
}
// 创建OssClient实例。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{
    byte[] binaryData = Encoding.ASCII.GetBytes(objectContent);
    MemoryStream requestContent = new MemoryStream(binaryData);

    var meta = new ObjectMetadata();
    // 在HTTP header中设置标签信息。
    string str = UrlEncodeKey("key1") + "=" + UrlEncodeKey("value1") + "&" + UrlEncodeKey("key2") + "=" + UrlEncodeKey("value2");
    meta.AddHeader("x-oss-tagging", str);
    var putRequest = new PutObjectRequest(bucketName, objectName, requestContent);
    putRequest.Metadata = meta;

    // 上传文件的同时对文件设置标签。
    client.PutObject(putRequest);
    Console.WriteLine("Put object succeeded");
}
catch (Exception ex)
{
    Console.WriteLine("Put object failed, {0}", ex.Message);
}
package main

import (
	"fmt"
	"os"
	"strings"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// 创建OSSClient实例。
	// yourEndpoint填写Bucket对应的Endpoint,以华东1(杭州)为例,填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。
	client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// 填写Bucket名称,例如examplebucket。
	bucketName := "examplebucket"
	// 填写Object完整路径,Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
	objectName := "exampledir/exampleobject.txt"

	// 获取存储空间。
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// 依次填写对象标签的键(例如owner)和值(例如John)。
	tag1 := oss.Tag{
		Key:   "owner",
		Value: "John",
	}
	tag2 := oss.Tag{
		Key:   "type",
		Value: "document",
	}
	tagging := oss.Tagging{
		Tags: []oss.Tag{tag1, tag2},
	}

	// 设置对象标签。
	err = bucket.PutObject(objectName, strings.NewReader("Hello OSS"), oss.SetTagging(tagging))
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	fmt.Println(bucket.GetObjectTagging(objectName))
}
#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* 初始化OSS账号信息。*/
    
    /* yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。*/
    std::string Endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
    /* 填写Bucket名称,例如examplebucket。*/
    std::string BucketName = "examplebucket";
    /* 填写Object完整路径,完整路径中不能包含Bucket名称,例如exampledir/exampleobject.txt。*/
    std::string ObjectName = "exampledir/exampleobject.txt";

    /* 初始化网络等资源。*/
    InitializeSdk();

    ClientConfiguration conf;
    /* 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    std::shared_ptr<std::iostream> content = std::make_shared<std::stringstream>();
    *content << "test cpp sdk";
    PutObjectRequest request(BucketName, ObjectName, content);

    /* 设置标签。*/
    Tagging tagging;
    tagging.addTag(Tag("key1", "value1"));
    tagging.addTag(Tag("key2", "value2"));
    request.setTagging(tagging.toQueryParameters());

    /* 上传文件。*/
    auto outcome = client.PutObject(request);

    if (!outcome.isSuccess()) {
        /* 异常处理。*/
        std::cout << "PutObject fail" <<
        ",code:" << outcome.error().Code() <<
        ",message:" << outcome.error().Message() <<
        ",requestId:" << outcome.error().RequestId() << std::endl;
        return -1;
    }

    /* 释放网络等资源。*/
    ShutdownSdk();
    return 0;
}

使用命令行工具ossutil

关于使用ossutil设置Object标签的具体操作,请参见添加或修改Object标签

使用REST API

如果您的程序自定义要求较高,您可以直接发起REST API请求。直接发起REST API请求需要手动编写代码计算签名。更多信息,请参见PutObjectTagging