初始化客户端（Node.js SDK）--对象存储-火山引擎

文档中心

导航

对象存储

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

最近更新时间：2024.09.05 17:26:15首次发布时间：2022.05.13 18:28:15

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

前提条件

配置长期访问凭证

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

macOS

Linux

Windows

打开终端并执行以下命令打开文件。

nano ~/.bash_profile

在文件末尾添加 AKSK 信息。

export TOS_ACCESS_KEY=AKTPYmI1Z****
export TOS_SECRET_KEY=T1dJM01UU****

保存文件并退出。
执行以下命令生效配置信息。

source ~/.bash_profile

执行以下命令验证配置信息。

echo $TOS_ACCESS_KEY
echo $TOS_SECRET_KEY

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

AKTPYmI1Z****
T1dJM01UU****

打开终端并执行以下命令打开文件。

sudo vim /etc/profile

在文件末尾添加 AKSK 信息。

export TOS_ACCESS_KEY=AKTPYmI1Z****
export TOS_SECRET_KEY=T1dJM01UU****

保存文件并退出。
执行以下命令生效配置信息。

source /etc/profile

执行以下命令验证配置信息。

echo $TOS_ACCESS_KEY
echo $TOS_SECRET_KEY

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

AKTPYmI1Z****
T1dJM01UU****

打开命令行工具，执行以下命令，添加 AKSK 信息。

set TOS_ACCESS_KEY=AKTPYmI1Z****
set TOS_SECRET_KEY=T1dJM01UU****

执行以下命令生效配置信息。

setx TOS_ACCESS_KEY "%TOS_ACCESS_KEY%"
setx TOS_SECRET_KEY "%TOS_SECRET_KEY%"

重启命令行工具，然后执行以下命令验证配置信息。

echo %TOS_ACCESS_KEY%
echo %TOS_SECRET_KEY%

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

AKTPYmI1Z****
T1dJM01UU****

创建 TosClient

使用必选参数初始化

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

说明

TOS 支持的 Region 及 Endpoint 信息，请参见地域及访问域名。
AKSK 信息可从环境变量获取，配置方式，请参见配置访问凭证。

// 导入 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	是否为自定义域名。