PCloud Swift SDK
官方pCloud Swift SDK，可用于iOS和macOS集成到pCloud API。您可以在此处找到完整的文档。
目录
迁移到v3
有关如何将SDK迁移到v3的说明，请参阅源存储库中v3.0.0的发布说明。
系统要求
- iOS 9.0+
- macOS 10.11+
- Xcode 10.2+
开始
注册应用
为了使用此SDK，您必须在
pCloud应用控制台中注册您的应用。请注意，创建后记住在您应用的首页中的应用密钥。
配置应用
SDK使用OAuth 2.0访问令牌来授权对pCloud API的请求。您可以使用SDK的授权流程来获取令牌。为了允许SDK执行此操作，在您的应用配置页面的“重定向URI”部分中查找并添加以下格式的URI：https://YOUR_APP_KEY://oauth2redirect其中YOUR_APP_KEY是从您的应用控制台获取的应用密钥。
安装SDK
您可以使用以下任何一种方法将SDK集成到项目中。
使用 CocoaPods
CocoaPods 是 Swift 和 Objective-C Cocoa 项目的依赖管理工具。如果您尚未使用 CocoaPods，您可以在此处了解如何入门。
首先，您应该安装 CocoaPods
$ gem install cocoapods然后，导航到您的项目根目录并运行 pod init。这将创建一个名为 Podfile 的文件。打开它，并向您的目标添加 pod 'PCloudSDKSwift'。您的 Podfile 应该看起来像这样。
use_frameworks!
target 'YOUR_TARGET_NAME' do
pod 'PCloudSDKSwift'
end然后，运行以下命令以安装 SDK 并将其集成到项目中
pod install一旦 SDK 集成到项目中，您可以使用以下命令获取 SDK 更新
pod updateCarthage
Carthage 是一个简单的、去中心化的 Cocoa 项目的依赖管理工具。如果您尚未使用 Carthage，您可以在此处了解如何安装它。
要使用 Carthage 安装 pCloud Swift SDK，您需要在项目（此文件列出了您想在项目中使用的框架）中创建一个 Cartfile，内容如下
github "https://github.com/pcloud/pcloud-sdk-swift"
然后，运行以下命令（这将将依赖项提取到 Carthage/Checkouts 文件夹中，并为每个依赖项构建）
iOS
carthage update --platform iOS在 Xcode 中的项目导航器中，选择您的项目，然后选择您的目标，然后导航到 通用 > 链接的框架和库，并从 Carthage/Build/iOS 拖放 PCloudSDKSwift.framework。
然后，在您的应用目标的 构建阶段 设置标签页中，点击 + 按钮，选择 新运行脚本阶段。在新创建的 运行脚本 部分中，将以下代码添加到脚本主体区域
/usr/local/bin/carthage copy-frameworks然后，导航到 输入文件 部分，并添加框架的路径
$(SRCROOT)/Carthage/Build/iOS/PCloudSDKSwift.frameworkmacOS
carthage update --platform Mac在Xcode的项目导航器中，选择您的项目，然后导航到 通用 > 链接框架和库，然后将 PCloudSDKSwift.framework 从 Carthage/Build/Mac拖放到那里。
然后，在您的应用目标“构建阶段”设置选项卡的“新建 Copy Files 阶段”，点击 + 图标并选择 新建 Copy Files 阶段。在新创建的“复制文件”部分，点击 目标 下拉菜单并选择 产品目录，然后从 Carthage/Build/Mac 拖放 PCloudSDKSwift.framework.dSYM。
Swift Package Manager
您可以使用 Swift 包管理器 将 pCloud SDK 集成到项目中。当前，仅对 iOS 平台添加了 SPM 支持。要将 SDK 集成到项目中，您需要指定存储库的 URL。
https://github.com/pCloud/pcloud-sdk-swift有关更多信息，请参阅 官方文档。
初始化 SDK
一旦集成到项目中，SDK 就需要验证用户身份，以便进行 API 调用。
使用授权流程
SDK 为获取用户信息定义了预定义流程。如果当前操作系统版本允许，它尝试通过 ASWebAuthenticationSession 验证用户。否则，它将在您的应用中打开一个网页并加载 pCloud 授权页面，用户可以在其中登录并授权您的应用。要使用授权流程
初始化 PCloud 实例
在应用代理中
iOS
import PCloudSDKSwift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
PCloud.setUp(withAppKey: "YOUR_APP_KEY")
}macOS
import PCloudSDKSwift
func applicationDidFinishLaunching(_ notification: Notification) {
PCloud.setUp(withAppKey: "YOUR_APP_KEY")
}执行授权流程
要开始授权流程，请调用 PCloud.authorize(with:_:) 并提供一个视图控制器和一个在授权完成或用户取消时调用的代码块。完成代码块之前，视图控制器会自动消失。
从你的视图控制器
iOS
import PCloudSDKSwift
// Inside a UIViewController subclass.
func logInButtonTapped(_ sender: UIButton) {
PCloud.authorize(with: self) { result in
if case .success(_) = result {
// You can make calls via the SDK.
}
}
}这将尝试使用 ASWebAuthenticationSession 进行认证，或者将使用传递给方法的视图控制器呈现一个包含 Web 视图的视图控制器。
macOS
import PCloudSDKSwift
// Inside an NSViewController subclass.
func logInButtonTapped(_ sender: NSButton) {
PCloud.authorize(with: self) { result in
if case .success(_) = result {
// You can make calls via the SDK.
}
}
}这将尝试使用 ASWebAuthenticationSession 进行认证，或者将使用传递给方法的视图控制器以弹出的方式呈现一个包含 Web 视图的视图控制器。
一旦PCloud.authorize(with:_:)成功完成，您就可以通过全局的PCloudClient实例调用API了，该实例可通过PCloud.sharedClient访问。此外，您的访问令牌存储在设备的密钥链中，所以下次您的应用程序启动时，共享的客户端实例会在PCloud.setUp(withAppKey:)调用中初始化。
手动创建客户端
这是一种更灵活地使用SDK的方法。但是，这需要您做更多的工作。使用这种方法也将访问令牌的管理委托给您。您可以手动创建一个带有访问令牌的PCloudClient实例。在某些情况下，手动管理此实例的生命周期可能更加方便。要请求访问令牌而无需自动初始化共享客户端实例
OAuth.performAuthorizationFlow(with: anchor, appKey: "YOUR_APP_KEY") { result in
if case .success(let user) = result {
let client = PCloud.createClient(with: user)
// Use the client.
}
}其中anchor将是iOS上的UIWindow实例或在macOS上的NSWindow实例。此方法将尝试通过ASWebAuthenticationSession进行认证，这是推荐的认证方式。但是，这需要iOS 13 / macOS 10.15。另一个选项是使用
OAuth.performAuthorizationFlow(with: view, appKey: "YOUR_APP_KEY") { result in
if case .success(let user) = result {
let client = PCloud.createClient(with: user)
// Use the client.
}
}其中view将是iOS上的WebViewControllerPresenterMobile实例或在macOS上的WebViewControllerPresenterDesktop实例。
进行API请求数据
一旦您拥有授权的客户端，您可以使用SDK尝试进行一些API请求数据。首先，创建对您的PCloudClient实例的引用
let client = PCloud.sharedClient // When using the authorization flow处理网络任务
SDK包含了最常见的API请求数据预定义，并通过PCloudClient实例作为方法公开了它们。每个方法返回一个非运行的任务对象，表示API请求数据。一旦您获得了任务，您可以给它分配回调块并启动它。任务完成后，将生成一个Result值。
有三种类型的任务
CallTask
执行RPC请求。成功时生成请求的预先解析响应。失败时，生成一个CallError值。
import PCloudSDKSwift
client.createFolder(named: "Movies", inFolder: Folder.root)
.addCompletionBlock { result in
// Handle result
}
.start()UploadTask
执行上传。成功时生成上传文件的元数据。失败时，生成一个CallError值。
import PCloudSDKSwift
client.upload(fromFileAt: "file:///path/to/file", toFolder: Folder.root, asFileNamed: "song.mp3")
.addProgressBlock { uploaded, total in
// Handle progress
}
.addCompletionBlock { result in
// Handle result
}
.start()DownloadTask
下载文件。成功时，生成下载文件的URL。失败时，生成一个NetworkOperationError值。
import PCloudSDKSwift
let link: FileLink.Metadata
client.downloadFile(from: link.address, downloadTag: link.downloadTag, to: { path in
// Move the file
})
.addCompletionBlock { result in
// Handle completion
}
.addProgressBlock { written, total in
// Handle progress
}
.start()
任务一旦开始，如果成功、失败或被取消，都可以停止。由于任务不可重复使用，一旦任务以任何方式停止运行，就不能再次启动。如果任务失败或成功，将只会调用任务的完成块，不会在被取消时调用。此外，任务的所有回调块都在主队列上调用。任务将保留在内存中直到运行完成，因此您启动任务时不需要手动保持对其的引用。
处理API错误
上传和RPC调用任务会失败并返回一个CallError。该枚举结合了来自网络层和PCloud API层的可能错误。其中一个可能的错误是CallError<T>.methodError(T)，而该子错误将取决于任务执行的API方法。所有API方法都在PCloudAPI.swift中定义，并且在它们的命名空间中每个都有一个定义的Error枚举。所以，例如，如果你正在执行ListFolder API方法，任务错误将定义为CallError<ListFolder.Error>。一些API方法（例如UserInfo）除了通用API错误外不能以任何其他方式失败，因此它们将定义其错误为NullError。这样的任务永远不会失败与CallError<T>.methodError(T)。
示例
示例应用程序可以在Example_iOS文件夹中找到。该示例应用程序演示了如何验证用户身份，以及如何列出用户的文件和文件夹。