You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /
  • 对象存储

初始化客户端（Node.js SDK）

最近更新时间：2024.02.04 18:30:56

首次发布时间：2022.05.13 18:28:15

我的收藏

初始化 TOSClient 实例之后，您才可以向 TOS 服务发送 HTTP/HTTPS 请求。本文介绍 Node.js SDK 的初始化方式。
TOS Node.js 客户端提供了一系列接口用来与 TOS 服务进行交互，用来管理桶和对象等 TOS 上的资源。初始化客户端时，需要带上 AccessKey ID、AccessKey Secret 和 Region 等信息。在初始化时，您可以设置建立连接超时时间、超时重试次数和最大空闲连接数量等可选参数。

前提条件

配置长期访问凭证

初始化 SDK 前，您需要先配置长期访问凭证。本章节介绍不同操作系统下配置长期访问凭证的操作步骤。

  1. 打开终端并执行以下命令打开文件。
nano ~/.bash_profile
  1. 在文件末尾添加 AKSK 信息。
export TOS_ACCESS_KEY=AKTPYmI1Z****
export TOS_SECRET_KEY=T1dJM01UU****
  1. 保存文件并退出。
  2. 执行以下命令生效配置信息。
source ~/.bash_profile
  1. 执行以下命令验证配置信息。
echo $TOS_ACCESS_KEY
echo $TOS_SECRET_KEY

如果配置成功，则返回如下示例：

AKTPYmI1Z****
T1dJM01UU****

创建 TosClient

使用必选参数初始化

以下代码展示如何使用 TOS 域名等必选参数初始化 TosClient，包括 AccessKey ID、AccessKey Secret、Endpoint 和 Region。

说明

// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { TosClient } 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", // 填写域名地址
});

使用可选参数初始化

TOS Node.js SDK 提供了多个可选参数来自定义配置 TosClient，例如配置 STS，HTTP 请求超时时间，请求重试策略等。
以下代码展示如何自定义配置 TosClient 的 HTTP 连接超时时间，具体的配置场景，请参见下文的配置超时机制。

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

const connectionTimeout = 10000;

// 创建客户端
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", // 填写域名地址
  connectionTimeout,
});

console.log(client);

常见配置场景

配置超时机制

您可以在初始化 TosClient 时，通过添加可选参数配置网络请求的超时时间。目前 TOS Node.js SDK 提供了以下超时参数用于 HTTP 请求的超时配置：

  • requestTimeout：HTTP 请求超时时间，单位毫秒，默认值为 120000，即 120 秒。
  • connectionTimeout：建立 HTTP 连接的超时时间，单位毫秒，默认值为 10000，即 10 秒。
    以下代码展示如何在初始化 TosClient 时配置超时时间。
// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { TosClient } from '@volcengine/tos-sdk';

const connectionTimeout = 10000;
const requestTimeout = 120000;

// 创建客户端
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", // 填写域名地址
  connectionTimeout,
  requestTimeout,
});

console.log(client);

配置重试策略

网络波动或短期 TOS 服务异常（例如返回 500 HTTP 状态码）等场景会导致请求 TOS 服务失败。针对此问题，SDK 内部提供了重试机制，根据设置的重试次数进行指数退避重试，默认重试次数为 3 次。
幂等操作的接口在失败后会使用指数退避策略进行重试，非幂接口则直接抛出对应异常。您可以在初始化 TosClient 时，添加可选参数配置重试次数。
以下代码展示如何设置 SDK 的重试次数。

// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { TosClient } from '@volcengine/tos-sdk';
// 设置最大重试次数为 3 次，可根据实际需要调整
const maxRetryCount = 3;

// 创建客户端
const client = new TOS({
  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", // 填写域名地址
  maxRetryCount,
});

配置数据校验

TOS SDK 在上传或下载对象时默认关闭 CRC 数据校验，确保数据传输过程中的完整性。
您可以使用以下代码，开启 CRC 数据校验。

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

// 设置开启 CRC 数据校验,默认为 false
const enableCRC = true;

// 创建客户端
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", // 填写域名地址
  enableCRC,
});

初始化参数列表

参数

参数类型

是否必选

示例值

说明

accessKeyId

string

必选

AKTPYmI1Z****

Access Key ID，密钥 ID，默认值 null。

accessKeySecret

string

必选

T1dJM01UU****==

AccessKey Secret，私有访问密钥，默认值 null。

region

string

必选

cn-beijing

TOS 服务端所在地域，默认值 null。

endpoint

string

可选，为空时由 region 参数决定

tos-cn-beijing.volces.com

访问域名，为空时由 region 参数决定。

stsToken

string

可选

STSkeyJBY2NvdW50SW************

临时访问凭证中的安全令牌，默认值 null。

enableVerifySSL

boolean

可选

true

配置是否开启 SSL 证书校验，默认值为 False。

autoRecognizeContentType

boolean

可选

true

自动识别 MIME 类型，默认开启。

requestTimeout

number

可选

120000

HTTP 请求超时时间，单位毫秒，默认值为 120000。

connectionTimeout

number

可选

10000

建立连接超时时间，单位毫秒，默认值为 10000。

idleConnectionTime

number

可选

60000

连接池中空闲 HTTP 连接时间超过此参数的设定值，则关闭 HTTP 连接，单位：毫秒，默认值为 60000。

maxConnections

number

可选

1024

HTTP 连接池最大连接数，默认值为 1024。

maxRetryCount

number

可选

3

请求失败后的最大重试次数，默认值为 3。

proxyHost

string

可选

localhost

代理服务器的主机地址，当前只支持 HTTP 协议，默认值 null。

proxyPort

number

可选

8080

代理服务器的端口号。

enableCRC

boolean

可选

false

是否开启 CRC 校验，默认值 false。

isCustomDomain

boolean

可选

false

是否为自定义域名。