初始化

更新时间：2024-10-31

确定Endpoint

在确认您使用SDK时配置的Endpoint时，可先阅读开发人员指南中关于BOS访问域名的部分，理解Endpoint相关的概念。百度智能云目前开放了多区域支持，请参考区域选择说明。

region与endpoint参考如下链接

https://cloud.baidu.com/doc/BOS/s/akrqd2wcx

常见示例如下:

区域	访问EndPoint	支持协议
bj	bj.bcebos.com	HTTP,HTTPS
bd	bd.bcebos.com	HTTP,HTTPS
su	su.bcebos.com	HTTP,HTTPS
gz	gz.bcebos.com	HTTP,HTTPS
cd	cd.bcebos.com	HTTP,HTTPS
hkg	hkg.bcebos.com	HTTP,HTTPS
fwh	fwh.bcebos.com	HTTP,HTTPS
fsh	fsh.bcebos.com	HTTP,HTTPS

Node.js端快速入门

初始化一个BosClient。

BosClient是与BOS服务交互的客户端，BOS JavaScript SDK的BOS操作都是通过BosClient完成的。

说明：考虑到安全风险，推荐您初始化一个带有STS验证的BosClient。

示例代码（带有STS验证）：

var sdk = require('@baiducloud/sdk');
var BosClient = sdk.BosClient;
var config = {
 credentials: {
     ak: '{accessKeyId}',    // STS服务器下发的临时ak
     sk: '{secretAccessKey}' // STS服务器下发的临时sk
 },
 sessionToken: '{sessionToken}',     // STS服务器下发的sessionToken
 endpoint: 'https://bj.bcebos.com'  //需要根据bucket所属局域进行修改
};

示例代码（不带STS验证）：

var sdk = require('@baiducloud/sdk');
var BosClient = sdk.BosClient;
var config = {
 credentials: {
      ak: 'ak',  //您的AK
      sk: 'sk'   //您的SK
   },
 endpoint: 'https://bj.bcebos.com'  //需要根据bucket所属局域进行修改
};

新建一个Bucket。

Bucket是BOS上的命名空间，相当于数据的容器，可以存储若干数据实体（Object）。在您上传数据前，必须先创建一个Bucket。

示例代码：

let newBucketName = <BucketName>;    // 新建一个Bucket，指定Bucket名称
client.createBucket(newBucketName)
  .then(function() {
         // 创建完成，添加您自已的代码；
   })
   .catch(function(error) {
        // 创建失败，添加您自己的代码，处理异常
   });

上传Object。

Object是BOS中最基本的数据单元，您可以把Object简单的理解为文件。对于一个简单的Object的上传，BOS为您提供了四种方式：文件形式上传、数据流形式上传、二进制串上传和字符串上传。

示例代码：

function done(response) {
  // 上传完成
}
function fail(fail) {
  // 上传失败
}

// 以字符串形式上传
client.putObjectFromString(bucket, object, 'hello world')
  .then(done)
  .catch(fail);

// 以buffer形式上传
var buffer = new Buffer('hello world'); client.putObject(bucket, object, buffer)
  .then(done)
  .catch(fail);

// 以文件形式上传，仅支持Node.js环境
client.putObjectFromFile(bucket, object, <path-to-file>)
  .then(done)
  .catch(fail);

// 以blob对象形式上传，仅支持浏览器环境
client.putObjectFromBlob(bucket, object, <blob对象>)
  .then(done)
  .catch(fail);

查看Bucket中的Object

您可以参考如下代码来查看Bucket中的Object列表：

client.listObjects(<bucketName>)
  .then(function (response) {
      var contents = response.body.contents;
      for (var i = 0, l = contents.length; i < l; i++) {
          console.log(contents[i].key);
      }
  })
  .catch(function (error) {
      // 查询失败
  });

新建BosClient

BosClient是BOS服务的JavaScript客户端，为开发者与BOS服务进行交互提供了一系列的方法。在使用SDK发起对BOS的请求前，您需要初始化一个BosClient实例，并对它进行一些必要设置。

浏览器端： let BosClient = baidubce.sdk.BosClient
Node.js端： import {BosClient} from '@baiducloud/sdk'

通过STS方式访问BOS

说明：移动终端是一个不受信任的环境，把 AccessKeyId 和 SecretAccessKey 直接保存在终端用来加签请求，存在极高的风险。故推荐您使用STS鉴权模式，通过STS方式访问BOS。

BOS可以通过STS机制实现第三方的临时授权访问。STS（Security Token Service）是百度智能云提供的临时授权服务，详情可参见百度智能云STS使用介绍。通过STS，您可以为第三方用户颁发一个自定义时效和权限的访问凭证。第三方用户可以使用该访问凭证直接调用百度智能云的API或SDK访问百度智能云资源。

通过STS方式访问BOS，用户先通过sts-client申请一套AK、SK和token，然后将该套参数配置到BosClient中，用户可以参考如下代码新建一个BosClient：

Node.js端：

const {BosClient} = require('@baiducloud/sdk');

var bosConfig = {
    credentials: {
        ak: '{accessKeyId}', // STS服务器下发的临时ak
        sk: '{secretAccessKey}' // STS服务器下发的临时sk
    },
    sessionToken: '{sessionToken}',  // STS服务器下发的sessionToken
    endpoint: 'http://bj.bcebos.com' //需要根据bucket所属局域进行修改
};

var client = new BosClient(bosConfig);

浏览器端：

var bosConfig = {
    credentials: {
        ak: '{accessKeyId}', // STS服务器下发的临时ak
        sk: '{secretAccessKey}' // STS服务器下发的临时sk
    },
    sessionToken: '{sessionToken}',  // STS服务器下发的sessionToken
    endpoint: 'http://bj.bcebos.com'
};

var client = new baidubce.sdk.BosClient(bosConfig);

通过AK/SK方式访问BOS

确定EndPoint。EndPoint是指BOS服务在各个区域的域名地址，默认域名为北京：http://bj.bcebos.com。
传入您的AK/SK。
将配置好的config传入BosClient。

示例代码

用户可以参考如下代码新建一个BosClient：

let config = {
    endpoint: 'https://bj.bcebos.com',
    credentials: {
        ak: <AccessKeyID>,           //您的AK
        sk: <SecretAccessKey>       //您的SK
    }
}
let client = new BosClient(config);

注意： EndPoint参数即BOS访问域名，只能用指定的包含区域的域名来进行定义，不指定时默认为北京区域http://bj.bcebos.com。BOS访问域名支持HTTP和HTTPS两种调用方式，为了提升数据的安全性，建议使用https://bj.bcebos.com。百度智能云目前开放了多区域支持，请参考区域选择说明。

配置自定义域名访问BOS

使用自定义域名

如果希望使用自定义域名作为访问BOS的endpoint，在控制台将自定义域名和BOS某个bucket绑定之后，配置endpoint为自定义域名并打开cname_enabled开关，例如cdn-test.cdn.bcebos.com，配置代码如下：

var sdk = require('@baiducloud/sdk');
var BosClient = sdk.BosClient;
var config = {
 credentials: {
      ak: 'ak',       //您的AK
      sk: 'sk'        //您的SK
   },
 endpoint: 'http://cdn-test.cdn.bcebos.com', // 自定义域名
 cname_enabled: true // 使用自定义域名标示
};

配置访问域名风格

@baiducloud/sdk@1.0.1-beta.9及以上版本支持

JavaScript SDK 在1.0.1-beta.9 及以上访问域名默认使用virtual hosting风格，若希望继续使用PathStyle风格的endpoint，可以通过以下设置 pathStyleEnable 为true开启（不建议），具体域名风格规定请参考存储桶域名请求风格

var sdk = require('@baiducloud/sdk');
var BosClient = sdk.BosClient;
var config = {
 credentials: {
      ak: 'ak',       //您的AK
      sk: 'sk'        //您的SK
   },
 endpoint: 'https://bj.bcebos.com', // 域名
 pathStyleEnable: true // 使用pathStyle标志
};

配置自定义签名函数

@baiducloud/sdk@1.0.1-beta.4及以上版本支持

JavaScript SDK 支持 STS（Security Token Service）临时授权的方式进行鉴权。服务端生成一组具体特定操作权限、具有一定时效性的临时AK/SK，这组临时的 AK/SK 可以暴露给浏览器端直接使用。用户只需要通过createSignature签名函数，使用临时的AK、SK和sessionToken计算出最新签名，即可访问BOS资源。关于 STS 方面的介绍请参考临时授权访问。

createSignature函数签名：

import type {HttpClient} from '@baiducloud/sdk';

// 自定义签名函数
interface SignatureFunction {
  (
    /* 当前的全局鉴权密钥 */
    credentials: {
        ak: string;
        sk: string
    },
    /* 当前HTTP请求的方法, GET,POST,PUT,DELETE,HEAD */
    httpMethod: string,
    /* 当前HTTP请求的path */
    path: string,
    /* 当前HTTP请求的查询字符串 */
    params: Record<string, any>,
    /* 当前HTTP请求的请求头 */
    headers: Record<string, any>,
    /* 当前函数的上下文，通常为HttpClient实例 */
    context: HttpClient
  ): Promise<string>;
}

HttpClient.updateConfigByPath可用于更新全局BceConfig，可以在SignatureFunction中通过context.updateConfigByPath发起调用。注意该函数会对当前服务实例上的config直接进行修改，不要破坏原对象引用，避免SignatureFunction失效，函数签名如下：

interface UpdateGlobalConfigFunction {
  (
    /* 要设置的属性的key路径，比如"sessionToken"、"credentials.ak"等 */
    path: string;
    /* 更新后的值 */
    value: string,
  ): void;
}

操作步骤如下：

使用STS服务的getSessionToken方法生成临时密钥，这一步通常在服务端完成，这里仅作为演示。
声明自定义签名函数createSignature, 主要用于判断当前的密钥是否过期，如果过期，则需要再次获取最新的临时密钥和sessionToken，并更新以下信息：
- 使用context.updateConfigByPath方法将全局的ak、sk和sessionToken更新。
- 更新请求头x-bce-security-token字段值为最新的sessionToken。
- 更新请求头x-bce-date为最新的当前时间，因为服务端计算签名可能会带来时间差。

import {BosClient, STS, Auth, Q} from '@baiducloud/sdk';

(async function () {
    const ak = '<Your Access Key>';
    const sk = '<Your Secret Access Key>';
    const bucket = '<Your Bucket Name>';
    // 临时密钥有效时间（秒）
    const durationInSeconds = 3600;

    /* 获取临时鉴权密钥 */
    async function generateTempAuth() {
        const stsClient = new STS({
            protocol: 'https',
            region: 'bj',
            endpoint: 'https://sts.bj.baidubce.com',
            credentials: {ak, sk}
        });

        const res = await stsClient.getSessionToken(durationInSeconds, {
            accessControlList: [
                {
                    // 限定服务范围为BOS
                    service: 'bce:bos',
                    // bucket 代表操作对象是bucket
                    // bucket/* 代表操作对象是存储桶内所有object
                    resource: [bucket, `${bucket}/*`],
                    region: 'bj',
                    effect: 'Allow',
                    permission: ['READ', 'WRITE', 'LIST']
                }
          ]
        });

        return res.body;
    }

    let {
        accessKeyId,
        secretAccessKey,
        sessionToken,
        expiration: expiredUTCTime
    } = await generateTempAuth();

    /**
     * 签名计算函数，这里仅作为演示
     */
    async function createSignature(
        credentials: {ak: string; sk: string},
        httpMethod: string,
        path: string,
        params: Record<string, any>,
        headers: Record<string, any>,
        context: any
    ) {
        let upatedAK = credentials.ak;
        let upatedSK = credentials.sk;
        const now = new Date();

        // 将当前的秒数向上取整，因为getSessionToken接口返回的expiration不带毫秒数
        if (now.getUTCMilliseconds() > 0) {
            // 如果有毫秒，则增加一秒并设置毫秒为0
            now.setUTCSeconds(now.getUTCSeconds() + 1, 0);
        }

        // 如果当前时间大于过期时间，则重新获取临时密钥
        if (now >= new Date(expiredUTCTime)) {
            const tempRes = await generateTempAuth();

            // 更新临时密、过期时间和sessionToken
            upatedAK = tempRes.ak;
            upatedSK = tempRes.sk;
            expiredUTCTime = tempRes.expiration;
            sessionToken = tempRes.sessionToken;

            // 更新全局config信息
            context.updateConfigByPath('credentials.ak', upatedAK);
            context.updateConfigByPath('credentials.sk', upatedSK);
            context.updateConfigByPath('sessionToken', sessionToken);
        }

        // 更新session Token
        headers['x-bce-security-token'] = sessionToken;

        // 更新当前时间，遵循ISO8601规范，格式如2016-04-06T08:23:49Z。
        const revisionTimestamp = Date.now() + (context?.timeOffset || 0);
        headers['x-bce-date'] = new Date(revisionTimestamp).toISOString().replace(/\.\d+Z$/, 'Z');

        // 计算最新签名并返回，格式为string
        return Q.fcall(function () {
            var auth = new Auth(upatedAK, upatedSK);
            return auth.generateAuthorization(httpMethod, path, params, headers, revisionTimestamp / 1000);
        });
    }

    // 生成BOS SDK服务实例
    const bosClient = new BosClient({
        protocol: 'https',
        endpoint: 'https://bj.bcebos.com',
        credentials: {
          ak: accessKeyId,
          sk: secretAccessKey
        },
        sessionToken: sessionToken,
        createSignature
    });
})();

动态切换endpoint

@baiducloud/sdk@1.0.1-beta.9及以上版本支持

JavaScript SDK 支持调用API时动态切换endpoint，有两种方案可供用户选择：

提供属性region作为options的config参数的属性，进行endpoint切换
提供返回请求endpoint的自定义函数customGenerateUrl作为options的config参数的属性，其中customGenerateUrl可使用参数bucketName、region