初始化

确认Endpoint

  • 在确认您使用SDK时配置的Endpoint时,可先阅读开发人员指南中关于BOS访问域名的部分,理解Endpoint相关的概念。

  • 百度智能云目前开放了多区域支持,请参考区域选择说明

  • 目前支持“华北-北京”、“华南-广州”和“华东-苏州”三个区域。北京区域:http://bj.bcebos.com,广州区域:http://gz.bcebos.com,苏州区域:http://su.bcebos.com

    对应信息为:

    访问区域 对应Endpoint
    BJ bj.bcebos.com
    GZ gz.bcebos.com
    SU su.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为准。

配置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)

参数说明如下:

参数 说明 默认值
protocol 协议 http
region 区域 bj
open_timeout_in_millis 请求超时时间(单位:毫秒) 50 * 1000
read_timeout_in_millis 通过打开的连接传输数据的超时时间(单位:毫秒) 10 60 1000(设置时需要对文件大小和网速进行评估,否则上传大文件时会产生超时)
send_buf_size 发送缓冲区大小 1024 * 1024
recv_buf_size 接收缓冲区大小 10 * 1024 * 1024

设置可选参数

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)

Bucket管理

Bucket既是BOS上的命名空间,也是计费、权限控制、日志记录等高级功能的管理实体。

  • Bucket名称在所有区域中具有全局唯一性,且不能修改。

    说明:

    • 百度智能云目前开放了多区域支持,请参考区域选择说明
    • 目前支持“华北-北京”、“华南-广州”和“华东-苏州”三个区域。北京区域:http://bj.bcebos.com,广州区域:http://gz.bcebos.com,苏州区域:http://su.bcebos.com
  • 存储在BOS上的每个Object都必须包含在一个Bucket中。

  • 一个用户最多可创建100个Bucket,但每个Bucket中存放的Object的数量和大小总和没有限制,用户不需要考虑数据的可扩展性。

Bucket权限管理

设置Bucket的访问权限

如下代码将Bucket的权限设置为了private:

client.set_bucket_canned_acl(bucket_name, "private")

canned acl支持三种权限,分别为:privatepublic-readpublic-read-write。关于权限的具体内容可以参考《BOS API文档 使用CannedAcl方式的权限控制》。

设置指定用户对Bucket的访问权限

BOS提供set_bucket_acl方法来实现指定用户对Bucket的访问权限设置,可以参考如下代码实现:

acl = [{'grantee' => [{'id' => 'b124deeaf6f641c9ac27700b41a350a8'},
                      {'id' => 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'}],
        'permission' => ['FULL_CONTROL']
}]

client.set_bucket_acl(bucket_name, acl)

注意:

  1. permission中的权限设置包含三个值:READWRITEFULL_CONTROL,它们分别对应相关权限。具体内容可以参考《BOS API文档 上传ACL文件方式的权限控制》。
  2. 设置两个以上(含两个)被授权人时,请参考以上示例的格式,若将数组合并会返回报错。

设置更多Bucket访问权限

  1. 通过设置referer白名单方式设置防盗链

    acl = [{'grantee' => [{'id' => 'b124deeaf6f641c9ac27700b41a350a8'},
                        {'id' => 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'}],
          'permission' => ['FULL_CONTROL'],
          'condition' => {
              'referer' => {
                  'stringLike' => ['http://www.abc.com/*'],
                  'stringEquals' => ['http://www.abc.com']
               }
          }
    }]
    
    client.set_bucket_acl(bucket_name, acl)
    
  2. 限制客户端IP访问,只允许部分客户端IP访问

    acl = [{'grantee' => [{'id' => 'b124deeaf6f641c9ac27700b41a350a8'},
                        {'id' => 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'}],
          'permission' => ['FULL_CONTROL'],
          'condition' => {
              "ipAddress" => [
                    '192.168.0.0/16',
                    '192.169.0.*',
                    '192.170.0.5'
              ]
          }
    }]
    
    client.set_bucket_acl(bucket_name, acl)
    

设置STS临时token权限

对于通过STS方式创建的临时访问身份,管理员也可进行专门的权限设定。
STS的简介及设置临时权限的方式可参见临时授权访问

使用BOS Ruby SDK设置STS临时token权限可参考使用STS创建BosClient

查看Bucket的权限

如下代码可以查看Bucket的权限:

client.get_bucket_acl(bucket_name)

get_bucket_acl方法返回的解析类中可供调用的参数有:

参数 说明
owner Bucket owner信息
id Bucket owner的用户ID
acl 标识Bucket的权限列表
grantee 标识被授权人
-id 被授权人ID
permission 标识被授权人的权限

查看Bucket所属的区域

Bucket Location即Bucket Region,百度智能云支持的各region详细信息可参见区域选择说明

如下代码可以获取该Bucket的Location信息:

client.get_bucket_location(bucket_name)

新建Bucket

如下代码可以新建一个Bucket:

bucketName = "your_bucket";

# Bucket是否存在,若不存在创建Bucket
client.create_bucket(bucket_name) unless client.does_bucket_exist(bucket_name)

注意:
由于Bucket的名称在所有区域中是唯一的,所以需要保证bucketName不与其他所有区域上的Bucket名称相同。

Bucket的命名有以下规范:

  • 只能包括小写字母,数字,短横线(-)。
  • 必须以小写字母或者数字开头。
  • 长度必须在3-63字节之间。

通过上述代码创建的bucket,权限是私有读写,存储类型是标准类型(Standard)。用户在控制台创建Bucket时可以指定Bucket权限和存储类型。

列举Bucket

如下代码可以列出用户所有的Bucket:

buckets = client.list_buckets()

删除Bucket

删除指定Bucket

如下代码可以删除一个Bucket:

bucketName = "your_bucket";
client.delete_bucket(bucketName)

注意:

  • 在删除前需要保证此Bucket下的所有Object和未完成的三步上传Part已经被删除,否则会删除失败。
  • 在删除前确认该Bucket没有开通跨区域复制,不是跨区域复制规则中的源Bucket或目标Bucket,否则不能删除。

删除所有Bucket

delete_bucketlist_buckets函数结合,可以删除全部Bucket,参考代码如下:

# 列出全部Bucket
buckets = client.list_buckets()['buckets']

# 遍历删除全部Bucket
buckets.each do |bucket|
    while true
        options = {}
        res = client.list_objects(bucket['name'], options)
        res['contents'].each do |object|
            client.delete_object(bucket['name'], object['key'])
        end
        if res['isTruncated']
            options[:marker] = res['nextMarker']
        else
            break
        end
    end
    client.delete_bucket(bucket['name'])
end

判断Bucket是否存在

若用户需要判断某个Bucket是否存在,则如下代码可以做到:

client.does_bucket_exist(bucketName)