快速入门

1. 初始化一个带有STS验证的BosClient。

   BosClient是与BOS服务交互的客户端，BOS Android SDK的BOS操作都是通过BosClient完成的。

   示例代码：

   BosClientConfiguration config = new BosClientConfiguration(); //初始化一个带有STS验证的BosClient
   config.setCredentials(new DefaultBceSessionCredentials(<AccessKeyID>, <SecretAccessKey>, <Token>); //STS返回的临时AK/SK及Token
   config.setEndpoint(<EndPoint>); //传入Bucket所在区域域名
   BosClient client = new BosClient(config);

2. 新建一个Bucket。

   Bucket是BOS上的命名空间，相当于数据的容器，可以存储若干数据实体（Object）。在您上传数据前，必须先创建一个Bucket。

   示例代码：

   BosClient client = new BosClient(config);    //创建BOSClient实例
   client.createBucket(<BucketName>);     //新建一个Bucket，指定Bucket名称

3. 上传Object。

   Object是BOS中最基本的数据单元，您可以把Object简单的理解为文件。对于一个简单的Object的上传，BOS为您提供了四种方式：文件形式上传、数据流形式上传、二进制串上传和字符串上传。

   示例代码：

   // 获取指定文件
   File file = new File(<FilePath>);     //指定文件路径
   
   // 以文件形式上传Object
   PutObjectResponse putObjectFromFileResponse = client.putObject(<BucketName>, <ObjectKey>, file);
   
   // 获取数据流
   InputStream inputStream = new FileInputStream(<FilePath>);
   
   // 以数据流形式上传Object
   PutObjectResponse putObjectResponseFromInputStream = client.putObject(<BucketName>, <ObjectKey>, inputStream);
   
   // 以二进制串上传Object
   PutObjectResponse putObjectResponseFromByte = client.putObject(<BucketName>, <ObjectKey>, <byte>);
   
   // 以字符串上传Object
   PutObjectResponse putObjectResponseFromString = client.putObject(<BucketName>, <ObjectKey>, <string>);
   
   // 打印ETag
   System.out.println(putObjectFromFileResponse.getETag());

4. 查看Bucket下的Object列表。

   当您完成一系列上传后，可以参考如下代码来查看Bucket下的全部Object。

   示例代码：

   // 获取指定Bucket下的所有Object信息
   ListObjectsResponse listing = client.listObjects(<BucketName>);
   
   // 遍历所有Object
   for (BosObjectSummary objectSummary : listing.getContents()) {
     System.out.println("ObjectKey: " + objectSummary.getKey());
     }

5. 获取指定Object

   用户可以参考如下代码来实现对一个或者多个Object的获取。

   示例代码：

   // 获取Object，返回结果为BosObject对象
   BosObject object = client.getObject(<BucketName>, <ObjectKey>);
   
   // 获取ObjectMeta
   ObjectMetadata meta = object.getObjectMetadata();
   
   // 获取Object的输入流
   InputStream objectContent = object.getObjectContent();
   
   // 处理Object
   ...
   
   // 关闭流
   objectContent.close();

完整示例

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;

import android.os.Bundle;

import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.development.AppSettings;
import com.baidubce.development.BaseActivity;
import com.baidubce.development.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.BosObject;
import com.baidubce.services.bos.model.BosObjectSummary;
import com.baidubce.services.bos.model.CreateBucketResponse;
import com.baidubce.services.bos.model.ListObjectsResponse;
import com.baidubce.services.bos.model.ObjectMetadata;
import com.baidubce.services.bos.model.PutObjectResponse;
import com.baidubce.util.BLog;

public class ExampleActivity extends BaseActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        //打开bossdk运行时log
        BLog.enableLog();
        
        BosClientConfiguration config = new BosClientConfiguration(); //初始化一个带有STS验证的BosClient
        config.setCredentials(new DefaultBceSessionCredentials(<AccessKeyID>, <SecretAccessKey>, <Token>); //STS返回的临时AK/SK及Token
        config.setEndpoint(<EndPoint>); //Bucket所在区域
        final BosClient client = new BosClient(config);

        new Thread(new Runnable() {

            @Override
            public void run() {

                try {
                    //创建Bucket
                    CreateBucketResponse response = client.createBucket(<BucketName>); //新建一个Bucket并指定Bucket名称
                    System.out.println(response.getLocation());
                    System.out.println(response.getName());

                    //上传Object
                    File file = new File(<Path>);//上传文件的目录
                    PutObjectResponse putObjectFromFileResponse = client.putObject(<BucketName>, <ObjectKey>, file);
                    System.out.println(putObjectFromFileResponse.getETag());

                    //查看Object
                    ListObjectsResponse list = client.listObjects(<BucketName>);
                    for (BosObjectSummary objectSummary : list.getContents()) {
                        System.out.println("ObjectKey: " + objectSummary.getKey());
                    }

                    // 获取Object
                    BosObject object = client.getObject(<BucketName>, <ObjectKey>);
                    // 获取ObjectMeta
                    ObjectMetadata meta = object.getObjectMetadata();
                    // 获取Object的输入流
                    InputStream objectContent = object.getObjectContent();
                    // 处理Object
                    FileOutputStream fos=new FileOutputStream(<Path>);//下载文件的目录/文件名
                    byte[] buffer=new byte[2048];
                    int count=0;
                    while ((count=objectContent.read(buffer))>=0) {
                        fos.write(buffer,0,count);
                    }

                    // 关闭流
                    objectContent.close();
                    fos.close();
                    System.out.println(meta.getETag());
                    System.out.println(meta.getContentLength());

                }catch (BceServiceException e) {
                    System.out.println("Error ErrorCode: " + e.getErrorCode());
                    System.out.println("Error RequestId: " + e.getRequestId());
                    System.out.println("Error StatusCode: " + e.getStatusCode());
                    System.out.println("Error Message: " + e.getMessage());
                    System.out.println("Error ErrorType: " + e.getErrorType());
                } catch (BceClientException e) {
                    System.out.println("Error Message: " + e.getMessage());
                } catch (IOException e) {
                    // TODO Auto-generated catch block
                    e.printStackTrace();
                }



            }
        }).start();

    }
}

新建带有STS验证的BosClient

BosClient是BOS服务的客户端，为开发者与BOS服务进行交互提供了一系列的方法。在使用SDK发起对BOS的请求前，您需要初始化一个BosClient实例，并对它进行一些必要设置。

说明：Android SDK主要用于移动端开发的场景，移动端是一个不受信任的环境，把AccessKeyId和SecretAccessKey直接保存在终端用来加签请求，存在极高的风险。故推荐您使用STS鉴权模式。STS的详细介绍请参考 临时授权访问。

使用STS方式需要您在调用API时首先创建带有STS的BosClient来执行，目前BOS的STS只支持如下方法的API调用：

• DeleteObject
• PutObject
• ListParts
• GetObject
• DoesBucketExist
• CompleteMultipartUpload
• AbortMultipartUpload
• InitiateMultipartUpload
• UploadPart

示例代码：用户可以参考如下代码新建一个带有STS验证的BosClient：

  BosClientConfiguration config = new BosClientConfiguration(); //初始化一个带有STS验证的BosClient
  config.setCredentials(new DefaultBceSessionCredentials(<AccessKeyID>, <SecretAccessKey>, <Token>); //STS返回的临时AK/SK及Token
  config.setEndpoint(<EndPoint>); //传入Bucket所在区域域名。EndPoint是指BOS服务在各个区域的域名地址，例如北京域名为bj.bcebos.com
  BosClient client = new BosClient(config);

注意：EndPoint参数只能用指定的包含区域的域名来进行定义。百度智能云目前开放了多区域支持，请参考 区域选择说明。

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

配置HTTPS协议访问BOS

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

• 在endpoint中指明https:

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

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

  String endpoint = "bj.bcebos.com"; // endpoint中不包含protocol
  String ak = "ak";
  String sk = "sk";
  BosClientConfiguration config = new BosClientConfigration();
  config.setEndpoint(endpoint);  
  config.setCredentials(new DefaultBceCredentials(ak, sk));
  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 BosClientConfigration();
  config.setEndpoint(endpoint); 
  config.setCredentials(new DefaultBceCredentials(ak, sk));
  config.setProtocol(Protocol.HTTPS); // endpoint中已经指明, 此为无效操作, 对http也是如此
  BosClient client = new BosClient(config);

配置BosClient

如果您需要配置BosClient的一些细节的参数，可以在构造BosClient的时候传入BosClientConfiguration对象。 BosClientConfiguration是BOS服务的配置类，可以通过BosClientConfiguration对基本网络参数进行设置。

设置网络参数

您可以使用BosClientConfiguration对基本网络参数进行设置。

• 示例代码

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

• 参数说明

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

  参数	说明
  UserAgent	用户代理，指HTTP的User-Agent头
  Protocol	连接协议类型，缺省值HTTP协议
  LocalAddress	本地地址
  ConnectionTimeoutInMillis	建立连接的超时时间（单位：毫秒），缺省值为30000
  SocketTimeoutInMillis	通过打开的连接传输数据的超时时间（单位：毫秒），缺省值为30000
  MaxConnections	允许打开的最大HTTP连接数，缺省值为5
  RetryPolicy	连接重试策略
  SocketBufferSizeInBytes	Socket缓冲区大小
  StreamBufferSize	流文件缓冲区大小
  Ipv4Priority	Ipv4优先，缺省值false