初始化

确认Endpoint

• 在确认您使用SDK时配置的Endpoint时，可先阅读开发人员指南中关于BOS访问域名的部分，理解Endpoint相关的概念。
• 百度智能云目前开放了多区域支持，请参考区域选择说明。
• 目前支持 “华北-北京”、“华北-保定”、“华东-苏州”、“华南-广州”、“西南-成都”、“中国香港”、“华中-武汉”和“华东-上海”。北京区域：http://bj.bcebos.com，保定区域:http://bd.bcebos.com,苏州区域:http://su.bcebos.com,广州区域:http://gz.bcebos.com,成都区域:http://cd.bcebos.com,香港区域:http://hkg.bcebos.com,武汉区域：http://fwh.bcebos.com,上海区域：http://fsh.bcebos.com。

对应信息为：

1访问区域 | 对应Endpoint
2---|---
3BJ | bj.bcebos.com
4BD | bd.bcebos.com
5SU | su.bcebos.com
6GZ | gz.bcebos.com
7CD | cd.bcebos.com
8HKG| hkg.bcebos.com
9FWH | fwh.bcebos.com
10FSH | fsh.bcebos.com

获取密钥

要使用百度智能云BOS，您需要拥有一个有效的 AK（Access Key ID）和SK(Secret Access Key)用来进行签名认证。AK/SK是由系统分配给用户的，均为字符串，用于标识用户，为访问BOS做签名验证。

可以通过如下步骤获得并了解您的AK/SK信息：

1. 注册百度智能云账号
2. 创建AK/SK

新建BosClient

BosClient是BOS服务的客户端，为开发者与BOS服务进行交互提供了一系列的方法。

使用AK/SK新建BosClient

通过AK/SK方式访问BOS，用户可以参考如下代码新建一个BosClient：

1#使用Ruby SDK，引入bos_client和Baidubce模块
2require 'baidubce/services/bos/bos_client'
3include Baidubce
4
5#配置client参数
6credentials = Auth::BceCredentials.new(
7    "accessKeyId",
8    "secretAccessKey"
9)
10
11conf = BceClientConfiguration.new(
12    credentials,
13    "ENDPOINT"
14)
15#新建BosClient
16client = Services::BosClient.new(conf)

注意：

1. 在上面代码中，accessKeyId对应控制台中的“Access Key ID”，secretAccessKey对应控制台中的“Access Key Secret”，获取方式请参考《操作指南 管理ACCESSKEY》。
2. 如果用户需要自己指定域名，可以通过传入ENDPOINT参数来指定，ENDPOINT参数需要用指定区域的域名来进行定义，如服务所在区域为北京，则为http://bj.bcebos.com。

使用STS创建BosClient

申请STS token

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

通过STS方式访问BOS，用户需要先通过STS的client申请一个认证字符串，申请方式可参见百度智能云STS使用介绍。

用STS token新建BOSClient

申请好STS后，可将STStoken配置到BosClient中，用户可以参考如下代码新建一个BosClient：

1. 首先进行STS的endpoint配置。STS的配置示例如下：

   Ruby 复制

   1require 'baidubce/services/sts/sts_client'
   2require 'baidubce/services/bos/bos_client'
   3
   4credentials = Baidubce::Auth::BceCredentials.new(
   5    "your ak",
   6    "your sk"
   7)
   8
   9sts_conf = Baidubce::BceClientConfiguration.new(
   10    credentials,
   11    "http://sts.bj.baidubce.com"
   12)

2. StsClient的示例代码如下：

   Ruby 复制

   1# 新建StsClient
   2sts_client = Baidubce::Services::StsClient.new(sts_conf)
   3acl = {
   4            id: '8c47a952db4444c5a097b41be3f24c94',
   5            accessControlList: [
   6                {
   7                    eid: 'shj',
   8                    service: 'bce:bos',
   9                    region: 'bj',
   10                    effect: 'Allow',
   11                    resource: ["bos-demo"],
   12                    permission: ["READ"]
   13                }
   14            ]
   15}
   16
   17# durationSeconds为失效时间，如果为非int值或者不设置该参数，会使用默认的12小时作为失效时间
   18# sts_client.get_session_token(acl, "test")
   19# sts_client.get_session_token(acl, 1024)
   20sts_response = sts_client.get_session_token(acl)
   21
   22sts_ak = sts_response["accessKeyId"]
   23sts_sk = sts_response['secretAccessKey']
   24token = sts_response['sessionToken']

   注意：其中acl指用户定义的acl，语法请参照访问控制。

3. 将获取到的accessKeyID/secretAccessKey/sessionToken用于新建BosClient。

   Ruby 复制

   1 # 使用获取到的ak, sk, token新建BosClient访问BOS
   2sts_credentials = Baidubce::Auth::BceCredentials.new(
   3    sts_ak,
   4    sts_sk,
   5    token
   6)
   7
   8conf = Baidubce::BceClientConfiguration.new(
   9    sts_credentials,
   10    "http://bj.bcebos.com",
   11)
   12
   13client = Baidubce::Services::BosClient.new(conf)

   注意：目前使用STS配置client时，无论对应BOS服务的endpoint在哪里，endpoint都需配置为http://sts.bj.baidubce.com。

配置HTTPS协议访问BOS

BOS支持HTTPS传输协议，您可以通过如下两种方式在BOS Ruby SDK中使用HTTPS访问BOS服务：

• 在endpoint中指定HTTPS:

  Ruby 复制

  1# 配置client参数
  2credentials = Auth::BceCredentials.new(
  3    "accessKeyId",
  4    "secretAccessKey"
  5)
  6
  7conf = BceClientConfiguration.new(
  8    credentials,
  9    "https://bj.bcebos.com"
  10)
  11# 新建BosClient
  12client = Services::BosClient.new(conf)

• 通过在protocol中指定https来设置HTTPS协议:

  Ruby 复制

  1# 配置client参数
  2credentials = Auth::BceCredentials.new(
  3    "accessKeyId",
  4    "secretAccessKey"
  5)
  6
  7options = {
  8    'protocol' => 'https'
  9}
  10
  11conf = BceClientConfiguration.new(
  12    credentials,
  13    "bj.bcebos.com",
  14    options
  15)
  16
  17# 新建BosClient
  18client = Services::BosClient.new(conf)

  注意：如果您在指定了endpoint的scheme的同时指定了protocol参数，则以endpoint为准。

配置自定义域名/备用域名访问BOS

使用自定义域名

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

1require 'baidubce/services/bos/bos_client'
2include Baidubce
3
4#配置client参数
5credentials = Auth::BceCredentials.new(
6    "accessKeyId",
7    "secretAccessKey"
8)
9options = {
10    'cname_enabled' => true
11}
12conf = BceClientConfiguration.new(
13    credentials,
14    "cdn-test.cdn.bcebos.com",
15    options
16)
17
18#新建BosClient
19client = Services::BosClient.new(conf)

使用备用域名

在使用官方域名和自定义域名作为ENDPOINT访问BOS的基础上，SDK进一步支持了使用ENDPOINT主域名访问BOS失败时重试备用域名机制，使用方式如下：

1// 如果使用ENDPOINT访问BOS失败，SDK会自动重试backup_endpoint域名
2options = {
3    'backup_endpoint' => "bj.bcebos.com"
4}
5conf = BceClientConfiguration.new(
6    credentials,
7    "cdn.bcebos.com",
8    options
9)
10
11#新建BosClient
12client = Services::BosClient.new(conf)

配置BosClient

设置自定义参数

Ruby SDK默认设置了一些基本参数，若用户想要对参数的值进行修改，可以创建自身的参数配置，并在构造BosClient的时候传入，传入代码参考如下：

1#配置自定义参数
2options = {
3    'protocol' => 'https',
4    'read_timeout_in_millis' => 1000 * 60,
5    'region' => 'bj'
6}
7
8conf = BceClientConfiguration.new(
9    credentials,
10    "http://bj.bcebos.com",
11    options
12)
13
14#新建BosClient
15client = Services::BosClient.new(conf)

参数说明如下：

设置可选参数

BosClient将可选的参数封装到options中，每一个方法具有的可选参数详见具体的接口使用方法介绍，现以put_object_from_string方法为例，参考如下代码实现设置可选参数：

1# 利用options在上传Object的时候传入指定参数
2user_metadata = { "key1" => "value1" }
3options = { Http::CONTENT_TYPE => 'string',
4            "key2" => "value2",
5            'Content-Disposition' => 'inline',
6            'user-metadata' => user_metadata
7}
8
9client.put_object_from_string(bucket_name, object_name, "obj_str", options)