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时添加对象标签

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

    以下代码用于简单上传时(即通过PutObject方法)添加对象标签。

    const OSS = require('ali-oss')
    
    const client = new OSS({
      // yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourRegion',
      // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // 填写Bucket名称,例如examplebucket。
      bucket: 'examplebucket',
    });
    
    // 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
    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
    })
  • 分片上传时添加对象标签

    以下代码用于分片上传时(即通过multipartUpload方法)添加对象标签。

    const OSS = require('ali-oss')
    
    const client = new OSS({
      // yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourRegion',
      // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // 填写Bucket名称,例如examplebucket。
      bucket: 'examplebucket',
    });
    
    // 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
    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', 
    }
    
    
    async function setTag() {
      await client.multipartUpload(objectName, localFilepath, {
        // 设置分片大小,单位为字节。除了最后一个分片没有大小限制,其他的分片最小为100 KB。
        partSize: 100 * 1024,
        headers
      });
      const tag = await client.getObjectTagging(objectName);
      console.log(tag);
    }
    
    setTag()
  • 追加上传时添加对象标签

    以下代码用于追加上传时(即通过AppendObject方法)添加对象标签。

    const OSS = require('ali-oss')
    
    const client = new OSS({
      // yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourRegion',
      // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // 填写Bucket名称,例如examplebucket。
      bucket: 'examplebucket',
    });
    // 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
    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',
    }
    
    
    // 追加上传文件,append接口指定header时,将会为文件设置标签。
    // 只有第一次调用append接口设置的标签才会生效,后续再次调用append接口设置的标签不生效。
    async function setTag() {
      await client.append(objectName, localFilepath, {
        // 设置分片大小,单位为字节。除了最后一个分片没有大小限制,其他的分片最小为100 KB。
        partSize: 100 * 1024,
        headers
      });
      const tag = await client.getObjectTagging(objectName);
      console.log(tag);
    }
    
    
    setTag()
  • 断点续传上传时添加对象标签

    以下代码用于断点续传上传时(即通过multipartUpload方法)添加对象标签。

    const OSS = require('ali-oss')
    
    const client = new OSS({
      // yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourRegion',
      // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // 填写Bucket名称,例如examplebucket。
      bucket: 'examplebucket',
    });
    
    // 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
    const objectName = 'exampledir/exampleobject.txt'
    // 填写本地文件的完整路径,例如D:\\localpath\\examplefile.txt。
    // 如果本地文件的完整路径中未指定本地路径只填写了本地文件名称(例如examplefile.txt),则默认从示例程序所属项目对应本地路径中上传文件。
    const localFilepath = 'D:\\localpath\\examplefile.txt'
    // 设置断点信息。
    let checkpoint;
    
    // 设置请求头信息。
    const headers = {
      // 依次填写对象标签的键(例如owner)和值(例如John)。
      'x-oss-tagging': 'owner=John&type=document',
    }
    
    
    async function setTag() {
      await client.multipartUpload(objectName, localFilepath, {
        checkponit,
        async progress(percentage, cpt) {
          checkpoint = cpt;
        },
        headers
      });
      const tag = await client.getObjectTagging(objectName);
      console.log(tag);
    }
    
    setTag()

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

如果上传Object时未添加对象标签或者添加的对象标签不满足使用需求,您可以在上传Object后为Object添加或更改对象标签。

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

const OSS = require('ali-oss')

const client = new OSS({
  // yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
  region: 'yourRegion',
  // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // 填写Bucket名称,例如examplebucket。
  bucket: 'examplebucket',
});

// 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
const objectName = 'exampledir/exampleobject.txt'
// 依次填写对象标签的键(例如owner)和值(例如John)。
const tag = { owner: 'John', type: 'document' };

async function putObjectTagging(objectName, tag) {
  try {
    const result = await client.putObjectTagging(objectName, tag);
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

putObjectTagging(objectName, tag)

为Object指定版本添加或更改对象标签

在已开启版本控制的Bucket中,通过指定Object的版本ID(versionId),您可以为Object指定版本添加或更改对象标签。

以下代码用于为Object指定版本添加或更改对象标签。

说明 关于获取versionId的具体操作,请参见列举文件
const OSS = require('ali-oss')

const client = new OSS({
  // yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
  region: 'yourRegion',
  // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // 填写Bucket名称,例如examplebucket。
  bucket: 'examplebucket',
});

// 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
const objectName = 'exampledir/exampleobject.txt'
// 依次填写对象标签的键(例如owner)和值(例如John)。
const tag = { owner: 'John', type: 'document' };
// 填写Object的版本ID。
const versionId = 'CAEQIRiBgMDqvPqA3BciIDJhMjE4MWZkN2ViYTRmYzJhZjkxMzk2YWM2NjJk****'

async function putObjectTagging(objectName, tag) {
  try {
    const options = {
      versionId
    };
    const result = await client.putObjectTagging(objectName, tag, options);
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

putObjectTagging(objectName, tag)

拷贝Object时设置对象标签

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

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

  • 简单拷贝时添加对象标签

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

    const OSS = require('ali-oss')
    
    const client = new OSS({
      // yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourRegion',
      // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // 填写Bucket名称,例如examplebucket。
      bucket: 'examplebucket',
    });
    
    // 填写源Object完整路径,例如srcexampledir/exampleobject.txt。
    const sourceObjectName = 'srcexampledir/exampleobject.txt';
    // 填写目标Object完整路径,例如destexampledir/exampleobject.txt。 
    const targetObjectName = 'destexampledir/exampleobject.txt';
    
    // 设置请求头信息。
    const headers = {
      // 依次填写对象标签的键(例如owner)和值(例如John)。
      'x-oss-tagging': 'owner=John&type=document',
      // 指定如何设置目标Object的对象标签。可选值包括Copy和Replace。默认值为Copy,Copy表示复制源Object的对象标签到目标Object。Replace表示忽略源Object的对象标签,直接采用请求中指定的对象标签。
      'x-oss-tagging-directive': 'Replace' 
    }
    
    async function setTag() {
      const result = await client.copy(targetObjectName, sourceObjectName, {
        headers
      });
      const tag = await client.getObjectTagging(targetObjectName)
      console.log(tag)
    }
    
    setTag()
  • 分片拷贝时添加对象标签

    以下代码用于分片拷贝1 GB以上的Object时设置对象标签。

    const OSS = require('ali-oss')
    
    const client = new OSS({
      // yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourRegion',
      // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // 填写Bucket名称,例如examplebucket。
      bucket: 'examplebucket'
    });
    
    
    // 填写源Object完整路径,例如srcexampledir/exampleobject.txt。
    const sourceObjectName = 'srcexampledir/exampleobject.txt'
    // 填写目标Object完整路径,例如destexampledir/exampleobject.txt。 
    const targetObjectName = 'destexampledir/exampleobject.txt'
    
    // 设置请求头信息。
    const headers = {
      // 依次填写对象标签的键(例如owner)和值(例如John)。
      'x-oss-tagging': 'owner=John&type=document',
    }
    
    async function setTag() {
      await client.multipartUploadCopy(targetObjectName, {
        sourceKey: sourceObjectName,
        sourceBucketName: 'examplebucket'
      }, {
        // 设置分片大小,单位为字节。除了最后一个分片没有大小限制,其他的分片最小为100 KB。
        partSize: 256 * 1024,
        headers
      });
      const tag = await client.getObjectTagging(targetObjectName)
      console.log(tag)
    }
    
    setTag()

为软链接文件设置标签

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

const OSS = require('ali-oss')

const client = new OSS({
  // yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
  region: 'yourRegion',
  // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // 填写Bucket名称,例如examplebucket。
  bucket: 'examplebucket',
});
// 填写软链接完整路径,例如shortcut/myobject.txt。
const symLink = "shortcut/myobject.txt";
// 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
const targetObjectName = 'exampledir/exampleobject.txt'
                
// 设置请求头信息。
const headers = {
  // 依次填写对象标签的键(例如owner)和值(例如John)。
  'x-oss-tagging': 'owner=John&type=document',
}

async function setTag() {
  await client.putSymlink(symLink, targetObjectName, {
    storageClass: 'IA',
    meta: {
      uid: '1',
      slus: 'test.html'
    },
    headers
  });
  const tag = await client.getObjectTagging(targetObjectName)
  console.log(tag)
}

setTag()