初始化

@Cloudbase/node-sdk 让您可以在服务端使用 Node.js 服务访问 Cloudbase 服务和资源

⚠️ 注意：从 v3 版本开始，如在初始化 init({}) 未指定 env 参数，则默认使用当前云函数环境 ID，不再使用云开发默认环境。如需要使用云开发默认环境，可以指定 init({env: tcb.SYMBOL_DEFAULT_ENV})。

选择一个提示词，开始你的 AI 原生开发之旅

安装 SDK

# npm
npm install @cloudbase/node-sdk -S

# yarn
yarn add @cloudbase/node-sdk

初始化 SDK

基本用法

import tcb from "@cloudbase/node-sdk";

// 云函数环境使用 commonjs 引入方式
// const tcb = require('@cloudbase/node-sdk')

const app = tcb.init({
  env: "your-env-id", // 替换为您的环境 ID
});

初始化参数

字段	类型	必填	说明
env	string	否	TCB 环境 ID
accessKey	string	否	Cloudbase API Key，优先级最高的鉴权方式。也可通过环境变量 CLOUDBASE_APIKEY 配置
secretId	string	否	腾讯云 API 固定密钥对 secretId，前往 腾讯云控制台/API 密钥管理 生成。也可通过环境变量 TENCENTCLOUD_SECRETID 配置
secretKey	string	否	腾讯云 API 固定密钥对 secretKey，前往 腾讯云控制台/API 密钥管理 生成。也可通过环境变量 TENCENTCLOUD_SECRETKEY 配置
sessionToken	string	否	腾讯云 API 临时密钥对 Token，通过 申请扮演角色临时访问凭证 接口获取
credentials	object	否	Cloudbase 私钥，包含 private_key 和 private_key_id 两个字符串，用于自定义登录场景签发 ticket 登录 云开发平台/身份认证/登录方式，通过自定义登录「私钥下载」获取
context	Context	否	函数型云托管入口函数 context 参数，用于云托管场景的免签名调用
timeout	number	否	调用接口的超时时间（ms），默认为 15000ms，即 15s
proxy	string	否	调用接口时使用的 http 代理 url
version	string	否	版本号，依赖项目的版本号

登录鉴权

node-sdk 使用不同环境下的鉴权方式如下：

SDK 初始化时可按以下方式选择鉴权方式（但只需选择其中一种）：

鉴权方式	说明
使用默认鉴权方式	用户在 init 中无需传入，自动从环境变量读取 secretId 和 secretKey，使用管理员角色身份进行访问
使用客户端 Publishable Key（显式配置）	用户在 init 中显式传入 Publishable Key，使用匿名角色身份进行访问
使用服务端 API Key	用户在 init 中无需传入，自动从环境变量读取 CLOUDBASE_APIKEY，将服务端 API Key 配置到环境变量 CLOUDBASE_APIKEY 中
secretId + secretKey（显式配置）	用户在 init 中显式传入 secretId 和 secretKey，使用管理员角色身份进行访问
sessionToken（显式配置）	用户在 init 中显式传入 sessionToken，使用扮演角色临时访问凭证
context.extendedContext	云托管环境自动从 context 中获取临时密钥和环境 ID

鉴权示例

使用默认鉴权

用户在 init 中无需传入，自动从环境变量读取 secretId 和 secretKey

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({
  env: "your-env-id",
});

使用 Publishable Key

Publishable Key 详细介绍请 参考文档说明 。

• 用户权限：匿名用户权限
• 有效期：长期有效
• 获取方式：通过云开发平台/ApiKey 管理获取

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({
  env: "your-env-id",
  accessKey: "your-publishable-key",
});

使用 API Key

可以通过环境变量 CLOUDBASE_APIKEY 配置，在云函数中开启 API key设置，添加 CLOUDBASE_APIKEY。

import tcb from "@cloudbase/node-sdk";

// 无需显式传入 accessKey，SDK 自动从环境变量读取
const app = tcb.init({
  env: "your-env-id",
});

使用 secretId 和 secretKey

前往 腾讯云控制台/API 密钥管理 生成 secretKey、secretId

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({
  env: "your-env-id",
  secretId: "your-secretId",
  secretKey: "your-secretKey",
});

使用 sessionToken

通过 申请扮演角色临时访问凭证 接口获取 Token

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({
  env: "your-env-id",
  sessionToken: "your-sessionToken",
});

场景示例

云函数环境

在云函数环境中，SDK 会自动从环境变量中读取鉴权信息，无需手动配置鉴权参数。

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({
  env: tcb.SYMBOL_DEFAULT_ENV, // 使用当前云函数默认环境 ID
});

云托管环境

在函数型云托管环境中，通过传入 context 参数实现免签名调用。

💡 注意：如果传入了 context 参数但没有 env 参数，则会使用 context 中的 envID 参数作为环境 ID。

import tcb from "@cloudbase/node-sdk";

exports.main = async (event, context) => {
  const app = tcb.init({
    context,
  });
};