AI 助理
备案控制台
文档
输入文档关键字查找
首页 对象存储 开发参考 SDK参考 Node.js 对象/文件 管理文件 对象标签 设置对象标签

Node.js设置对象标签

更新时间：
产品详情
相关技术圈
我的收藏

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

注意事项

  • 在配置对象标签之前，请确保您已了解该功能。详情请参见对象标签。

  • 本文以华东1（杭州）外网Endpoint为例。如果您希望通过与OSS同地域的其他阿里云产品访问OSS，请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系，请参见OSS访问域名、数据中心、开放端口。

  • 本文以从环境变量读取访问凭证为例。如何配置访问凭证，请参见Java配置访问凭证。

  • 本文以OSS域名新建OSSClient为例。如果您希望通过自定义域名、STS等方式新建OSSClient，请参见新建OSSClient。

  • 仅Java SDK 3.5.0及以上版本支持设置对象标签。

  • 要设置对象标签，您必须具有oss:PutObjectTagging权限。具体操作，请参见为RAM用户授权自定义的权限策略。

上传Object时添加对象标签

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

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

    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
})

  • 分片上传时添加对象标签

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

    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', 
}


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',
  // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量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',
}


// 追加上传文件，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',
  // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量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'
// 设置断点信息。
letcheckpoint;

// 设置请求头信息。
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',
  // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量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'
// 依次填写对象标签的键（例如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',
  // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量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'
// 依次填写对象标签的键（例如owner）和值（例如John）。
const tag = { owner: 'John', type: 'document' };
// 填写Object的版本ID。
constversionId='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',
  // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量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名称。例如srcexampledir/exampleobject.txt。
const sourceObjectName = 'srcexampledir/exampleobject.txt';
// 填写目标Object完整路径，Object完整路径中不能包含Bucket名称。例如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',
  // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量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名称。例如srcexampledir/exampleobject.txt。
const sourceObjectName = 'srcexampledir/exampleobject.txt'
// 填写目标Object完整路径，Object完整路径中不能包含Bucket名称。例如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',
  // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量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'
});

// 填写软链接完整路径，例如shortcut/myobject.txt。
const symLink = "shortcut/myobject.txt";
// 填写Object完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
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()

相关文档

  • 关于设置对象标签的完整示例代码，请参见GitHub示例。

  • 关于设置对象标签的API接口说明，请参见PutObjectTagging。

上一篇：对象标签下一篇：获取对象标签
文档推荐