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控制台
登入OSS管理主控台。
單擊Bucket 列表,然後單擊目標Bucket名稱。
在左側導覽列,選擇文件管理>檔案清單。
為Object設定標籤。
選擇需要設定標籤的Object。
Bucket未開啟版本控制
在目標Object右側操作欄下,選擇
> 標籤。
Bucket已開啟版本控制
在指定版本Object右側操作欄下,選擇
> 標籤。
在標籤面板,按標籤使用規則說明指定標籤的鍵和值。
單擊確定。
使用阿里雲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";
// 填寫Bucket所在地區。以華東1(杭州)為例,Region填寫為cn-hangzhou。
String region = "cn-hangzhou";
// 建立OSSClient執行個體。
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
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,
"signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
"region"=> "cn-hangzhou"
);
$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,
authorizationV4: true,
// 填寫儲存空間名稱。
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.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"
# examplebucket填寫儲存空間名稱。
bucket = oss2.Bucket(auth, endpoint, "examplebucket", region=region)
# 填寫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;
using Aliyun.OSS.Common;
// 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();
}
// 填寫Bucket所在地區對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。
const string region = "cn-hangzhou";
// 建立ClientConfiguration執行個體,按照您的需要修改預設參數。
var conf = new ClientConfiguration();
// 設定v4簽名。
conf.SignatureVersion = SignatureVersion.V4;
// 建立OssClient執行個體。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);
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);
}
#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 = "yourEndpoint";
/* yourRegion填寫Bucket所在地區對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。*/
std::string Region = "yourRegion";
/* 填寫Bucket名稱,例如examplebucket。*/
std::string BucketName = "examplebucket";
/* 填寫Object完整路徑,完整路徑中不能包含Bucket名稱,例如exampledir/exampleobject.txt。*/
std::string ObjectName = "exampledir/exampleobject.txt";
/* 初始化網路等資源。*/
InitializeSdk();
ClientConfiguration conf;
conf.signatureVersion = SignatureVersionType::V4;
/* 從環境變數中擷取訪問憑證。運行本程式碼範例之前,請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
OssClient client(Endpoint, credentialsProvider, conf);
client.SetRegion(Region);
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;
}
package main
import (
"context"
"flag"
"log"
"strings"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)
// 定義全域變數
var (
region string // 儲存地區
bucketName string // 儲存空間名稱
objectName string // 對象名稱
)
// init函數用於初始化命令列參數
func init() {
flag.StringVar(®ion, "region", "", "The region in which the bucket is located.")
flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
flag.StringVar(&objectName, "object", "", "The name of the object.")
}
func main() {
// 解析命令列參數
flag.Parse()
// 檢查bucket名稱是否為空白
if len(bucketName) == 0 {
flag.PrintDefaults()
log.Fatalf("invalid parameters, bucket name required")
}
// 檢查region是否為空白
if len(region) == 0 {
flag.PrintDefaults()
log.Fatalf("invalid parameters, region required")
}
// 檢查object名稱是否為空白
if len(objectName) == 0 {
flag.PrintDefaults()
log.Fatalf("invalid parameters, object name required")
}
// 定義要上傳的內容
content := "hi oss"
// 載入預設配置並設定憑證提供者和地區
cfg := oss.LoadDefaultConfig().
WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
WithRegion(region)
// 建立OSS用戶端
client := oss.NewClient(cfg)
// 建立上傳對象的請求
request := &oss.PutObjectRequest{
Bucket: oss.Ptr(bucketName), // 儲存空間名稱
Key: oss.Ptr(objectName), // 對象名稱
Body: strings.NewReader(content), // 要上傳的內容
Tagging: oss.Ptr("tag1=value1&tag2=value2"), // 填寫實際的對象標籤
}
// 執行上傳對象的請求
result, err := client.PutObject(context.TODO(), request)
if err != nil {
log.Fatalf("failed to put object %v", err)
}
// 列印上傳對象的結果
log.Printf("put object result:%#v\n", result)
}
使用命令列工具ossutil
您可以使用命令列工具ossutil來添加或修改標籤,ossutil的安裝請參見安裝ossutil。
以下命令為儲存空間examplebucket
中的對象exampleobject添加或修改標籤。
ossutil api put-object-tagging --bucket examplebucket --key exampleobject --tagging "{\"TagSet\":{\"Tag\":[{\"Key\":\"key1\",\"Value\":\"value1\"},{\"Key\":\"key2\",\"Value\":\"value2\"}]}}"
關於該命令的更多資訊,請參見put-object-tagging。
相關API
以上操作方式底層基於API實現,如果您的程式自訂要求較高,您可以直接發起REST API請求。直接發起REST API請求需要手動編寫代碼計算簽名。更多資訊,請參見PutObjectTagging。