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

背景信息

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

  • 您可以在上传Object时设置对象标签,也可以对已上传Object设置对象标签。设置对象标签时,如果对象已有标签,则覆盖原标签。关于设置对象标签的更多信息,请参见PutObjectTagging
  • 设置对象标签时,您要有PutObjectTagging权限。

    请通过脚本配置方式创建以上自定义权限策略,然后为指定的RAM用户授予相应权限。具体操作,请参见为RAM用户授权自定义的RAM Policy

  • 更改标签时不会更新Object的Last‑Modified时间。
  • 单个Object最多可设置10个标签,Key不可重复。
  • 每个Key长度不超过128字节,每个Value长度不超过256字节。
  • Key和Value区分大小写。
  • 标签合法字符集包括大小写字母、数字、空格和以下符号:

    +‑=._:/

    说明 通过HTTP header的方式设置标签且标签中包含任意字符时,您可以对标签的Key和Value做URL编码。

对象标签使用一组键值对(Key-Value)来标记对象。关于对象标签的更多信息,请参见对象标签

上传Object时添加对象标签

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

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

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

    // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
    String endpoint = "yourEndpoint";
    // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
    String accessKeyId = "yourAccessKeyId";
    String accessKeySecret = "yourAccessKeySecret";
    // 填写Bucket名称,例如examplebucket。
    String bucketName = "examplebucket";
    // 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
    String objectName = "exampledir/exampleobject.txt";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    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);
    
    // 关闭OSSClient。
    ossClient.shutdown();
  • 分片上传时添加对象标签

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

    // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
    String endpoint = "yourEndpoint";
    // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
    String accessKeyId = "yourAccessKeyId";
    String accessKeySecret = "yourAccessKeySecret";
    // 填写Bucket名称,例如examplebucket。
    String bucketName = "examplebucket";
    // 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
    String objectName = "exampledir/exampleobject.txt";
    // 填写本地文件的完整路径。如果未指定本地路径,则默认从示例程序所属项目对应本地路径中上传文件。
    String localFile = "D:\\localpath\\examplefile.txt";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    /* 
       步骤1:初始化一个分片上传事件。
    */
    // 在HTTP header中设置标签信息。
    Map<String, String> tags = new HashMap<String, String>();
    // 依次填写对象标签的键(例如owner)和值(例如John)。
    tags.put("owner", "John");
    tags.put("type", "document");
    
    ObjectMetadata metadata = new ObjectMetadata();
    metadata.setObjectTagging(tags);
    
    // 发起InitiateMultipartUploadRequest请求的同时设置标签信息。
    InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, objectName, metadata);
    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;   // 1 MB。
    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 = null;
        try {
            instream = new FileInputStream(sampleFile);
            // 跳过已上传的分片。
            instream.skip(startPos);
        } catch (FileNotFoundException e) {
            e.printStackTrace();
        } catch (IOException e) {
            e.printStackTrace();
        }
        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>