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

背景信息

设置对象标签时,请注意以下事项:

  • 您可以在上传Object时设置对象标签,也可以对已上传Object设置对象标签。设置对象标签时,若对象已有标签,则覆盖原标签。设置对象标签的详情请参见PutObjectTagging
  • 设置对象标签时要求请求者有PutObjectTagging权限。
  • 更改标签时不会更新Object的Last‑Modified时间。
  • 标签合法字符集包括大小写字母、数字、空格和以下符号:

    +‑=._:/

对象标签使用一组键值对(Key-Value)来标记对象。对象标签的详情请参见对象标签

上传Object时添加对象标签

以下分别介绍简单上传、分片上传、追加上传以及断点续传上传场景下为上传的Object添加对象标签的示例。

  • 简单上传时添加对象标签

    以下代码用于简单上传时添加对象标签:

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    String objectName = "<yourObjectName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    Map<String, String> tags = new HashMap<String, String>();
    tags.put("key1", "value1");
    tags.put("key2", "value2");
    
    // 在HTTP header中设置标签信息。
    ObjectMetadata metadata = new ObjectMetadata();
    metadata.setObjectTagging(tags);
    
    // 上传文件的同时设置标签信息。
    String content = "<yourtContent>";
    ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()), metadata);
    
    // 关闭OSSClient。
    ossClient.shutdown();
  • 分片上传时添加对象标签

    以下代码用于分片上传时添加对象标签:

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    String objectName = "<yourObjectName>";
    String localFile = "<yourLocalFile>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    /* 步骤1:初始化一个分片上传事件。
    */
    // 在HTTP header中设置标签信息。
    Map<String, String> tags = new HashMap<String, String>();
    tags.put("key1", "value1");
    tags.put("key2", "value2");
    
    ObjectMetadata metadata = new ObjectMetadata();
    metadata.setObjectTagging(tags);
    
    // 发起InitiateMultipartUploadRequest请求的同时设置标签信息。
    InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, objectName);
    InitiateMultipartUploadResult result = ossClient.initiateMultipartUpload(request);
    // 返回uploadId,它是分片上传事件的唯一标识。您可以根据这个ID来发起相关的操作,如取消分片上传、查询分片上传等。
    String uploadId = result.getUploadId();
    
    /* 步骤2:上传分片。
    */
    // partETags是PartETag的集合。PartETag由分片的ETag和分片号组成。
    List<PartETag> partETags =  new ArrayList<PartETag>();
    // 计算文件有多少个分片。
    final long partSize = 1 * 1024 * 1024L;   // 1MB
    final File sampleFile = new File("<localFile>");
    long fileLength = sampleFile.length();
    int partCount = (int) (fileLength / partSize);
    if (fileLength % partSize != 0) {
        partCount++;
     }
    // 遍历分片上传。
    for (int i = 0; i < partCount; i++) {
        long startPos = i * partSize;
        long curPartSize = (i + 1 == partCount) ? (fileLength - startPos) : partSize;
        InputStream instream = new FileInputStream(sampleFile);
        // 跳过已上传的分片。
        instream.skip(startPos);
        UploadPartRequest uploadPartRequest = new UploadPartRequest();
        uploadPartRequest.setBucketName(bucketName);
        uploadPartRequest.setKey(objectName);
        uploadPartRequest.setUploadId(uploadId);
        uploadPartRequest.setInputStream(instream);
        // 设置分片大小。除了最后一个分片没有大小限制,其他的分片最小为100 KB。
        uploadPartRequest.setPartSize(curPartSize);
        // 设置分片号。每一个上传的分片都有一个分片号,取值范围是1~10000,如果超出这个范围,OSS将返回InvalidArgument的错误码。
        uploadPartRequest.setPartNumber( i + 1);
      // 每个分片不需要按顺序上传,甚至可以在不同客户端上传,OSS会按照分片号排序组成完整的文件。
        UploadPartResult uploadPartResult = ossClient.uploadPart(uploadPartRequest);
      // 每次上传分片之后,OSS的返回结果会包含一个PartETag。PartETag将被保存到partETags中。
        partETags.add(uploadPartResult.getPartETag());
    }
    
    /* 步骤3:完成分片上传。
    */
    // partETags必须按分片号升序排列。
    Collections.sort(partETags, new Comparator<PartETag>() {
        public int compare(PartETag p1, PartETag p2) {
            return p1.getPartNumber() - p2.getPartNumber();
        }
    });
    // 在执行该操作时,需要提供所有有效的partETags。OSS收到提交的partETags后,会逐一验证每个分片的有效性。当所有的数据分片验证通过后,OSS将把这些分片组合成一个完整的文件。
    CompleteMultipartUploadRequest completeMultipartUploadRequest =
            new CompleteMultipartUploadRequest(bucketName, objectName, uploadId, partETags);
    ossClient.completeMultipartUpload(completeMultipartUploadRequest);
    
    // 查看文件标签信息。
    TagSet tagSet = ossClient.getObjectTagging(bucketName, objectName);
    Map<String, String> getTags = tagSet.getAllTags();
    System.out.println("object tagging: "+ getTags.toString());
    
    // 关闭OSSClient。
    ossClient.shutdown();
  • 追加上传时添加对象标签

    以下代码用于追加上传时添加对象标签:

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    String objectName = "<yourObjectName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    String content1 = "Hello OSS A \n";
    String content2 = "Hello OSS B \n";
    String content3 = "Hello OSS C \n";
    
    Map<String, String> tags = new HashMap<String, String>();
    tags.put("key1", "value1");
    tags.put("key2", "value2");
    
    ObjectMetadata meta = new ObjectMetadata();
    // 设置上传文件的标签。
     meta.setObjectTagging(tags);
    // 指定上传的内容类型。
    meta.setContentType("text/plain");
    
    // 通过AppendObjectRequest设置多个参数。
    AppendObjectRequest appendObjectRequest = new AppendObjectRequest(bucketName, objectName, new ByteArrayInputStream(content1.getBytes()), meta);
    
    // 通过AppendObjectRequest设置单个参数。
    // 设置存储空间名称。
    //appendObjectRequest.setBucketName("<yourBucketName>");
    // 设置文件名称。
    //appendObjectRequest.setKey("<yourObjectName>");
    // 设置待追加的内容。有两种可选类型:InputStream类型和File类型。这里为InputStream类型。
    //appendObjectRequest.setInputStream(new ByteArrayInputStream(content1.getBytes()));
    // 设置待追加的内容。有两种可选类型:InputStream类型和File类型。这里为File类型。
    //appendObjectRequest.setFile(new File("<yourLocalFile>"));
    // 指定文件的元信息,第一次追加时有效。
    //appendObjectRequest.setMetadata(meta);
    
    // 第一次追加。只有第一次追加上传时设置的标签生效。
    // 设置文件的追加位置。
    appendObjectRequest.setPosition(0L);
    AppendObjectResult appendObjectResult = ossClient.appendObject(appendObjectRequest);
    // 文件的64位CRC值。此值根据ECMA-182标准计算得出。
    System.out.println(appendObjectResult.getObjectCRC());
    
    // 第二次追加。
    // nextPosition指明下一次请求中应当提供的Position,即文件当前的长度。
    appendObjectRequest.setPosition(appendObjectResult.getNextPosition());
    appendObjectRequest.setInputStream(new ByteArrayInputStream(content2.getBytes()));
    appendObjectResult = ossClient.appendObject(appendObjectRequest);
    
    // 第三次追加。
    appendObjectRequest.setPosition(appendObjectResult.getNextPosition());
    appendObjectRequest.setInputStream(new ByteArrayInputStream(content3.getBytes()));
    appendObjectResult = ossClient.appendObject(appendObjectRequest);
    
    // 查看上传文件的标签信息。
    TagSet tagSet = ossClient.getObjectTagging(bucketName, objectName);
    Map<String, String> getTags = tagSet.getAllTags();
    System.out.println("object tagging: "+ getTags.toString());
    
    // 关闭OSSClient。
    ossClient.shutdown();
  • 断点续传上传时添加对象标签

    以下代码用于断点续传上传时添加对象标签:

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 设置文件的标签信息。
    Map<String, String> tags = new HashMap<String, String>();
    tags.put("key1", "value1");
    tags.put("key2", "value2");
    
    ObjectMetadata meta = new ObjectMetadata();
    // 指定上传的内容类型。
    meta.setContentType("text/plain");
    // 设置文件标签。
    meta.setObjectTagging(tags);
    
    // 通过UploadFileRequest设置多个参数。
    UploadFileRequest uploadFileRequest = new UploadFileRequest("<yourBucketName>","<yourObjectName>");
    
    // 通过UploadFileRequest设置单个参数。
    // 设置存储空间名称。
    //uploadFileRequest.setBucketName("<yourBucketName>");
    // 设置文件名称。
    //uploadFileRequest.setKey("<yourObjectName>");
    // 指定上传的本地文件。
    uploadFileRequest.setUploadFile("<yourLocalFile>");
    // 指定上传并发线程数,默认为1。
    uploadFileRequest.setTaskNum(5);
    // 指定上传的分片大小,范围为100 KB~5 GB,默认上传的分片大小是整个文件大小的1/10000。
    uploadFileRequest.setPartSize(1 * 1024 * 1024);
    // 开启断点续传,默认关闭。
    uploadFileRequest.setEnableCheckpoint(true);
    // 记录本地分片上传结果的文件。开启断点续传功能时需要设置此参数,上传过程中的进度信息会保存在该文件中,如果某一分片上传失败,再次上传时会根据文件中记录的点继续上传。上传完成后,该文件会被删除。默认与待上传的本地文件同目录,为uploadFile.ucp。
    uploadFileRequest.setCheckpointFile("<yourCheckpointFile>");
    // 文件的元数据。
    uploadFileRequest.setObjectMetadata(meta);
    // 设置上传成功回调,参数为Callback类型。
    uploadFileRequest.setCallback("<yourCallbackEvent>");
    
    // 断点续传上传, 同时设置文件标签。
    ossClient.uploadFile(uploadFileRequest);
    
    // 查看文件的标签信息。
    TagSet tagSet = ossClient.getObjectTagging(bucketName, objectName);
    Map<String, String> getTags = tagSet.getAllTags();
    System.out.println("object tagging: "+ getTags.toString());
    
    // 关闭OSSClient。
    ossClient.shutdown();

对已上传Object添加或更改对象标签

以下代码用于对已上传Object添加或更改对象标签:

// Endpoint以杭州为例,其它Region请按实际情况填写。
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";
String bucketName = "<yourBucketName>";
String objectName = "<yourObjectName>";

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

Map<String, String> tags = new HashMap<String, String>();
tags.put("key1", "value1");
tags.put("key2", "value2");

// 给文件设置标签。
ossClient.setObjectTagging(bucketName, objectName, tags);

// 关闭OSSClient。
ossClient.shutdown();

拷贝Object时设置对象标签

拷贝Object时,可以指定如何设置目标Object的对象标签。取值如下:
  • Copy(默认值):复制源Object的对象标签到目标Object。
  • Replace:忽略源Object的对象标签,直接采用请求中指定的对象标签。

以下分别提供了简单拷贝1 GB以下的Object及分片拷贝1 GB以上的Object时设置对象标签的详细示例。

  • 以下代码用于简单拷贝1 GB以下的Object时设置对象标签:

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    
    String sourceBucketName = "<yourSourceBucketName>";
    String sourceObjectName = "<yourSourceObjectName>";
    String destinationBucketName = "<yourDestinationBucketName>";
    String destinationObjectName = "<yourDestinationObjectName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 创建CopyObjectRequest对象。
    CopyObjectRequest copyObjectRequest = new CopyObjectRequest(sourceBucketName, sourceObjectName, destinationBucketName, destinationObjectName);
    
    // 设置目标文件的标签。如果不设置headers,目标文件默认复制源文件的标签。
    Map<String, String> headers = new HashMap<String, String>();
    headers.put(OSSHeaders.COPY_OBJECT_TAGGING_DIRECTIVE, "REPLACE");
    headers.put(OSSHeaders.OSS_TAGGING, "key1=value1&key2=value2");
    copyObjectRequest.setHeaders(headers);
    
    // 复制文件。
    CopyObjectResult result = ossClient.copyObject(copyObjectRequest);
    System.out.println("ETag: " + result.getETag() + " LastModified: " + result.getLastModified());
    
    // 查看目标文件的标签信息。
    TagSet tagSet = ossClient.getObjectTagging(bucketName, destinationObjectName);
    Map<String, String> getTags = tagSet.getAllTags();
    System.out.println("dest object tagging: "+ getTags.toString());
    
    // 关闭OSSClient。
    ossClient.shutdown();
  • 以下代码用于分片拷贝1 GB以上的Object时设置对象标签:
    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    
    String sourceBucketName = "<yourSourceBucketName>";
    String sourceObjectName = "<yourSourceObjectName>";
    String destinationBucketName = "<yourDestinationBucketName>";
    String destinationObjectName = "<yourDestinationObjectName>";
    
    ObjectMetadata objectMetadata = ossClient.getObjectMetadata(sourceBucketName, sourceObjectName);
    // 获取被拷贝文件的大小。
    long contentLength = objectMetadata.getContentLength();
    // 设置分片大小为10 MB。
    long partSize = 1024 * 1024 * 10;
    // 计算分片总数。
    int partCount = (int) (contentLength / partSize);
    if (contentLength % partSize != 0) {
        partCount++;
    }
    
    System.out.println("total part count:" + partCount);
    
    // 在HTTP header中设置标签信息。
    Map<String, String> tags2 = new HashMap<String, String>();
    tags2.put("key3", "value3");
    tags2.put("key4", "value4");
    
    ObjectMetadata metadata = new ObjectMetadata();
    metadata.setObjectTagging(tags2);
    
    // 初始化拷贝任务。同时给要拷贝的目标文件设置标签。
    InitiateMultipartUploadRequest initiateMultipartUploadRequest = new InitiateMultipartUploadRequest(destinationBucketName, destinationObjectName, metadata);
    InitiateMultipartUploadResult initiateMultipartUploadResult = ossClient.initiateMultipartUpload(initiateMultipartUploadRequest);
    String uploadId = initiateMultipartUploadResult.getUploadId();
    
    // 分片拷贝。
    List<PartETag> partETags = new ArrayList<PartETag>();
    for (int i = 0; i < partCount; i++) {
         // 计算每个分片的大小。
        long skipBytes = partSize * i;
        long size = partSize < contentLength - skipBytes ? partSize : contentLength - skipBytes;
    
        // 创建UploadPartCopyRequest。可以通过UploadPartCopyRequest指定限定条件。
        UploadPartCopyRequest uploadPartCopyRequest = 
            new UploadPartCopyRequest(sourceBucketName, sourceObjectName, destinationBucketName, destinationObjectName);
        uploadPartCopyRequest.setUploadId(uploadId);
        uploadPartCopyRequest.setPartSize(size);
        uploadPartCopyRequest.setBeginIndex(skipBytes);
        uploadPartCopyRequest.setPartNumber(i + 1);
    
        UploadPartCopyResult uploadPartCopyResult = ossClient.uploadPartCopy(uploadPartCopyRequest);
        // 将返回的分片ETag保存到partETags中。
        partETags.add(uploadPartCopyResult.getPartETag());
    }
    
    // 提交分片拷贝任务。
    CompleteMultipartUploadRequest completeMultipartUploadRequest = new CompleteMultipartUploadRequest(
                        destinationBucketName, destinationObjectName, uploadId, partETags);
    CompleteMultipartUploadResult completeMultipartUploadResult = ossClient.completeMultipartUpload(completeMultipartUploadRequest);
    
    // 查看源文件的标签信息。
    TagSet tagSet = ossClient.getObjectTagging(bucketName, sourceObjectName);
    Map<String, String> getTags = tagSet.getAllTags();
    System.out.println("src object tagging: "+ getTags.toString());
    
    // 查看目标文件的标签信息。
    tagSet = ossClient.getObjectTagging(bucketName, destinationObjectName);
    getTags = tagSet.getAllTags();
    System.out.println("dest object tagging: "+ getTags.toString());
    
    // 关闭OSSClient。
    ossClient.shutdown();

为软链接文件设置标签

以下代码用于为软链接文件设置标签:

// Endpoint以杭州为例,其它Region请按实际情况填写。
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";
String bucketName = "<yourBucketName>";
String symLink = "<yourSymLink>";
String destinationObjectName = "<yourDestinationObjectName>";

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

// 设置软链接的标签信息。
Map<String, String> tags = new HashMap<String, String>();
tags.put("key1", "value1");
tags.put("key2", "value2");

// 创建上传文件元信息。
ObjectMetadata metadata = new ObjectMetadata();
metadata.setObjectTagging(tags);

// 创建CreateSymlinkRequest。
CreateSymlinkRequest createSymlinkRequest = new CreateSymlinkRequest(bucketName, symLink, destinationObjectName);

// 设置元信息。
createSymlinkRequest.setMetadata(metadata);

// 创建软链接。
ossClient.createSymlink(createSymlinkRequest);

// 查看软链接的标签信息。
TagSet tagSet = ossClient.getObjectTagging(bucketName, symLink);
Map<String, String> getTags = tagSet.getAllTags();
System.out.println("symLink tagging: "+ getTags.toString());

// 关闭OSSClient。
ossClient.shutdown();