全部产品
Search

搜索本产品

    对象存储 OSS：iOS初始化

    文档中心

    对象存储 OSS：iOS初始化

    更新时间：Sep 11, 2024

    OSSClient是OSS服务的iOS客户端，为调用者提供了一系列的方法进行操作、管理存储空间（Bucket）和文件（Object）等。在使用SDK发起对OSS的请求前，您需要初始化一个OSSClient实例，并对OSSClient实例进行必要设置。

    说明

    OSSClient的生命周期需与应用程序的生命周期保持一致。即您需要在应用启动时创建一个全局的OSSClient，在应用结束时销毁OSSClient。

    初始化OSSClient

    重要

    移动终端是一个不受信任的环境，把AccessKeyId和AccessKeySecret直接保存在终端用来加签请求，存在极高的风险。推荐使用STS鉴权模式或自签名模式。

    您可以通过以下多种方式新建OSSClient。

    使用STS新建OSSClient

    以下代码用于使用STS新建OSSClient。

    // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
NSString *endpoint = @"yourEndpoint";
// 从STS服务获取的临时访问密钥（AccessKey ID和AccessKey Secret）。
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// 从STS服务获取的安全令牌（SecurityToken）。
NSString *securityToken = @"yourSecurityToken";

id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider];

    使用自定义域名新建OSSClient

    以下代码用于使用自定义域名新建OSSClient。

    // yourEndpoint填写自定义域名。
NSString *endpoint = @"yourEndpoint";
// 从STS服务获取的临时访问密钥（AccessKey ID和AccessKey Secret）。
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// 从STS服务获取的安全令牌（SecurityToken）。
NSString *securityToken = @"yourSecurityToken";

id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider];

    专有云或专有域环境新建OSSClient

    以下代码用于在专有云或专有域环境新建OSSClient。

    // yourEndpoint填写Bucket所在地域对应的Endpoint。
NSString *endpoint = @"yourEndpoint";
// 从STS服务获取的临时访问密钥（AccessKey ID和AccessKey Secret）。
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// 从STS服务获取的安全令牌（SecurityToken）。
NSString *securityToken = @"yourSecurityToken";

id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClientConfiguration *configuration = [OSSClientConfiguration new];
// 跳过CNAME解析。
configuration.cnameExcludeList = @[endpoint];
OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider clientConfiguration:configuration];

    配置OSSClient

    ClientConfiguration是OSSClient的配置类，您可通过此类来配置代理、连接超时、最大连接数等参数。

    参数

    描述

    方法

    maxRetryCount

    请求失败后最大的重试次数。默认3次。

    configuration.maxRetryCount

    maxConcurrentRequestCount

    最大并发数。默认为5。

    configuration.maxConcurrentRequestCount

    enableBackgroundTransmitService

    是否开启后台任务，默认不开启。

    configuration.enableBackgroundTransmitService

    backgroundSesseionIdentifier

    自定义后台会话标识符，默认值为com.aliyun.oss.backgroundsession。

    configuration.backgroundSesseionIdentifier

    isHttpdnsEnable

    是否开启httpDns。

    • true：2.10.14及以下版本默认开启httpDns。

    • false：2.10.14及以上版本默认关闭httpDns。

    configuration.isHttpdnsEnable

    timeoutIntervalForRequest

    请求超时时间，默认15秒。

    configuration.timeoutIntervalForRequest

    timeoutIntervalForResource

    资源超时时间，默认7天。

    configuration.timeoutIntervalForResource

    proxyHost

    代理服务器主机地址。

    configuration.proxyHost

    proxyPort

    代理服务器端口。

    configuration.proxyPort

    userAgentMark

    用户代理中HTTP的User-Agent头。

    configuration.userAgentMark

    cnameExcludeList

    列表中的元素将跳过CNAME解析。

    configuration.cnameExcludeList

    crc64Verifiable

    是否开启CRC64校验。取值如下：

    • YES：开启CRC64校验。

    • NO（默认值）：关闭CRC64校验。

    configuration.crc64Verifiable

    isAllowUACarrySystemInfo

    是否允许User-Agent携带系统信息。取值如下：

    • YES：允许User-Agent携带系统信息。

    • NO（默认值）：不允许User-Agent携带系统信息。

    configuration.isAllowUACarrySystemInfo

    isFollowRedirectsEnable

    是否开启HTTP重定向。取值如下：

    • YES：开启HTTP重定向。

    • NO（默认值）：关闭HTTP重定向。

    configuration.isFollowRedirectsEnable

    以下代码用于使用ClientConfiguration配置OSSClient参数。

    // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
NSString *endpoint = @"yourEndpoint";
// 从STS服务获取的临时访问密钥（AccessKey ID和AccessKey Secret）。
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// 从STS服务获取的安全令牌（SecurityToken）。
NSString *securityToken = @"yourSecurityToken";

id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClientConfiguration *configuration = [OSSClientConfiguration new];
// 请求失败后最大的重试次数。
configuration.maxRetryCount = 3;
// 最大并发数。
configuration.maxConcurrentRequestCount = 3;
// 是否开启后台任务。
configuration.enableBackgroundTransmitService = YES;
// 自定义后台会话标识符。
configuration.backgroundSesseionIdentifier = @"yourBackgroundSesseionIdentifier";
// 是否开启httpDns。
configuration.isHttpdnsEnable = YES;
// 请求超时时间。
configuration.timeoutIntervalForRequest = 15;
// 资源超时时间。
configuration.timeoutIntervalForResource = 24 * 60 * 60;
// 代理服务器主机地址。
configuration.proxyHost = @"yourProxyHost";
// 代理服务器端口。
configuration.proxyPort = @8080;
// 用户代理中HTTP的User-Agent头。
configuration.userAgentMark = @"yourUserAgent";
// 列表中的元素将跳过CNAME解析。
configuration.cnameExcludeList = @[@"yourCname"];
// 是否开启CRC校验。
configuration.crc64Verifiable = YES;
// 是否允许User-Agent携带系统信息。
configuration.isAllowUACarrySystemInfo = YES;
// 是否开启HTTP重定向。
configuration.isFollowRedirectsEnable = NO;

OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider clientConfiguration:configuration];

    启用日志

    移动端的使用环境比较复杂，部分区域或某个时段会出现无法正常使用OSS SDK的情况。为了进一步定位开发者遇到的问题，OSS SDK在开启日志记录功能后，会将日志信息记录在本地。使用OSSClient前完成初始化，并调用如下方法开启日志记录。

    // 日志样式。
//2017/10/25 11:05:43:863  [Debug]: 第17次：<NSThread: 0x7f8099108580>{number = 3, name = (null)}
//2017/10/25 11:05:43:863  [Debug]: 第15次：<NSThread: 0x7f80976052c0>
//2017/10/25 11:05:43:863  [Debug]: ----------TestDebug------------
// 开启日志记录。
[OSSLog enableLog];
    说明

    • 日志文件存储在沙盒的Caches/OSSLogs文件夹内。

    • 您可以自行选择将文件上传至服务器，或者选择接入阿里云日志服务上传日志文件。

    OSSTask

    1. 所有调用API操作均会返回一个OSSTask。

      OSSTask * task = [client getObject:get];

    2. 设置OSSTask。

      • 为OSSTask设置延续 (continuation) 以实现异步回调。

        [task continueWithBlock: ^(OSSTask *task) {
    // do something
    ...
    return nil;
}];

      • 等待OSSTask完成以实现同步回调。

        [task waitUntilFinished];