You need to enable JavaScript to run this app.
导航
管理对象元信息(Node.js SDK)
最近更新时间:2024.02.04 18:30:57首次发布时间:2022.05.13 18:28:15

对象元信息是对象的属性描述,包括 HTTP 标准属性(HTTP Header)和用户自定义元数据(User Meta)两种。

注意事项

  • 只有对象拥有者,具备设置对象元数据权限。
  • 设置用户自定义元数据时,英文字母自定义元数据 Key 只支持小写,不支持空格等特殊字符。

参数说明

通过 TOS Node.js SDK 可以添加和修改已经上传对象的元数据信息。TOS 支持携带以下 7 个请求头来修改对象元数据,在下载对象或者 HEAD 对象时,这些值会设置到 HTTP 头域中返回给客户端。请求头如下所示:

名称

说明

Content-Type

对象类型。

Cache-Control

指定该对象被下载时网页的缓存行为。

Expires

RFC2616 中定义的缓存失效时间。

Content-Disposition

对象被下载时的名称。

Content-Encoding

对象被下载时的内容编码类型。

Content-Language

对象被下载时的内容语言格式。

x-tos-meta-*

使用 SDK 设置 meta 字段时设置的元数据信息。当查询此对象时,元数据将会在返回消息的 Header 中。

示例代码

普通上传时设置元数据信息

// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { TosClient, TosClientError, TosServerError } from '@volcengine/tos-sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: process.env['TOS_ACCESS_KEY'],
  accessKeySecret: process.env['TOS_SECRET_KEY'],
  region: "Provide your region", // 填写 Bucket 所在地域。以华北2(北京)为例,则 "Provide your region" 填写为 cn-beijing。
  endpoint: "Provide your endpoint", // 填写域名地址
});

function handleError(error) {
  if (error instanceof TosClientError) {
    console.log('Client Err Msg:', error.message);
    console.log('Client Err Stack:', error.stack);
  } else if (error instanceof TosServerError) {
    console.log('Request ID:', error.requestId);
    console.log('Response Status Code:', error.statusCode);
    console.log('Response Header:', error.headers);
    console.log('Response Err Code:', error.code);
    console.log('Response Err Msg:', error.message);
  } else {
    console.log('unexpected exception, message: ', error);
  }
}

const bucketName = 'node-sdk-test-bucket';
// 将文件上传到 example_dir 目录下的 example.txt 文件
const objectKey = 'example_dir/example.txt';
async function main() {
  try {
    // 将字符串 "Hello TOS" 上传到指定 example_dir 目录下的 example.txt
    const body = Buffer.from('Hello TOS');
    const { requestId } = await client.putObject({
      bucket: bucketName,
      key: objectKey,
      body,
      // 用户自定义元数据信息
      meta: {
        key: 'value',
      },
      // 设置对象类型
      contentType: 'text/html',
      // 设置对象下载时内容语言格式
      contentLanguage: 'zh-cn',
      // 设置缓存策略
      cacheControl: 'no-store',
      // 设置缓存过期时间
      expires: new Date('2028/01/01'),
      // 设置下载内容下载时的名称
      contentDisposition: 'example.png',
      // 设置下载时编码类型
      contentEncoding: 'deflate',
    });
    console.log('putObject Request ID:', requestId);
  } catch (error) {
    handleError(error);
  }
}

main();

分片上传设置元数据信息

// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { TosClient, TosClientError, TosServerError } from '@volcengine/tos-sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: process.env['TOS_ACCESS_KEY'],
  accessKeySecret: process.env['TOS_SECRET_KEY'],
  region: "Provide your region", // 填写 Bucket 所在地域。以华北2(北京)为例,则 "Provide your region" 填写为 cn-beijing。
  endpoint: "Provide your endpoint", // 填写域名地址
});

function handleError(error) {
  if (error instanceof TosClientError) {
    console.log('Client Err Msg:', error.message);
    console.log('Client Err Stack:', error.stack);
  } else if (error instanceof TosServerError) {
    console.log('Request ID:', error.requestId);
    console.log('Response Status Code:', error.statusCode);
    console.log('Response Header:', error.headers);
    console.log('Response Err Code:', error.code);
    console.log('Response Err Msg:', error.message);
  } else {
    console.log('unexpected exception, message: ', error);
  }
}

const bucketName = 'node-sdk-test-bucket';
// 将文件上传到 example_dir 目录下的 example.txt 文件
const objectKey = 'example_dir/example.txt';
async function main() {
  try {
    // 将字符串 "Hello TOS" 上传到指定 example_dir 目录下的 example.txt
    const body = Buffer.from('Hello TOS');
    const { data, requestId } = await client.createMultipartUpload({
      bucket: bucketName,
      key: objectKey,
      body,
      // 用户自定义元数据信息
      meta: {
        key: 'value',
      },
      // 设置对象类型
      contentType: 'text/html',
      // 设置对象下载时内容语言格式
      contentLanguage: 'zh-cn',
      // 设置缓存策略
      cacheControl: 'no-store',
      // 设置缓存过期时间
      expires: new Date('2028/01/01'),
      // 设置下载内容下载时的名称
      contentDisposition: 'example.png',
      // 设置下载时编码类型
      contentEncoding: 'deflate',
    });
    const uploadId = data.UploadId;
    console.log('createMultipartUpload Request ID:', requestId);
    console.log('dcreateMultipartUpload UploadId:', uploadId);

    // 上传分片数据
    const { data: part, requestId: uploadPartRequestId } = await client.uploadPart({
      bucket: bucketName,
      key: objectKey,
      uploadId,
      partNumber: 1,
      body: Buffer.from('your body data'),
    });
    console.log('uploadPart Request ID:', uploadPartRequestId);

    // 完成上传
    const { requestId: completeRequestId } = await client.completeMultipartUpload({
      bucket: bucketName,
      key: objectKey,
      uploadId,
      parts: [{ partNumber: 1, eTag: part.ETag }],
    });
    console.log('completeMultipartUpload Request ID:', completeRequestId);
  } catch (error) {
    handleError(error);
  }
}

main();

通过 SetObjectMeta 设置对象元数据信息

// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { TosClient, TosClientError, TosServerError } from '@volcengine/tos-sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: process.env['TOS_ACCESS_KEY'],
  accessKeySecret: process.env['TOS_SECRET_KEY'],
  region: "Provide your region", // 填写 Bucket 所在地域。以华北2(北京)为例,则 "Provide your region" 填写为 cn-beijing。
  endpoint: "Provide your endpoint", // 填写域名地址
});

function handleError(error) {
  if (error instanceof TosClientError) {
    console.log('Client Err Msg:', error.message);
    console.log('Client Err Stack:', error.stack);
  } else if (error instanceof TosServerError) {
    console.log('Request ID:', error.requestId);
    console.log('Response Status Code:', error.statusCode);
    console.log('Response Header:', error.headers);
    console.log('Response Err Code:', error.code);
    console.log('Response Err Msg:', error.message);
  } else {
    console.log('unexpected exception, message: ', error);
  }
}

const bucketName = 'node-sdk-test-bucket';
// 存储桶中的对象名
const objectKey = 'example_dir/example.txt';
async function main() {
  try {
    const { requestId } = await client.setObjectMeta({
      bucket: bucketName,
      key: objectKey,
      // 用户自定义元数据信息
      meta: {
        key: 'value',
      },
      // 设置对象类型
      contentType: 'text/html',
      // 设置对象下载时内容语言格式
      contentLanguage: 'zh-cn',
      // 设置缓存策略
      cacheControl: 'no-store',
      // 设置缓存过期时间
      expires: new Date('2028/01/01'),
      // 设置下载内容下载时的名称
      contentDisposition: 'example.png',
      // 设置下载时编码类型
      contentEncoding: 'deflate',
    });
    console.log('setObjectMeta Request ID:', requestId);
  } catch (error) {
    handleError(error);
  }
}

main();

查询对象元数据信息(判断对象是否存在)

注意

获取对象元数据前,您必须具有 tos:GetObject 权限,具体操作请参见 IAM 策略概述

// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { TosClient, TosClientError, TosServerError } from '@volcengine/tos-sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: process.env['TOS_ACCESS_KEY'],
  accessKeySecret: process.env['TOS_SECRET_KEY'],
  region: "Provide your region", // 填写 Bucket 所在地域。以华北2(北京)为例,则 "Provide your region" 填写为 cn-beijing。
  endpoint: "Provide your endpoint", // 填写域名地址
});

function handleError(error) {
  if (error instanceof TosClientError) {
    console.log('Client Err Msg:', error.message);
    console.log('Client Err Stack:', error.stack);
  } else if (error instanceof TosServerError) {
    console.log('Request ID:', error.requestId);
    console.log('Response Status Code:', error.statusCode);
    console.log('Response Header:', error.headers);
    console.log('Response Err Code:', error.code);
    console.log('Response Err Msg:', error.message);
  } else {
    console.log('unexpected exception, message: ', error);
  }
}

const bucketName = 'node-sdk-test-bucket';
// 存储桶中的对象名
const objectKey = 'example_dir/example.txt';
async function main() {
  try {
    const { headers, requestId } = await client.headObject({
      bucket: bucketName,
      key: objectKey,
    });
    console.log('headObject Request ID:', requestId);
    // 查看内容语言格式
    console.log('headObject Response ContentLanguage:', headers['content-language']);
    // 查看下载时的名称
    console.log('headObject Response ContentDisposition:', headers['content-disposition']);
    // 查看编码类型
    console.log('headObject Response ContentEncoding:', headers['content-encoding']);
    // 查看缓存策略
    console.log('headObject Response CacheControl:', headers['cache-control']);
    // 查看对象类型
    console.log('headObject Response ContentType:', headers['content-type']);
    // 查看缓存过期时间
    console.log('headObject Response Expires:', headers['expires']);
  } catch (error) {
    handleError(error);
  }
}

main();

相关文档

关于设置对象元数据的 API 文档,请参见 SetObjectMeta