初始化
确定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验证）：
1var sdk = require('@baiducloud/sdk');
2var BosClient = sdk.BosClient;
3var config = {
4 credentials: {
5 ak: '{accessKeyId}', // STS服务器下发的临时ak
6 sk: '{secretAccessKey}' // STS服务器下发的临时sk
7 },
8 sessionToken: '{sessionToken}', // STS服务器下发的sessionToken
9 endpoint: 'https://bj.bcebos.com' //需要根据bucket所属局域进行修改
10};示例代码（不带STS验证）：
1var sdk = require('@baiducloud/sdk');
2var BosClient = sdk.BosClient;
3var config = {
4 credentials: {
5 ak: 'ak', //您的AK
6 sk: 'sk' //您的SK
7 },
8 endpoint: 'https://bj.bcebos.com' //需要根据bucket所属局域进行修改
9};-
新建一个Bucket。
Bucket是BOS上的命名空间，相当于数据的容器，可以存储若干数据实体（Object）。在您上传数据前，必须先创建一个Bucket。
示例代码：
JavaScript1let newBucketName = <BucketName>; // 新建一个Bucket，指定Bucket名称 2client.createBucket(newBucketName) 3 .then(function() { 4 // 创建完成，添加您自已的代码； 5 }) 6 .catch(function(error) { 7 // 创建失败，添加您自己的代码，处理异常 8 }); -
上传Object。
Object是BOS中最基本的数据单元，您可以把Object简单的理解为文件。对于一个简单的Object的上传，BOS为您提供了四种方式：文件形式上传、数据流形式上传、二进制串上传和字符串上传。
示例代码：
JavaScript1function done(response) { 2 // 上传完成 3} 4function fail(fail) { 5 // 上传失败 6} 7 8// 以字符串形式上传 9client.putObjectFromString(bucket, object, 'hello world') 10 .then(done) 11 .catch(fail); 12 13// 以buffer形式上传 14var buffer = new Buffer('hello world'); client.putObject(bucket, object, buffer) 15 .then(done) 16 .catch(fail); 17 18// 以文件形式上传，仅支持Node.js环境 19client.putObjectFromFile(bucket, object, <path-to-file>) 20 .then(done) 21 .catch(fail); 22 23// 以blob对象形式上传，仅支持浏览器环境 24client.putObjectFromBlob(bucket, object, <blob对象>) 25 .then(done) 26 .catch(fail); -
查看Bucket中的Object
您可以参考如下代码来查看Bucket中的Object列表：
JavaScript1client.listObjects(<bucketName>) 2 .then(function (response) { 3 var contents = response.body.contents; 4 for (var i = 0, l = contents.length; i < l; i++) { 5 console.log(contents[i].key); 6 } 7 }) 8 .catch(function (error) { 9 // 查询失败 10 });
新建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端：
1const {BosClient} = require('@baiducloud/sdk');
2
3var bosConfig = {
4 credentials: {
5 ak: '{accessKeyId}', // STS服务器下发的临时ak
6 sk: '{secretAccessKey}' // STS服务器下发的临时sk
7 },
8 sessionToken: '{sessionToken}', // STS服务器下发的sessionToken
9 endpoint: 'http://bj.bcebos.com' //需要根据bucket所属局域进行修改
10};
11
12var client = new BosClient(bosConfig);- 浏览器端：
1var bosConfig = {
2 credentials: {
3 ak: '{accessKeyId}', // STS服务器下发的临时ak
4 sk: '{secretAccessKey}' // STS服务器下发的临时sk
5 },
6 sessionToken: '{sessionToken}', // STS服务器下发的sessionToken
7 endpoint: 'http://bj.bcebos.com'
8};
9
10var client = new baidubce.sdk.BosClient(bosConfig);通过AK/SK方式访问BOS
- 确定EndPoint。EndPoint是指BOS服务在各个区域的域名地址，默认域名为北京：
http://bj.bcebos.com。 - 传入您的AK/SK。
- 将配置好的config传入BosClient。
示例代码
用户可以参考如下代码新建一个BosClient：
1let config = {
2 endpoint: 'https://bj.bcebos.com',
3 credentials: {
4 ak: <AccessKeyID>, //您的AK
5 sk: <SecretAccessKey> //您的SK
6 }
7}
8let 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，配置代码如下：
1var sdk = require('@baiducloud/sdk');
2var BosClient = sdk.BosClient;
3var config = {
4 credentials: {
5 ak: 'ak', //您的AK
6 sk: 'sk' //您的SK
7 },
8 endpoint: 'http://cdn-test.cdn.bcebos.com', // 自定义域名
9 cname_enabled: true // 使用自定义域名标示
10};配置访问域名风格
@baiducloud/sdk@1.0.1-beta.9及以上版本支持
JavaScript SDK 在1.0.1-beta.9 及以上访问域名默认使用virtual hosting风格，若希望继续使用PathStyle风格的endpoint，可以通过以下设置 pathStyleEnable 为true开启（不建议），具体域名风格规定请参考存储桶域名请求风格
1var sdk = require('@baiducloud/sdk');
2var BosClient = sdk.BosClient;
3var config = {
4 credentials: {
5 ak: 'ak', //您的AK
6 sk: 'sk' //您的SK
7 },
8 endpoint: 'https://bj.bcebos.com', // 域名
9 pathStyleEnable: true // 使用pathStyle标志
10};配置自定义签名函数
@baiducloud/sdk@1.0.1-beta.4及以上版本支持
JavaScript SDK 支持 STS（Security Token Service）临时授权的方式进行鉴权。服务端生成一组具体特定操作权限、具有一定时效性的临时AK/SK，这组临时的 AK/SK 可以暴露给浏览器端直接使用。用户只需要通过createSignature签名函数，使用临时的AK、SK和sessionToken计算出最新签名，即可访问BOS资源。关于 STS 方面的介绍请参考临时授权访问。
createSignature函数签名：
1import type {HttpClient} from '@baiducloud/sdk';
2
3// 自定义签名函数
4interface SignatureFunction {
5 (
6 /* 当前的全局鉴权密钥 */
7 credentials: {
8 ak: string;
9 sk: string
10 },
11 /* 当前HTTP请求的方法, GET,POST,PUT,DELETE,HEAD */
12 httpMethod: string,
13 /* 当前HTTP请求的path */
14 path: string,
15 /* 当前HTTP请求的查询字符串 */
16 params: Record<string, any>,
17 /* 当前HTTP请求的请求头 */
18 headers: Record<string, any>,
19 /* 当前函数的上下文，通常为HttpClient实例 */
20 context: HttpClient
21 ): Promise<string>;
22}HttpClient.updateConfigByPath可用于更新全局BceConfig，可以在SignatureFunction中通过context.updateConfigByPath发起调用。注意该函数会对当前服务实例上的config直接进行修改，不要破坏原对象引用，避免SignatureFunction失效，函数签名如下：
1interface UpdateGlobalConfigFunction {
2 (
3 /* 要设置的属性的key路径，比如"sessionToken"、"credentials.ak"等 */
4 path: string;
5 /* 更新后的值 */
6 value: string,
7 ): void;
8}操作步骤如下：
- 使用STS服务的
getSessionToken方法生成临时密钥，这一步通常在服务端完成，这里仅作为演示。 -
声明自定义签名函数
createSignature, 主要用于判断当前的密钥是否过期，如果过期，则需要再次获取最新的临时密钥和sessionToken，并更新以下信息：- 使用
context.updateConfigByPath方法将全局的ak、sk和sessionToken更新。 - 更新请求头
x-bce-security-token字段值为最新的sessionToken。 - 更新请求头
x-bce-date为最新的当前时间，因为服务端计算签名可能会带来时间差。
- 使用
1import {BosClient, STS, Auth, Q} from '@baiducloud/sdk';
2
3(async function () {
4 const ak = '<Your Access Key>';
5 const sk = '<Your Secret Access Key>';
6 const bucket = '<Your Bucket Name>';
7 // 临时密钥有效时间（秒）
8 const durationInSeconds = 3600;
9
10 /* 获取临时鉴权密钥 */
11 async function generateTempAuth() {
12 const stsClient = new STS({
13 protocol: 'https',
14 region: 'bj',
15 endpoint: 'https://sts.bj.baidubce.com',
16 credentials: {ak, sk}
17 });
18
19 const res = await stsClient.getSessionToken(durationInSeconds, {
20 accessControlList: [
21 {
22 // 限定服务范围为BOS
23 service: 'bce:bos',
24 // bucket 代表操作对象是bucket
25 // bucket/* 代表操作对象是存储桶内所有object
26 resource: [bucket, `${bucket}/*`],
27 region: 'bj',
28 effect: 'Allow',
29 permission: ['READ', 'WRITE', 'LIST']
30 }
31 ]
32 });
33
34 return res.body;
35 }
36
37 let {
38 accessKeyId,
39 secretAccessKey,
40 sessionToken,
41 expiration: expiredUTCTime
42 } = await generateTempAuth();
43
44 /**
45 * 签名计算函数，这里仅作为演示
46 */
47 async function createSignature(
48 credentials: {ak: string; sk: string},
49 httpMethod: string,
50 path: string,
51 params: Record<string, any>,
52 headers: Record<string, any>,
53 context: any
54 ) {
55 let upatedAK = credentials.ak;
56 let upatedSK = credentials.sk;
57 const now = new Date();
58
59 // 将当前的秒数向上取整，因为getSessionToken接口返回的expiration不带毫秒数
60 if (now.getUTCMilliseconds() > 0) {
61 // 如果有毫秒，则增加一秒并设置毫秒为0
62 now.setUTCSeconds(now.getUTCSeconds() + 1, 0);
63 }
64
65 // 如果当前时间大于过期时间，则重新获取临时密钥
66 if (now >= new Date(expiredUTCTime)) {
67 const tempRes = await generateTempAuth();
68
69 // 更新临时密、过期时间和sessionToken
70 upatedAK = tempRes.ak;
71 upatedSK = tempRes.sk;
72 expiredUTCTime = tempRes.expiration;
73 sessionToken = tempRes.sessionToken;
74
75 // 更新全局config信息
76 context.updateConfigByPath('credentials.ak', upatedAK);
77 context.updateConfigByPath('credentials.sk', upatedSK);
78 context.updateConfigByPath('sessionToken', sessionToken);
79 }
80
81 // 更新session Token
82 headers['x-bce-security-token'] = sessionToken;
83
84 // 更新当前时间，遵循ISO8601规范，格式如2016-04-06T08:23:49Z。
85 const revisionTimestamp = Date.now() + (context?.timeOffset || 0);
86 headers['x-bce-date'] = new Date(revisionTimestamp).toISOString().replace(/\.\d+Z$/, 'Z');
87
88 // 计算最新签名并返回，格式为string
89 return Q.fcall(function () {
90 var auth = new Auth(upatedAK, upatedSK);
91 return auth.generateAuthorization(httpMethod, path, params, headers, revisionTimestamp / 1000);
92 });
93 }
94
95 // 生成BOS SDK服务实例
96 const bosClient = new BosClient({
97 protocol: 'https',
98 endpoint: 'https://bj.bcebos.com',
99 credentials: {
100 ak: accessKeyId,
101 sk: secretAccessKey
102 },
103 sessionToken: sessionToken,
104 createSignature
105 });
106})();动态切换endpoint
@baiducloud/sdk@1.0.1-beta.9及以上版本支持
JavaScript SDK 支持 调用API时动态切换endpoint，有两种方案可供用户选择：
- 提供属性
region作为options的config参数的属性，进行endpoint切换 - 提供返回请求endpoint的自定义函数
customGenerateUrl作为options的config参数的属性，其中customGenerateUrl可使用参数bucketName、region
createSignature函数签名：
1import {BosClient} from '@baiducloud/sdk';
2
3// 生成BOS SDK服务实例
4const bosClient = new BosClient({
5 protocol: 'https',
6 endpoint: 'https://bj.bcebos.com',
7 credentials: {
8 ak: accessKeyId,
9 sk: secretAccessKey
10 },
11});
12
13// 提供region，更新endpoint
14bosClient.getBucketStorageclass(CDBucket, {config: {region: 'cd'}}).then(res => {
15 // do something
16}).catch(err => {})
17
18// 自定义生成url函数
19const customGenerateUrl = function (bucketName, region) {
20 const protocol = 'https';
21 return `${protocol}://${bucketName}.${region}.bcebos.com`;
22}
23bosClient.getBucketStorageclass(CDBucket, {config: {customGenerateUrl: customGenerateUrl}}).then(res => {
24 // do something
25}).catch(err => {})