Uploadcare 的 Swift API 客户端

license Build and test

Uploadcare Swift API 客户端适用于 iOS、iPadOS、tvOS 和 macOS，通过封装 Uploadcare 上传和 REST API 来处理文件上传和后续操作。

查看我们的演示应用。

安装

Swift Package Manager

要使用稳定版本，请将依赖项添加到您的 Package.swift 文件中

dependencies: [
    .package(url: "https://github.com/uploadcare/uploadcare-swift.git", .branch("master"))
]

如果您想尝试当前的开发版本，请将依赖项更改为

dependencies: [
    .package(url: "https://github.com/uploadcare/uploadcare-swift.git", branch("develop"))
]

要从 Xcode 添加，请选择 File -> Swift Packages -> Add Package Dependency 并输入仓库 URL

https://github.com/uploadcare/uploadcare-swift

或者您可以在 Xcode 中使用该 URL 将其添加到包列表中：https://github.com/uploadcare/uploadcare-swift（选择 master 分支）。

Carthage

要使用稳定版本，请将依赖项添加到您的 Cartfile

github "uploadcare/uploadcare-swift"

要使用当前的开发版本

github "uploadcare/uploadcare-swift" "develop"

Cocoapods

要使用稳定版本，请将依赖项添加到您的 Podfile

pod 'Uploadcare', git: 'https://github.com/uploadcare/uploadcare-swift'

要使用当前的开发版本

pod 'Uploadcare', git: 'https://github.com/uploadcare/uploadcare-swift', :branch => 'develop'

初始化

在 Uploadcare 仪表板 中创建您的项目，并从那里复制其 API 密钥。

上传 API 只需要公钥，而 REST API 则需要公钥和私钥

final class MyClass {
    private var uploadcare: Uploadcare
    
    init() {
        self.uploadcare = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY")
        
        // Secret key is optional if you want to use Upload API only.
        // REST API requires both public and secret keys:
        self.uploadcare = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY", secretKey: "YOUR_SECRET_KEY")
    }
}

如果需要在您的 Uploadcare 帐户中使用多个项目，您可以创建更多 Uploadcare 对象

final class MyClass {
    private let project1: Uploadcare
    private let project2: Uploadcare
    
    init() {
        // A project to use Upload API only 
        self.project1 = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY_1")

        // A project to use both REST API and Upload API
        self.project2 = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY_2", secretKey: "YOUR_SECRET_KEY_2")
    }
}

请记住，由于 Uploadcare 不是单例模式。您应该存储对您的 Uploadcare 对象的强引用（例如作为实例变量），否则它将被释放。

使用上传 API

查看 上传 API 文档 以查看所有可用的方法。每种方法都有一个带有 Result 完成处理程序的实现，并且有一个替代的 async 实现用于 Swift 并发。

上传示例

guard let url = URL(string: "https://ucarecdn.com/46528d0d-323c-42d7-beab-2fdc5e7077ba/") else { return }
guard let data = try? Data(contentsOf: url) else { return }

// You can create an UploadedFile object to operate with it
var fileForUploading1 = uploadcare.file(fromData: data)
fileForUploading2.metadata = ["myKey": "myValue"]
try await fileForUploading1.upload(withName: "random_file_name.jpg", store: .auto)

// Or you can just upload data and provide a filename

var fileForUploading2 = uploadcare.file(withContentsOf: url)!
let file = try await uploadcare.uploadFile(data, withName: "random_file_name.jpg", store: .auto) { progress in
    print("upload progress: \(progress * 100)%")
}

// Same method with a completion callback that returns a task that can be paused or canceled:
let task = uploadcare.uploadFile(data, withName: "random_file_name.jpg", store: .auto, metadata: ["someKey": "someMetaValue"]) { progress in
    print("upload progress: \(progress * 100)%")
} _: { result in
    switch result {
    case .failure(let error):
        print(error.detail)
    case .success(let file):
        print(file)
    }
}
// Cancel uploading if needed
task.cancel()

// task will confirm UploadTaskable protocol if file size is less than 100 mb, and UploadTaskResumable if file size is >= 100mb
// You can pause or resume uploading of file with size >= 100mb if needed
(task as? UploadTaskResumable)?.pause()
(task as? UploadTaskResumable)?.resume()

可以在后台执行上传。但是实现是特定于平台的。此库不提供默认实现。您可以在我们的演示应用中找到 iOS 的示例。请参阅 FilesListStore.swift。

使用 REST API

请参阅 REST API 文档 以了解所有方法。每种方法都有一个带有 Result 完成处理程序的实现，并且有一个替代的 async 实现用于 Swift 并发。

获取文件列表的示例

// Make a list of files object
lazy var filesList = uploadcare.listOfFiles()

func someFilesListMethod() {
    // Make a query object
    let query = PaginationQuery()
        .stored(true)
        .ordering(.dateTimeUploadedDESC)
        .limit(5)

    // Get file list
    let list = try await filesList.get(withQuery: query)
    
    // Same method with a completion callback.
    filesList.get(withQuery: query) { result in
        switch result {
        case .failure(let error):
            print(error)
        case .success(let list):
            print(list)
        }
    }
}

获取下一页

// Check if the next page is available
guard filesList.next != nil else { return }

// Async:
let next = try await filesList.nextPage()

// With a completion callback:
filesList.nextPage { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let list):
        print(list)
    }
}

获取上一页

// Check if the previous page is available
guard filesList.previous != nil else { return }

// Async:
let previous = try await filesList.previousPage()

// With a completion callback:
filesList.previousPage { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let list):
        print(list)
    }
}

演示应用

查看 演示应用 以获取使用示例

实用链接

Swift 上传 API 客户端文档
Swift REST API 客户端文档
Uploadcare 文档
上传 API 参考
REST API 参考
贡献指南
安全策略
支持