初始化

更新时间：2022-05-19

快速入门

初始化BOSClient。

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

示例代码：

BCECredentials* credentials = [[BCECredentials alloc] init];
// access key和secret key分别代表AKSK。
credentials.accessKey = @"<access key>";
credentials.secretKey = @"<secret key>";

BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
configuration.endpoint = @"https://bcebos.cloud.geely.com";
configuration.credentials = credentials;

BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];

新建一个Bucket。

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

示例代码：

BCETask* task = [client putBucket:@"<bucketName>"];

// 任务可以异步执行。
task.then(^(BCEOutput* output) {
  // 可以在block内判断任务执行的结果。
  if (output.response) {
      // 任务执行成功。
  }

  if (output.error) {
      // 任务执行失败。
  }

  if (output.progress) {
      // 任务执行进度。
  }
});

// 可以同步方式，等待任务执行完毕。
[task waitUtilFinished];

上传Object。

Object是BOS中最基本的数据单元，您可以把Object简单的理解为文件。

示例代码：

BOSObjectContent* content = [[BOSObjectContent alloc] init];
// 以下两行设置一种。
content.objectData.file = @"<FilePath>";
content.objectData.data = <NSData object>;

BOSPutObjectRequest* request = [[BOSPutObjectRequest alloc] init];
request.bucket = @"<bucketname>";
request.key = @"<ObjectName>";
request.objectContent = content;

__block BOSPutObjectResponse* response;
BCETask* task = [client putObject:request];
task.then(^(BCEOutput* output) {
    if (output.progress) {
        // 打印进度
        NSLog(@"put object progress is %@", output.progress);
    }

    if (output.response) {
        response = (BOSPutObjectResponse*)output.response;
        // 打印eTag
        NSLog(@"The eTag is %@", response.metadata.eTag);
    }

    if (output.error) {
        NSLog(@"put object failure with %@", output.error);
    }
});

[task waitUtilFinished];

查看Bucket下的Object列表。

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

示例代码：

// 获取指定Bucket下的所有Object信息
BOSListObjectsRequest* request = [[BOSListObjectsRequest alloc] init];
request.bucket = @"<bucketname>";

__block BOSListObjectsResponse* response = nil;
BCETask* task = [client listObjects:request];
task.then(^(BCEOutput* output) {
  if (output.response) {
      response = (BOSListObjectsResponse*)output.response;
      for (BOSObjectInfo* object in response.contents) {
         NSLog(@"The object key is %@", object.key);
      }
  }

  if (output.error) {
      NSLog(@"list objects failure with %@", output.error);
  }
});

获取指定Object

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

示例代码：

BOSGetObjectRequest* request = [[BOSGetObjectRequest alloc] init];
request.bucket = @"<bucketname>";
request.key = @"<Objectname>";
request.file = @"<filename>";

__block BOSGetObjectResponse* response = nil;
BCETask* task = [self.client getObject:request];
task.then(^(BCEOutput* output) {
    // ...
});

完整示例

#import <BaiduBCEBasic/BaiduBCEBasic.h>
#import <BaiduBCEBOS/BaiduBCEBOS.h>

void example(void) {
// 初始化
BCECredentials* credentials = [[BCECredentials alloc] init];
credentials.accessKey = @"<access key>";
credentials.secretKey = @"<secret key>";
BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
configuration.credentials = credentials;

BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];

// 1. 新建bucket
BCETask* task = [client putBucket:@"<bucketName>"];
task.then(^(BCEOutput* output) { // 任务可以异步执行。
    if (output.response) {
        // 任务执行成功。
    }

    if (output.error) {
        // 任务执行失败。
    }

    if (output.progress) {
        // 任务执行进度。
    }
});
[task waitUtilFinished]; // 可以同步方式，等待任务执行完毕。

// 2. 上传Object
BOSObjectContent* content = [[BOSObjectContent alloc] init];
content.objectData.file = @"<FilePath>";

BOSPutObjectRequest* request = [[BOSPutObjectRequest alloc] init];
request.bucket = @"<bucketname>";
request.key = @"<Objectname>";
request.objectContent = content;

__block BOSPutObjectResponse* response = nil;
task = [client putObject:request];
task.then(^(BCEOutput* output) {
    if (output.progress) {
        // 打印进度
        NSLog(@"put object progress is %@", output.progress);
    }

    if (output.response) {
        response = (BOSPutObjectResponse*)output.response;
        // 打印eTag
        NSLog(@"The eTag is %@", response.metadata.eTag);
    }

    if (output.error) {
        NSLog(@"put object failure with %@", output.error);
    }
});
[task waitUtilFinished];

// 3. 查看Object
BOSListObjectsRequest* listRequest = [[BOSListObjectsRequest alloc] init];
listRequest.bucket = @"<bucketname>";

__block BOSListObjectsResponse* listRepsponse = nil;
task = [client listObjects:listRequest];
task.then(^(BCEOutput* output) {
    if (output.response) {
        listRepsponse = (BOSListObjectsResponse*)output.response;
        for (BOSObjectInfo* object in listRepsponse.contents) {
            NSLog(@"The object key is %@", object.key);
        }
    }

    if (output.error) {
        NSLog(@"list objects failure with %@", output.error);
    }
});
[task waitUtilFinished];

// 4. 下载Object
BOSGetObjectRequest* getRequest = [[BOSGetObjectRequest alloc] init];
getRequest.bucket = @"<bucketname>";
getRequest.key = @"<Objectname>";
getRequest.file = @"<file>";

__block BOSGetObjectResponse* getResponse = nil;
task = [client getObject:getRequest];
task.then(^(BCEOutput* output) {
    if (output.response) {
        getResponse = (BOSGetObjectResponse*)output.response;
    }

    if (output.error) {
        NSLog(@"get object failure with %@", output.error);
    }
});
[task waitUtilFinished];

}

新建BOSClient

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

基本流程
1. 确定服务区域，如北京是BCERegionBJ，广州是BCERegionGZ，苏州是BCERegionSU；
2. 创建一个BCECredentials, 并设置accessKey和secretKey字段；
3. 创建一个BOSClientConfiguration实例，并设置credentials字段；
4. 将配置好的BOSClientConfiguration传入BOSClient。
示例代码

用户可以参考如下代码新建一个BOSClient：
```
BCECredentials* credentials = [[BCECredentials alloc] init];
credentials.accessKey = @"<access key>";
credentials.secretKey = @"<secret key>";

BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
configuration.region = [BCERegion region:BCERegionBJ];
configuration.credentials = credentials;

BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];
```
注意：region参数只能定义为规定的枚举值，不指定时默认为北京区域。云平台目前开放了多区域支持，请参考区域选择说明。

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

新建带有STS验证的BOSClient

iOS SDK主要用于移动端开发的场景，而对于移动端的鉴权，如您直接将您的AK/SK泄露给移动端，势必会给账户带来安全隐患，因此推荐您使用STS方式实现移动端的鉴权。STS的详细介绍请参考临时授权访问。

使用STS方式需要您在调用API时首先创建带有STS的BOSClient来执行，目前支持通过STS方式调用的BOS API接口请参见[STS 服务接口](BOS/API参考/访问控制.md#STS 服务接口)。

示例代码：

BCESTSCredentials* credentials = [[BCESTSCredentials alloc] init];
credentials.accessKey = @"<access key>"; // 临时返回的AK
credentials.secretKey = @"<secret key>"; // 临时返回的SK
credentials.sessionToken = @"<session token>"; // 临时返回的SessionToken

BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
configuration.credentials = credentials;

BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];

说明：下述代码示例中，均使用原始AK/SK创建BOSClient举例，如您需要使用带有STS验证的BOSClient，可以在创建BOSClient时，按照上述方法执行。

配置HTTPS协议访问BOS

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

configuration.scheme = @"https";

配置BOSClient

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

设置网络参数

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

示例代码

BOSClientConfiguration config = [[BOSClientConfiguration alloc] init];

// 设置HTTP最大连接数为5
config.maxConurrentConnection = 5;

// 设置TCP连接超时为5秒
config.connectionTimeout = 5;

// 设置请求最长传输数据时间为60秒
config.totalTransferTimeout = 60;

参数说明

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

参数	说明
authVersion	使用的鉴权算法版本，目前默认值 1
APIVersion	使用BOS API版本，目前默认值 1
scheme	使用的HTTP协议，可取http和https，默认值 http
region	使用BOS服务的区域
endpoint	如果知道明确的服务地址，可以不设置scheme和region等，直接设置endpoint
allowsCellularAccess	是否允许使用蜂窝网络，默认值 NO
connectionTimeout	设置TCP连接超时，默认值 60s
totalTransferTimeout	设置请求最长传输数据时间, 单位秒，默认值7天
maxConurrentConnection	允许打开的最大HTTP连接数。

安装SDK工具包

Bucket管理