初始化

更新时间：2024-09-12

确认Endpoint

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

目前支持多个区域，对应信息为：

区域	访问EndPoint	支持协议
北京	bj.bcebos.com	HTTP,HTTPS
保定	bd.bcebos.com	HTTP,HTTPS
苏州	su.bcebos.com	HTTP,HTTPS
广州	gz.bcebos.com	HTTP,HTTPS
成都	cd.bcebos.com	HTTP,HTTPS
香港	hkg.bcebos.com	HTTP,HTTPS
武汉	fwh.bcebos.com	HTTP,HTTPS
金融云上海专区	fsh.bcebos.com	HTTP,HTTPS

获取密钥

要使用百度智能云BOS，您需要拥有一个有效的 AK（Access Key ID）和SK(Secret Access Key)用来进行签名认证。AK/SK是由系统分配给用户的，均为字符串，用于标识用户，为访问BOS做签名验证。可以通过如下步骤获得并了解您的AK/SK信息：

注册百度智能云账号

创建AK/SK

新建BosClient

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

使用AK/SK新建BosClient

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

public class Sample {
public static void main(String[] args) {
    String ACCESS_KEY_ID = <your-access-key-id>;                   // 用户的Access Key ID
    String SECRET_ACCESS_KEY = <your-secret-access-key>;           // 用户的Secret Access Key
        
    // 初始化一个BosClient
    BosClientConfiguration config = new BosClientConfiguration();
    config.setCredentials(new DefaultBceCredentials(ACCESS_KEY_ID, SECRET_ACCESS_KEY));
    BosClient client = new BosClient(config);
    }
}

在上面代码中，ACCESS_KEY_ID对应控制台中的“Access Key ID”，SECRET_ACCESS_KEY对应控制台中的“Access Key Secret”，获取方式请参考《操作指南管理ACCESSKEY》。

可以通过传入ENDPOINT参数来指定不同地域的BOS官方域名，不指定时默认为北京区域http://bj.bcebos.com。

String ACCESS_KEY_ID = <your-access-key-id>;                   // 用户的Access Key ID
String SECRET_ACCESS_KEY = <your-secret-access-key>;           // 用户的Secret Access Key
String ENDPOINT = <domain-name>;                               // 用户自己指定地域的官方域名

BosClientConfiguration config = new BosClientConfiguration();
config.setCredentials(new DefaultBceCredentials(ACCESS_KEY_ID,SECRET_ACCESS_KEY));
config.setEndpoint(ENDPOINT);
BosClient client = new BosClient(config);

注意：如需使用自定义域名访问，除了修改ENDPOINT参数外还需要打开自定义域名开关，详见下述配置自定义域名访问BOS。

使用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：

public class StsExample {
    private static final String STS_ENDPOINT = "http://sts.bj.baidubce.com";
    private static final String ENDPOINT = "bj.bcebos.com";
    private static final String ACCESS_KEY_ID = "your accesskey id";
    private static final String SECRET_ACCESS_KEY = "your secret accesskey";

    public static void main(String[] args) {
        BceCredentials credentials = new DefaultBceCredentials(ACCESS_KEY_ID, SECRET_ACCESS_KEY);
        StsClient client = new StsClient(
                new BceClientConfiguration().withEndpoint(STS_ENDPOINT).withCredentials(credentials)
        );
        GetSessionTokenResponse response = client.getSessionToken(new GetSessionTokenRequest());
        // or simply call:
        // GetSessionTokenResponse response = client.getSessionToken();
        // or you can specify limited permissions with ACL:
        // GetSessionTokenResponse response = client.getSessionToken(new GetSessionTokenRequest().withAcl("blabla"));
        // build DefaultBceSessionCredentials object from response:
        BceCredentials bosstsCredentials = new DefaultBceSessionCredentials(
                response.getAccessKeyId(),
                response.getSecretAccessKey(),
                response.getSessionToken());
        System.out.println("==================================");
        System.out.println("GetSessionToken result:");
        System.out.println("    accessKeyId:  " + response.getAccessKeyId());
        System.out.println("    secretAccessKey:  " + response.getSecretAccessKey());
        System.out.println("    securityToken:  " + response.getSessionToken());
        System.out.println("    expiresAt:  " + response.getExpiration().toString());
        System.out.println("==================================");

        // build bos client
        BosClientConfiguration config = new BosClientConfiguration();
        config.setCredentials(bosstsCredentials);
        config.setEndpoint(ENDPOINT);
        BosClient bosClient = new BosClient(config);
    }
}

注意：目前使用STS配置client时，无论对应bucket的区域在哪里，endpoint都需配置为http://sts.bj.baidubce.com，但创建BosClient时，仍需使用BOS的endpoint，如bj.bcebos.com、su.bcebos.com等.

配置自定义域名访问BOS

使用自定义域名

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

 String ACCESS_KEY_ID = <your-access-key-id>;                   // 用户的Access Key ID
 String SECRET_ACCESS_KEY = <your-secret-access-key>;           // 用户的Secret Access Key
 String ENDPOINT = "https://cdn-test.cdn.bcebos.com";           // 用户自己指定的域名

 BosClientConfiguration config = new BosClientConfiguration();
 config.setCredentials(new DefaultBceCredentials(ACCESS_KEY_ID,SECRET_ACCESS_KEY));
 config.setEndpoint(ENDPOINT);
 config.setCnameEnabled(true);
 BosClient client = new BosClient(config);

配置HTTPS协议访问BOS

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

在endpoint中指明https:

String endpoint = "https://bj.bcebos.com";
String ak = "ak";
String sk = "sk";
BosClientConfiguration config = new BosClientConfiguration();
config.setCredentials(new DefaultBceCredentials(ak, sk));
config.setEndpoint(endpoint);
BosClient client = new BosClient(config);

通过调用setProtocol方法设置https协议:

String endpoint = "bj.bcebos.com"; // endpoint中不包含protocol
String ak = "ak";
String sk = "sk";
BosClientConfiguration config = new BosClientConfiguration();
config.setCredentials(new DefaultBceCredentials(ak, sk));
config.setEndpoint(endpoint);
config.setProtocol(Protocol.HTTPS); // 如果不指明, 则使用http
BosClient client = new BosClient(config);

注意：如果在endpoint中指明了protocol, 则endpoint中的生效, 另外单独再调用setProtocol()不起作用。

String endpoint = "http://bj.bcebos.com";
String ak = "ak";
String sk = "sk";
BosClientConfiguration config = new BosClientConfiguration();
config.setCredentials(new DefaultBceCredentials(ak, sk));
config.setEndpoint(endpoint);    
config.setProtocol(Protocol.HTTPS); // endpoint中已经指明, 此为无效操作, 对http也是如此
BosClient client = new BosClient(config);

配置BosClient

如果用户需要配置BosClient的一些细节的参数，可以在构造BosClient的时候传入BosClientConfiguration对象。 BosClientConfiguration是BOS服务的配置类，可以为客户端配置代理，最大连接数等参数。

使用代理

下面一段代码可以让客户端使用代理访问BOS服务：

String ACCESS_KEY_ID = <your-access-key-id>;                   // 用户的Access Key ID
String SECRET_ACCESS_KEY = <your-secret-access-key>;           // 用户的Secret Access Key
String ENDPOINT = <domain-name>;                               // 用户自己指定的域名

// 创建BosClientConfiguration实例
BosClientConfiguration config = new BosClientConfiguration();

// 配置代理为本地8080端口
config.setProxyHost("127.0.0.1");
config.setProxyPort(8080);

// 创建BOS客户端
config.setCredentials(new DefaultBceCredentials(ACCESS_KEY_ID,SECRET_ACCESS_KEY));
config.setEndpoint(ENDPOINT);
BosClient client = new BosClient(config);

使用上面的代码段，客户端的所有操作都会通过127.0.0.1地址的8080端口做代理执行。

对于有用户验证的代理，可以通过下面的代码段配置用户名和密码：

// 创建BosClientConfiguration实例
BosClientConfiguration config = new BosClientConfiguration();
    
// 配置代理为本地8080端口
config.setProxyHost("127.0.0.1");
config.setProxyPort(8080);
    
//设置用户名和密码
config.setProxyUsername(<username>);                             //用户名
config.setProxyPassword(<password>);                             //密码

设置网络参数

用户可以用BosClientConfiguration对基本网络参数进行设置：

BosClientConfiguration config = new BosClientConfiguration();
    
// 设置HTTP最大连接数为10
config.setMaxConnections(10);
    
// 设置TCP连接超时为5000毫秒
config.setConnectionTimeoutInMillis(5000);
    
// 设置Socket传输数据超时的时间为2000毫秒
config.setSocketTimeoutInMillis(2000);

设置访问域名风格

在0.10.227版本之后，SDK会默认自动开启bucket virtual hosting，可以通过以下配置开启使用PathStyle风格的endpoint：

BosClientConfiguration config = new BosClientConfiguration();

// 开启使用PathStyle
config.setPathStyleAccessEnable(true);

注意：部分非BOS常规域名下，默认bucket virtual hosting风格的可能会有不兼容场景，表现为dns解析失败等，可以开启PathStyle解决。其他场景建议使用默认风格。

设置重定向

在0.10.330版本之后，出于安全考虑，SDK会默认关闭自动重定向。用户可以通过配置来开启自动重定向和配置参数：

BosClientConfiguration config = new BosClientConfiguration();

// 开启自动重定向
config.setRedirectsEnabled(true);
// 设置最大自动重定向次数
config.setMaxRedirects(10);

设置同步PUT

对PUT操作，默认使用CloseableHttpAsyncClient，可能会出现用户进程执行完未退出的现象。用户可以通过BosClientConfiguration设置所有BOS请求都通过BosClient同步的方式：

BosClientConfiguration config = new BosClientConfiguration();

// 设置PUT操作为同步方式，默认异步
config.setEnableHttpAsyncPut(false);

参数说明

通过BosClientConfiguration能指定的所有参数如下表所示：

参数	说明
CnameEnabled	使用cname访问BOS资源
ConnectionTimeoutInMillis	建立连接的超时时间（单位：毫秒）
Credentials	客户端用于签署HTTP请求的BCE凭据
EnableHttpAsyncPut	异步put
Endpoint	访问域名
LocalAddress	本地地址
MaxConnections	允许打开的最大HTTP连接数
Protocol	连接协议类型
ProxyDomain	访问NTLM验证的代理服务器的Windows域名
ProxyHost	代理服务器主机地址
ProxyPassword	代理服务器验证的密码
ProxyPort	代理服务器端口
ProxyPreemptiveAuthenticationEnabled	是否设置用户代理认证
ProxyUsername	代理服务器验证的用户名
ProxyWorkstation	NTLM代理服务器的Windows工作站名称
Region	地域
RetryPolicy	连接重试策略
SocketBufferSizeInBytes	Socket缓冲区大小
SocketTimeoutInMillis	通过打开的连接传输数据的超时时间（单位：毫秒）
StreamBufferSize	流文件缓冲区大小
UserAgent	用户代理，指HTTP的User-Agent头
RedirectsEnabled	是否开启HTTP重定向。默认关闭
MaxRedirects	HTTP重定向自动重定向最大次数。默认为1次
PathStyleAccessEnable	是否使用PathStyle风格的endpoint，默认关闭，即使用bucket virtual hosting

安装SDK工具包

Bucket管理

对象存储 BOS