快速入门

1. 初始化一个BosClient。

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

   示例代码：

   class BosClientSample
   {
       static void Main(string[] args)
       {
           const string accessKeyId = <AccessKeyID>; // 您的Access Key ID
           const string secretAccessKey = <SecretAccessKey>; // 您的Secret Access Key
           const string endpoint = "https://bj.bcebos.com";          //传入Bucket所在区域域名
   
           // 初始化一个BosClient
           BceClientConfiguration config = new BceClientConfiguration();
           config.Credentials = new DefaultBceCredentials(accessKeyId, secretAccessKey);
           config.Endpoint = endpoint;        
           BosClient client = new BosClient(config);
       }
   }

2. 新建一个Bucket。

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

   示例代码：

   public void CreateBucket(BosClient client, string bucketName)
   {
       // 新建一个Bucket
       client.CreateBucket(bucketName); 
   }                            

3. 上传Object。

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

   示例代码：

   public void PutObject(BosClient client, String bucketName, String objectKey, byte[] byte1, String string1)
   {
       // 获取指定文件
       FileInfo file = new FileInfo(<FilePath>);    //指定文件路径
                     
       // 以文件形式上传Object
       PutObjectResponse putObjectFromFileResponse = client.PutObject(bucketName, objectKey, file);
                    
       // 获取数据流
       Stream inputStream = file.OpenRead();
                     
       // 以数据流形式上传Object
       PutObjectResponse putObjectResponseFromInputStream = client.PutObject(bucketName, objectKey, inputStream);
                     
       // 以二进制串上传Object
       PutObjectResponse putObjectResponseFromByte = client.PutObject(bucketName, objectKey, Encoding.Default.GetBytes("sampledata"));
                         
       // 以字符串上传Object
       PutObjectResponse putObjectResponseFromString = client.PutObject(bucketName, objectKey, "sampledata");
   
       // 打印ETag
       Console.WriteLine(putObjectFromFileResponse.ETAG);
   }

4. 查看Bucket下的Object列表。

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

   示例代码：

   public void ListObjects(BosClient client, string bucketName)
   {
       // 获取指定Bucket下的所有Object信息
       ListObjectsResponse listObjectsResponse = client.ListObjects(bucketName);
   
       // 遍历所有Object
       foreach (BosObjectSummary objectSummary in listObjectsResponse.Contents)
       {
           Console.WriteLine("ObjectKey: " + objectSummary.Key);
       }
   }

5. 获取指定Object

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

   示例代码：

   public void GetObject(BosClient client, String bucketName, String objectKey)
   {
       // 获取Object，返回结果为BosObject对象
       BosObject bosObject = client.GetObject(bucketName, objectKey);
   
       // 获取ObjectMeta
       ObjectMetadata meta = bosObject.ObjectMetadata;
   
       // 获取Object的输入流
       Stream objectContent = bosObject.ObjectContent;
   
       // 处理Object
       ...
   
       // 关闭流
       objectContent.Close();
   }

完整示例

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text;
using BaiduBce;
using BaiduBce.Auth;
using BaiduBce.Services.Bos;
using BaiduBce.Services.Bos.Model;

namespace DotnetSample
{
    internal class BaseSample
    {
        private static void Main(string[] args)
        {
            BosClient client = GenerateBosClient();
            const string bucketName = <BucektName>;    //指定Bucket名称
            const string objectKey = <ObjectKey>;     //指定object名称

            //创建Bucket
            client.CreateBucket(bucketName);

            //上传Object
            FileInfo file = new FileInfo("d:\\lzb\\sample.txt");     //指定上传文件的路径
            PutObjectResponse putObjectFromFileResponse = client.PutObject(bucketName, objectKey, file);
            Console.WriteLine(putObjectFromFileResponse.ETAG);

            //查看Object
            ListObjectsResponse listObjectsResponse = client.ListObjects(bucketName);
            foreach (BosObjectSummary objectSummary in listObjectsResponse.Contents)
            {
                Console.WriteLine("ObjectKey: " + objectSummary.Key);
            }

            // 获取Object
            BosObject bosObject = client.GetObject(bucketName, objectKey);
            // 获取ObjectMeta
            ObjectMetadata meta = bosObject.ObjectMetadata;
            // 获取Object的输入流
            Stream objectContent = bosObject.ObjectContent;
            // 处理Object
            FileStream fileStream = new FileInfo("d:\\lzb\\sampleout.txt").OpenWrite();      //指定下载文件的目录/文件名
            byte[] buffer = new byte[2048];
            int count = 0;
            while ((count = objectContent.Read(buffer, 0, buffer.Length)) > 0)
            {
                fileStream.Write(buffer, 0, count);
            }

            // 关闭流
            objectContent.Close();
            fileStream.Close();
            Console.WriteLine(meta.ETag);
            Console.WriteLine(meta.ContentLength);
        }

        private static BosClient GenerateBosClient()
        {
            const string accessKeyId = <AccessKeyID>; // 您的Access Key ID
            const string secretAccessKey = <SecretAccessKey>; // 您的Secret Access Key
            const string endpoint = "https://bj.bcebos.com";        //指定Bucket所在区域域名

            // 初始化一个BosClient
            BceClientConfiguration config = new BceClientConfiguration();
            config.Credentials = new DefaultBceCredentials(accessKeyId, secretAccessKey);
            config.Endpoint = endpoint;

            return new BosClient(config);
        }
    }
}

新建BosClient

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

使用AK/SK新建BosClient

• 基本流程

  1. 确定EndPoint。EndPoint是指BOS服务在各个区域的域名地址，默认域名为北京http://bj.bcebos.com。
  2. 创建一个BceClientConfiguration实例。
  3. 使用您的AK/SK创建DefaultBceCredentials并赋值给BceClientConfiguration的Credentials属性。
  4. 用配置好的BceClientConfiguration创建BosClient实例。
• 示例代码

class BosClientSample
{
    static void Main(string[] args)
    {
        const string accessKeyId = <AccessKeyID>;         // 您的Access Key ID
        const string secretAccessKey = <SecretAccessKey>; // 您的Secret Access Key
        const string endpoint = "https://bj.bcebos.com";  // 传入Bucket所在区域域名

        // 初始化一个BosClient
        BceClientConfiguration config = new BceClientConfiguration();
        config.Credentials = new DefaultBceCredentials(accessKeyId, secretAccessKey);
        config.Endpoint = endpoint;        
        BosClient client = new BosClient(config);
    }
}

EndPoint参数只能用指定的包含区域的域名来进行定义，不指定时默认为北京区域http://bj.bcebos.com。百度智能云目前开放了多区域支持，请参考区域选择说明。 目前支持“华北-北京”、“华南-广州”和“华东-苏州”三个区域。北京区域：http://bj.bcebos.com，广州区域：http://gz.bcebos.com，苏州区域：http://su.bcebos.com。

使用STS新建BosClient

• 基本流程

  1. 确定StsEndPoint 。StsEndPoint 是指授权服务的域名地址，默认域名为http://sts.bj.baidubce.com。
  2. 创建一个BceClientConfiguration实例。
  3. 使用您的AK/SK创建DefaultBceCredentials并赋值给BceClientConfiguration的Credentials属性。
  4. 用配置好的BceClientConfiguration创建StsClient实例。
  5. 通过StsClient获取临时AK/SK、token用于临时授权。
  6. 确定EndPoint。EndPoint是指BOS服务在各个区域的域名地址，默认域名为北京http://bj.bcebos.com。
  7. 再次创建一个BceClientConfiguration实例。
  8. 使用临时AK/SK、token创建DefaultBceCredentials并赋值给BceClientConfiguration的Credentials属性。
  9. 用配置好的BceClientConfiguration创建BosClient实例。
• 示例代码

class BosClientSample
{
    static void Main(string[] args)
    {
         const string accessKeyId = <AccessKeyID>;               // 您的Access Key ID
         const string secretAccessKey = <SecretAccessKey>;       // 您的Secret Access Key
         const string endpoint = "https://bj.bcebos.com";        // 指定Bucket所在区域域名
         const string stsEndpoint = "http://sts.bj.baidubce.com";// 指定授权服务域名
         
         // 获取临时授权Token
         BceClientConfiguration stsConfig = new BceClientConfiguration();
         stsConfig.Credentials = new DefaultBceCredentials(accessKeyId, secretAccessKey);
         stsConfig.Endpoint = stsEndpoint;
         StsClient stsClient = new StsClient(stsConfig);
         GetSessionTokenResponse response = stsClient.GetSessionToken();
        
         // 使用Token初始化一个BosClient
         BceClientConfiguration config = new BceClientConfiguration();
         config.Credentials = new DefaultBceSessionCredentials(
                 response.AccessKeyId,
                 response.SecretAccessKey,
                 response.SessionToken);
         config.Endpoint = endpoint;
         BosClient client = new BosClient(config);
    }
}

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

配置HTTPS协议访问BOS

BOS支持HTTPS传输协议，您可以将EndPoint直接设置为https即可，不设置EndPoint时，默认为http协议。

• 示例代码

  class BosClientSample
  {
      static void Main(string[] args)
      {
          const string accessKeyId = <AccessKeyID>; // 您的Access Key ID
          const string secretAccessKey = <SecretAccessKey>; // 您的Secret Access Key
          const string endpoint =  "https://bj.bcebos.com" ;          //传入Bucket所在区域域名，并直接设置为https协议
  
          // 初始化一个BosClient
          BceClientConfiguration config = new BceClientConfiguration();
          config.Credentials = new DefaultBceCredentials(accessKeyId, secretAccessKey);
          config.Endpoint = endpoint;        
          BosClient client = new BosClient(config);
      }
  }

配置自定义域名访问BOS

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

class BosClientSample
{
    static void Main(string[] args)
    {
        const string accessKeyId = <AccessKeyID>;         // 您的Access Key ID
        const string secretAccessKey = <SecretAccessKey>; // 您的Secret Access Key
        const string endpoint = <EndPoint>;  // 传入自定义域名

        // 初始化一个BosClient
        BceClientConfiguration config = new BceClientConfiguration();
        config.Credentials = new DefaultBceCredentials(accessKeyId, secretAccessKey);
        config.Endpoint = endpoint;
      	config.CnameEnabled = true;
        BosClient client = new BosClient(config);
    }
}

配置BosClient

• 基本流程

  1. 创建一个BceClientConfiguration实例。
  2. 使用您的AK/SK创建DefaultBceCredentials并赋值给BceClientConfiguration的Credentials属性。
  3. 对BceClientConfiguratio实例的各种属性进行赋值。
  4. 用配置好的BceClientConfiguration创建BosClient实例。

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

设置网络参数

• 示例代码

  BceClientConfiguration config = new BceClientConfiguration();
  
  // 设置HTTP最大连接数为10
  config.ConnectionLimit = 10;
  
  // 设置TCP连接超时为5000毫秒
  config.TimeoutInMillis = 5000;
  
  // 设置读写数据超时的时间为50000毫秒
  config.ReadWriteTimeoutInMillis = 50000;

• 参数说明

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

• 完整示例

  下面示例代码演示了BosClient的创建和配置。

  using System;
  using System.Collections.Generic;
  using System.Linq;
  using System.Text;
  using BaiduBce;
  using BaiduBce.Auth;
  using BaiduBce.Services.Bos;
  
  namespace DotnetSample
  {
      internal class BosClientSample
      {
          private static void Main(string[] args)
          {
              const string accessKeyId = <AccessKeyID>; // 您的Access Key ID
              const string secretAccessKey = <SecretAccessKey>; // 您的Secret Access Key
              const string endpoint = "https://bj.bcebos.com";
  
              // 初始化一个BosClient
              BceClientConfiguration config = new BceClientConfiguration();
              config.Credentials = new DefaultBceCredentials(accessKeyId, secretAccessKey);
              config.Endpoint = endpoint;
  
              // 设置HTTP最大连接数为10
              config.ConnectionLimit = 10;
  
              // 设置TCP连接超时为5000毫秒
              config.TimeoutInMillis = 5000;
  
              // 设置读写数据超时的时间为50000毫秒
              config.ReadWriteTimeoutInMillis = 50000;
  
              BosClient client = new BosClient(config);
          }
      }
  }