确认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。

对应信息为：

访问区域 | 对应Endpoint
---|---
BJ | bj.bcebos.com
BD | bd.bcebos.com
SU | su.bcebos.com
GZ | gz.bcebos.com
CD | cd.bcebos.com
HKG| hkg.bcebos.com
FWH | fwh.bcebos.com
FSH | 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：

#使用Ruby SDK，引入bos_client和Baidubce模块
require 'baidubce/services/bos/bos_client'
include Baidubce

#配置client参数
credentials = Auth::BceCredentials.new(
    "accessKeyId",
    "secretAccessKey"
)

conf = BceClientConfiguration.new(
    credentials,
    "ENDPOINT"
)
#新建BosClient
client = 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的配置示例如下：

   require 'baidubce/services/sts/sts_client'
   require 'baidubce/services/bos/bos_client'
   
   credentials = Baidubce::Auth::BceCredentials.new(
       "your ak",
       "your sk"
   )
   
   sts_conf = Baidubce::BceClientConfiguration.new(
       credentials,
       "http://sts.bj.baidubce.com"
   )

2. StsClient的示例代码如下：

   # 新建StsClient
   sts_client = Baidubce::Services::StsClient.new(sts_conf)
   acl = {
               id: '8c47a952db4444c5a097b41be3f24c94',
               accessControlList: [
                   {
                       eid: 'shj',
                       service: 'bce:bos',
                       region: 'bj',
                       effect: 'Allow',
                       resource: ["bos-demo"],
                       permission: ["READ"]
                   }
               ]
   }
   
   # durationSeconds为失效时间，如果为非int值或者不设置该参数，会使用默认的12小时作为失效时间
   # sts_client.get_session_token(acl, "test")
   # sts_client.get_session_token(acl, 1024)
   sts_response = sts_client.get_session_token(acl)
   
   sts_ak = sts_response["accessKeyId"]
   sts_sk = sts_response['secretAccessKey']
   token = sts_response['sessionToken']

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

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

    # 使用获取到的ak, sk, token新建BosClient访问BOS
   sts_credentials = Baidubce::Auth::BceCredentials.new(
       sts_ak,
       sts_sk,
       token
   )
   
   conf = Baidubce::BceClientConfiguration.new(
       sts_credentials,
       "http://bj.bcebos.com",
   )
   
   client = 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:

  # 配置client参数
  credentials = Auth::BceCredentials.new(
      "accessKeyId",
      "secretAccessKey"
  )
  
  conf = BceClientConfiguration.new(
      credentials,
      "https://bj.bcebos.com"
  )
  # 新建BosClient
  client = Services::BosClient.new(conf)

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

  # 配置client参数
  credentials = Auth::BceCredentials.new(
      "accessKeyId",
      "secretAccessKey"
  )
  
  options = {
      'protocol' => 'https'
  }
  
  conf = BceClientConfiguration.new(
      credentials,
      "bj.bcebos.com",
      options
  )
  
  # 新建BosClient
  client = Services::BosClient.new(conf)

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

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

使用自定义域名

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

require 'baidubce/services/bos/bos_client'
include Baidubce

#配置client参数
credentials = Auth::BceCredentials.new(
    "accessKeyId",
    "secretAccessKey"
)
options = {
    'cname_enabled' => true
}
conf = BceClientConfiguration.new(
    credentials,
    "cdn-test.cdn.bcebos.com",
    options
)

#新建BosClient
client = Services::BosClient.new(conf)

使用备用域名

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

// 如果使用ENDPOINT访问BOS失败，SDK会自动重试backup_endpoint域名
options = {
    'backup_endpoint' => "bj.bcebos.com"
}
conf = BceClientConfiguration.new(
    credentials,
    "cdn.bcebos.com",
    options
)

#新建BosClient
client = Services::BosClient.new(conf)

配置BosClient

设置自定义参数

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

#配置自定义参数
options = {
    'protocol' => 'https',
    'read_timeout_in_millis' => 1000 * 60,
    'region' => 'bj'
}

conf = BceClientConfiguration.new(
    credentials,
    "http://bj.bcebos.com",
    options
)

#新建BosClient
client = Services::BosClient.new(conf)

参数说明如下：

设置可选参数

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

# 利用options在上传Object的时候传入指定参数
user_metadata = { "key1" => "value1" }
options = { Http::CONTENT_TYPE => 'string',
            "key2" => "value2",
            'Content-Disposition' => 'inline',
            'user-metadata' => user_metadata
}

client.put_object_from_string(bucket_name, object_name, "obj_str", options)