初始化

更新时间：2025-08-21

快速入门

初始化BOSClient。

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

新建带有STS验证方式的BOSClient：

示例代码：

Swift

1BCESTSCredentials* credentials = [[BCESTSCredentials alloc] init];
2 // access key和secret key分别代表AKSK。
3credentials.accessKey = @"<access key>"; // 临时返回的AK
4credentials.secretKey = @"<secret key>"; // 临时返回的SK
5credentials.sessionToken = @"<session token>"; // 临时返回的SessionToken
6
7BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
8configuration.credentials = credentials;
9
10BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];

新建一个Bucket。

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

示例代码：

Swift

1BCETask* task = [client putBucket:@"<bucketName>"];
2
3// 任务可以异步执行。
4task.then(^(BCEOutput* output) {
5  // 可以在block内判断任务执行的结果。
6  if (output.response) {
7      // 任务执行成功。
8  }
9
10  if (output.error) {
11      // 任务执行失败。
12  }
13
14  if (output.progress) {
15      // 任务执行进度。
16  }
17});
18
19// 可以同步方式，等待任务执行完毕。
20[task waitUtilFinished];

上传Object。

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

示例代码：

Swift

1BOSObjectContent* content = [[BOSObjectContent alloc] init];
2// 以下两行设置一种。
3content.objectData.file = @"<FilePath>";
4content.objectData.data = <NSData object>;
5
6BOSPutObjectRequest* request = [[BOSPutObjectRequest alloc] init];
7request.bucket = @"<bucketname>";
8request.key = @"<ObjectName>";
9request.objectContent = content;
10
11__block BOSPutObjectResponse* response;
12BCETask* task = [client putObject:request];
13task.then(^(BCEOutput* output) {
14    if (output.progress) {
15        // 打印进度
16        NSLog(@"put object progress is %@", output.progress);
17    }
18
19    if (output.response) {
20        response = (BOSPutObjectResponse*)output.response;
21        // 打印eTag
22        NSLog(@"The eTag is %@", response.metadata.eTag);
23    }
24
25    if (output.error) {
26        NSLog(@"put object failure with %@", output.error);
27    }
28});
29
30[task waitUtilFinished];

查看Bucket下的Object列表。

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

示例代码：

Swift

1// 获取指定Bucket下的所有Object信息
2BOSListObjectsRequest* request = [[BOSListObjectsRequest alloc] init];
3request.bucket = @"<bucketname>";
4
5__block BOSListObjectsResponse* response = nil;
6BCETask* task = [client listObjects:request];
7task.then(^(BCEOutput* output) {
8  if (output.response) {
9      response = (BOSListObjectsResponse*)output.response;
10      for (BOSObjectInfo* object in response.contents) {
11         NSLog(@"The object key is %@", object.key);
12      }
13  }
14
15  if (output.error) {
16      NSLog(@"list objects failure with %@", output.error);
17  }
18});

获取指定Object

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

示例代码：

Swift

1BOSGetObjectRequest* request = [[BOSGetObjectRequest alloc] init];
2request.bucket = @"<bucketname>";
3request.key = @"<Objectname>";
4request.file = @"<filename>";
5
6__block BOSGetObjectResponse* response = nil;
7BCETask* task = [self.client getObject:request];
8task.then(^(BCEOutput* output) {
9    // ...
10});

完整示例

Swift

1#import <BaiduBCEBasic/BaiduBCEBasic.h>
2#import <BaiduBCEBOS/BaiduBCEBOS.h>
3
4void example(void) {
5// 初始化带有STS验证的BOSClient
6 BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];
7    BCESTSCredentials* credentials = [[BCESTSCredentials alloc] init];
8     // access key和secret key分别代表AKSK。
9    credentials.accessKey = @"<access key>"; // 临时返回的AK
10    credentials.secretKey = @"<secret key>"; // 临时返回的SK
11    credentials.sessionToken = @"<session token>"; // 临时返回的SessionToken
12
13    BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
14    configuration.credentials = credentials;
15
16    BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];
17
18// 1. 新建bucket
19BCETask* task = [client putBucket:@"<bucketName>"];
20task.then(^(BCEOutput* output) { // 任务可以异步执行。
21    if (output.response) {
22        // 任务执行成功。
23    }
24
25    if (output.error) {
26        // 任务执行失败。
27    }
28
29    if (output.progress) {
30        // 任务执行进度。
31    }
32});
33[task waitUtilFinished]; // 可以同步方式，等待任务执行完毕。
34
35// 2. 上传Object
36BOSObjectContent* content = [[BOSObjectContent alloc] init];
37content.objectData.file = @"<FilePath>";
38
39BOSPutObjectRequest* request = [[BOSPutObjectRequest alloc] init];
40request.bucket = @"<bucketname>";
41request.key = @"<Objectname>";
42request.objectContent = content;
43
44__block BOSPutObjectResponse* response = nil;
45task = [client putObject:request];
46task.then(^(BCEOutput* output) {
47    if (output.progress) {
48        // 打印进度
49        NSLog(@"put object progress is %@", output.progress);
50    }
51
52    if (output.response) {
53        response = (BOSPutObjectResponse*)output.response;
54        // 打印eTag
55        NSLog(@"The eTag is %@", response.metadata.eTag);
56    }
57
58    if (output.error) {
59        NSLog(@"put object failure with %@", output.error);
60    }
61});
62[task waitUtilFinished];
63
64// 3. 查看Object
65BOSListObjectsRequest* listRequest = [[BOSListObjectsRequest alloc] init];
66listRequest.bucket = @"<bucketname>";
67
68__block BOSListObjectsResponse* listRepsponse = nil;
69task = [client listObjects:listRequest];
70task.then(^(BCEOutput* output) {
71    if (output.response) {
72        listRepsponse = (BOSListObjectsResponse*)output.response;
73        for (BOSObjectInfo* object in listRepsponse.contents) {
74            NSLog(@"The object key is %@", object.key);
75        }
76    }
77
78    if (output.error) {
79        NSLog(@"list objects failure with %@", output.error);
80    }
81});
82[task waitUtilFinished];
83
84// 4. 下载Object
85BOSGetObjectRequest* getRequest = [[BOSGetObjectRequest alloc] init];
86getRequest.bucket = @"<bucketname>";
87getRequest.key = @"<Objectname>";
88getRequest.file = @"<file>";
89
90__block BOSGetObjectResponse* getResponse = nil;
91task = [client getObject:getRequest];
92task.then(^(BCEOutput* output) {
93    if (output.response) {
94        getResponse = (BOSGetObjectResponse*)output.response;
95    }
96
97    if (output.error) {
98        NSLog(@"get object failure with %@", output.error);
99    }
100});
101[task waitUtilFinished];
102
103}

新建带有STS验证的BOSClient

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

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

使用STS方式需要您在调用API时首先创建带有STS的BOSClient来执行，目前支持通过STS方式调用的BOS API接口请参见STS 服务接口。

示例代码：

Swift

1BCESTSCredentials* credentials = [[BCESTSCredentials alloc] init];
2credentials.accessKey = @"<access key>"; // 临时返回的AK
3credentials.secretKey = @"<secret key>"; // 临时返回的SK
4credentials.sessionToken = @"<session token>"; // 临时返回的SessionToken
5
6BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
7configuration.region = [BCERegion region:BCERegionBJ];//服务区域，北京是BCERegionBJ，广州是BCERegionGZ，苏州是BCERegionSU，不指定默认为北京
8configuration.credentials = credentials;
9
10BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];

注意：

region参数只能定义为规定的枚举值，不指定时默认为北京区域。百度智能云目前开放了多区域支持，请参考区域选择说明。

目前支持 BOS 官网开放的区域。具体域名参考BOS region

新建带有AKSK验证的BOSClient

新建AKSK鉴权方式的bosclient与上文提到的sts方式类似。

示例代码：

Swift

1  BCECredentials* credentials = [[BCECredentials alloc] init];
2  credentials.accessKey = @"AK";
3  credentials.secretKey = @"SK";
4  
5  BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
6  configuration.credentials = credentials;
7  configuration.endpoint = @"http://bj.bcebos.com";
8  
9  BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];

配置HTTPS协议访问BOS

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

Swift

1configuration.scheme = @"https";

配置BOSClient

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

设置网络参数

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

示例代码

Swift

1BOSClientConfiguration config = [[BOSClientConfiguration alloc] init];
2
3// 设置HTTP最大连接数为5
4config.maxConurrentConnection = 5;
5
6// 设置TCP连接超时为5秒
7config.connectionTimeout = 5;
8
9// 设置请求最长传输数据时间为60秒
10config.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连接数。

配置访问域名风格

在v1.3.1版本之后，SDK会默认自动开启bucket virtual hosting。

path-style: ${region}.bcebos.com/${bucket}/${object}

virtual-hosted: {bucket}.${region}.bcebos.com/${object}

可以通过以下配置开启使用PathStyle风格的endpoint：

Swift

1BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
2configuration.isPathStyleAccessEnable = YES;

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

版本变更记录

Bucket管理

对象存储 BOS

对象存储 BOS

初始化

快速入门

完整示例

新建带有STS验证的BOSClient

新建带有AKSK验证的BOSClient

配置HTTPS协议访问BOS

配置BOSClient

配置访问域名风格