US3 SDK for iOS

概要

本文档主要是US3 (原名UFile) SDK for iOS的使用说明文档，下面我们从以下几个方面做介绍：

目录结构
环境要求
安装使用
功能说明
常见问题
联系我们

目录结构

该仓库主要包括SDK的源码以及示例项目，示例项目包含Objective-C和Swift两个版本。

目录	说明
`SDK/UFileSDK`	SDK源码
`SDK/UFileSDK/UFileSDKTests`	SDK各个功能的单元测试
`SDK/documents/devDocuments.zip`	SDK开发文档(解压后可用浏览器查看)
`SDK/Demos/OC/UFileSDKDemo`	Demo程序(`Objective-c`版本)
`SDK/Demos/Swift/UFileSDKDemo-swift`	Demo程序(`Swift`版本)

环境要求

iOS系统版本>=11.0
必须是UCloud的用户，并开通了US3服务。

安装使用

cocoapods方式

在你项目的Podfile中加入以下依赖：

pod 'UFileSDK'

使用方法

在工程中引入头文件:

#import <UFileSDK/UFileSDK.h>

注意，引入Framework后，需要在工程Build Settings的Other Linker Flags中加入-lc++ 。如下图所示

功能说明

文件操作功能

文件上传(以路径方式；以NSData方式；分片上传)
文件下载(下载指定范围文件数据；下载整个文件；下载文件到路径)
查询文件
删除文件
获取bucket下的文件列表(全部文件列表；指定前缀等条件的文件列表)
获取bucket下文件的下载地址(公有bucket空间下文件下载地址；私有bucket空间下文件下载地址)
获取文件的headfile信息(包括文件的mimetype,etag等)
获取文件的Etag
对比本地与远程文件的Etag

其操作类是UFFileClient.h,以上各个功能详细使用方法请查看SDK单元测试或者我们提供的Demo

后台下载功能

在项目的 Capability 中启用 Background Modes -> 勾选Background fetch.
在AppDelegate里添加下面的代码：

// 后台下载任务全部完成时回调
- (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void (^)(void))completionHandler;

代码示例

文件管理

假设此时，US3的控制台上你已经创建好了Bucket。下面我们介绍一下如何进行文件操作。

首先创建一个文件操作类,需要传入配置信息(主要是bucket配置信息)：

#import <UFileSDK/UFileSDK.h>

 // 使用本地签名，不推荐使用这种方式
UFConfig *ufConfig = [UFConfig instanceConfigWithPrivateToken:@"bucket私钥" publicToken:@"bucket公钥" bucket:@"bucket名称" fileOperateEncryptServer:nil fileAddressEncryptServer:nil proxySuffix:@"域名后缀" isHttps:YES];
    
 // 使用服务器签名，推荐使用
UFConfig *ufConfig = [UFConfig instanceConfigWithPrivateToken:nil publicToken:@"bucket公钥" bucket:@"bucket名称" fileOperateEncryptServer:@"文件操作签名服务器" fileAddressEncryptServer:@"获取文件URL的签名服务器" proxySuffix:@"域名后缀" isHttps:YES];
UFFileClient *fileClient =  [UFFileClient instanceFileClientWithConfig:ufConfig];

文件管理操作时，你所操作的bucket空间就是你在创建UFFileClient时所配置的bucket。下面我们示例一个简单的文件上传：

// 上传文件(以路径方式)
NSString*  fileName = @"initscreen.jpg";
NSString* strPath = [[NSBundle mainBundle] pathForResource:@"initscreen" ofType:@"jpg"];
    
[_fileClient uploadWithKeyName:fileName filePath:strPath mimeType:@"image/jpeg" progress:^(NSProgress * _Nonnull progress) {
        
    } uploadHandler:^(UFError * _Nullable ufError, UFUploadResponse * _Nullable ufUploadResponse) {
    if(!ufError){
    	// 你的上传成功逻辑
	   return;
    }
    // 根据ufError处理失败信息
    }];

服务器签名

此处特别强调：我们推荐使用服务端签名。服务端签名示例代码地址 ufile-sdk-auth-server ,你可以直接把它部署到你的服务器上配置好参数后在移动端使用。

Demo程序

我们在demo程序中，演示了文件操作的所有功能，你可以在本工程中查看其具体流程。另外，为了能更好的理解并使用UFile SDK，我们在此还提供了UFileSDKDemo说明文档

常见问题

iOS 9+强制使用HTTPS,使用XCode创建的项目默认不只支持HTTP，所以需要在project build info 添加NSAppTransportSecurity,在NSAppTransportSecurity下添加NSAllowsArbitraryLoads值设为YES,如下图。

版本记录

UFileSDK release history

联系我们

UCloud官方网站: https://www.ucloud.cn/
如有任何问题，欢迎提交issue或联系我们的技术支持，我们会第一时间解决问题。

许可证

Apache License 2.0

ucloud / ufile-sdk-ios