普通上传（Harmony SDK）--对象存储-火山引擎

文档中心

立即注册

导航

对象存储

普通上传（Harmony SDK）

最近更新时间：2025.01.08 15:40:02首次发布时间：2024.12.23 17:29:48

普通上传是指通过 putObject 方法上传单个对象(Object)，支持上传字符串（字符流）、上传 Bytes（Bytes 流）和上传本地文件。

注意事项

上传对象前，您必须具有 tos:PutObject 权限。
上传对象时，对象名必须满足一定规范，详细信息，请参见对象命名规范。
TOS 是面向海量存储设计的分布式对象存储产品，内部分区存储了对象索引数据。为横向扩展您上传对象和下载对象时的最大吞吐量和减小热点分区的概率，请您避免使用字典序递增的对象命名方式，详细信息，请参见性能优化。
如果桶中已经存在同名对象，则新对象会覆盖已有的对象。如果您的桶开启了版本控制，则会保留原有对象，并生成一个新版本号用于标识新上传的对象。

示例代码

上传字符串

您可以通过以下示例代码，使用 putObject 接口，上传字符串数据到 TOS 指定 example_dir 目录下的 example.txt 文件。

import { TosClient, TosClientError, TosServerError } from '@volcengine/tos_harmonyos_sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: "Provide your ak", 
  accessKeySecret: "Provide your sk", 
  securityToken: 'Provide your securityToken',
  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);
  }
}

async function main() {
  try {
    const bucketName = 'harmony-sdk-test-bucket';
    const objectName = 'example_dir/example.txt';
    // 上传对象
    await client.putObject({
      Bucket: bucketName,
      Key: objectName,
      // 将字符串 "Hello TOS" 上传到指定 example_dir 目录下的 example.txt
      Content: buffer.from('Hello TOS').buffer,
    });

    // 查询刚刚上传对象的大小
    const res = await client.headObject({
      Bucket: bucketName,
      Key: objectName,
    });
    // object size: 9
    console.log('object size:', res.ContentLength);
  } catch (error) {
    handleError(error);
  }
}

main();

上传本地文件流

您可以通过以下示例代码，使用 putObject 接口，将指定路径上的文件上传到 TOS 指定 example_dir 目录下的 example.txt 文件。

import { TosClient, TosClientError, TosServerError } from '@volcengine/tos_harmonyos_sdk';
import fs from 'fs';

// 创建客户端
const client = new TosClient({
  accessKeyId: "Provide your ak", 
  accessKeySecret: "Provide your sk", 
  securityToken: 'Provide your securityToken',
  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);
  }
}

async function main() {
  try {
    const bucketName = 'harmony-sdk-test-bucket';
    const objectName = 'example_dir/example.txt';
    const filePath = './example_dir/example.txt'
    const uploadFromStream = new rcp.UploadFromStream(fs.createStreamSync(filePath, 'r+'))
    // 上传对象
    await client.putObject({
      Bucket: bucketName,
      Key: objectName,
      Content: uploadFromStream,
    });

    // 查询刚刚上传对象的大小
    const res = await client.headObject({
      Bucket: bucketName,
      Key: objectName,
    });
    // object size: 9
    console.log('object size:', res.ContentLength);
  } catch (error) {
    handleError(error);
  }
}

main();

从本地文件上传

您可以通过以下示例代码，使用 putObjectFromFile 接口，通过指定文件路径将文件上传到 TOS 指定 example_dir 目录下的 example.txt 文件。

import { TosClient, TosClientError, TosServerError } from '@volcengine/tos_harmonyos_sdk';
import fs from 'fs';

// 创建客户端
const client = new TosClient({
  accessKeyId: "Provide your ak", 
  accessKeySecret: "Provide your sk", 
  securityToken: 'Provide your securityToken',
  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);
  }
}

async function main() {
  try {
    const bucketName = 'harmony-sdk-test-bucket';
    const objectName = 'example_dir/example.txt';
    // 上传对象
    await client.putObjectFromFile({
      Bucket: bucketName,
      Key: objectName,
      FilePath: './example.txt',
    });

    // 查询刚刚上传对象的大小
    const res = await client.headObject({
      Bucket: bucketName,
      Key: objectName,
    });
    // object size: 9
    console.log('object size:', res.ContentLength);
  } catch (error) {
    handleError(error);
  }
}

main();

上传时设置对象元数据信息

您可以通过以下示例代码，使用 putObject 接口，上传字符串数据到指定 example_dir 目录下的 example.txt 文件，上传时指定对象存储类型为低频存储，权限为私有同时设置上传文件元数据信息。

import { TosClient, TosClientError, TosServerError } from '@volcengine/tos_harmonyos_sdk';
import fs from 'fs';

// 创建客户端
const client = new TosClient({
  accessKeyId: "Provide your ak", 
  accessKeySecret: "Provide your sk", 
  securityToken: 'Provide your securityToken',
  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);
  }
}

async function main() {
  const meta: Record<string, string> = {};
  meta.key = 'value'
  try {
    const bucketName = 'harmony-sdk-test-bucket';
    const objectName = 'example_dir/example.txt';
    // 上传对象
    await client.putObject({
      Bucket: bucketName,
      Key: objectName,
      // 将字符串 "Hello TOS" 上传到指定 example_dir 目录下的 example.txt
      Content: buffer.from('Hello TOS').buffer,
      // 指定存储类型为低频存储
      StorageClass: StorageClassType.StorageClassIa,
      // 指定对象权限为私有
      ACL: ACLType.ACLPrivate,
      // 用户自定义元数据信息
      Meta: meta,
    });

    // 查询刚刚上传的对象
    const res = await client.headObject({
      Bucket: bucketName,
      Key: objectName,
    });
    console.log('object size:', res.ContentLength);
    console.log('storage class:',  res.StorageClass);
    console.log('x-tos-meta-key:', res.Meta?.['key']);
  } catch (error) {
    handleError(error);
  }
}