Install and use the Swift SDK to manage objects - Object Storage Service

Install the OSS SDK for Swift to manage buckets and objects, generate pre-signed URLs, and process images. This guide covers installation, credential setup, and five operations: create a bucket, upload, download, list, and delete objects.

Prerequisites

Before you begin, ensure that you have:

Swift 5.9 or later (supported on iOS, macOS, visionOS, watchOS, tvOS, Linux, and Windows)
An Alibaba Cloud account with an AccessKey pair (AccessKey ID and AccessKey secret)
An OSS bucket (required for upload, download, list, and delete operations)

Install the SDK

The SDK uses Swift Package Manager (SPM) for dependency management. Choose one of the following methods.

Add the dependency in Package.swift

Add the package to the dependencies array in your Package.swift file:

dependencies: [
    .package(url: "https://github.com/aliyun/alibabacloud-oss-swift-sdk-v2.git", from: "0.1.1")
]

Then add the product as a target dependency:

targets: [
    .target(
        name: "YourTarget",
        dependencies: [
            .product(name: "AlibabaCloudOSS", package: "alibabacloud-oss-swift-sdk-v2"),
            // .product(name: "AlibabaCloudOSSExtension", package: "alibabacloud-oss-swift-sdk-v2"),
        ]
    ),
]

The SDK provides two modules:

Module	Description
`AlibabaCloudOSS`	Bucket and object operations, paginators, and pre-signed URLs
`AlibabaCloudOSSExtension`	Configuration interfaces such as cross-origin resource sharing (CORS)

Add the dependency in Xcode

Open your project in Xcode. Go to Project > Package Dependencies and click +.
Enter https://github.com/aliyun/alibabacloud-oss-swift-sdk-v2.git in the search field and click Add Package.

Configure credentials

The SDK reads credentials from the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables through EnvironmentCredentialsProvider.

Set the environment variables in your terminal before running the examples:

export OSS_ACCESS_KEY_ID="<your-access-key-id>"
export OSS_ACCESS_KEY_SECRET="<your-access-key-secret>"

To set environment variables in Xcode, go to Product > Scheme > Edit Scheme, select Run, and add the variables under Environment Variables.

Basic operations

Each example creates a Configuration with credentials and region, initializes a Client, and calls the corresponding operation. Replace the following placeholders with your values:

Placeholder	Description	Example
`<region-id>`	The region where your bucket is located	`cn-hangzhou`
`<your-bucket-name>`	Your bucket name	`my-bucket`
`<your-object-key>`	The object key (path and file name)	`example/hello.txt`

Create a bucket

import AlibabaCloudOSS
import Foundation

func main() async throws {
    let region = "<region-id>"
    let bucket = "<your-bucket-name>"

    let config = Configuration.default()
        .withCredentialsProvider(EnvironmentCredentialsProvider())
        .withRegion(region)

    let client = Client(config)

    let result = try await client.putBucket(
        PutBucketRequest(bucket: bucket)
    )

    print("PutBucket done, StatusCode: \(result.statusCode), RequestId: \(result.requestId).")
}

try await main()

Upload an object

import AlibabaCloudOSS
import Foundation

func main() async throws {
    let region = "<region-id>"
    let bucket = "<your-bucket-name>"
    let key = "<your-object-key>"

    let config = Configuration.default()
        .withCredentialsProvider(EnvironmentCredentialsProvider())
        .withRegion(region)

    let client = Client(config)

    let content = "hi oss"

    let result = try await client.putObject(
        PutObjectRequest(
            bucket: bucket,
            key: key,
            body: .data(content.data(using: .utf8)!)
        )
    )

    print("PutObject done, StatusCode: \(result.statusCode), RequestId: \(result.requestId).")
}

try await main()

Download an object

import AlibabaCloudOSS
import Foundation

func main() async throws {
    let region = "<region-id>"
    let bucket = "<your-bucket-name>"
    let key = "<your-object-key>"

    let config = Configuration.default()
        .withCredentialsProvider(EnvironmentCredentialsProvider())
        .withRegion(region)

    let client = Client(config)

    let result = try await client.getObject(
        GetObjectRequest(
            bucket: bucket,
            key: key
        )
    )

    print("GetObject done, StatusCode: \(result.statusCode), RequestId: \(result.requestId).")
}

try await main()

List objects

import AlibabaCloudOSS
import Foundation

func main() async throws {
    let region = "<region-id>"
    let bucket = "<your-bucket-name>"

    let config = Configuration.default()
        .withCredentialsProvider(EnvironmentCredentialsProvider())
        .withRegion(region)

    let client = Client(config)

    // Paginate through all objects automatically.
    for try await result in client.listObjectsV2Paginator(
        ListObjectsV2Request(bucket: bucket)
    ) {
        if let objects = result.contents {
            for object in objects {
                print("Object: \(object)")
            }
        }
    }
}

try await main()

Delete an object

import AlibabaCloudOSS
import Foundation

func main() async throws {
    let region = "<region-id>"
    let bucket = "<your-bucket-name>"
    let key = "<your-object-key>"

    let config = Configuration.default()
        .withCredentialsProvider(EnvironmentCredentialsProvider())
        .withRegion(region)

    let client = Client(config)

    let result = try await client.deleteObject(
        DeleteObjectRequest(
            bucket: bucket,
            key: key
        )
    )

    print("DeleteObject done, StatusCode: \(result.statusCode), RequestId: \(result.requestId).")
}

try await main()

Build and run

Command line

Create a Swift package, add the SDK dependency to Package.swift, and place the example code in a .swift file under Sources/. Then build and run:

swift build
swift run

Xcode

Create a project or open an existing one, and add the SDK package dependency as described in Add the dependency in Xcode.
Set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables in the scheme editor (Product > Scheme > Edit Scheme > Run > Environment Variables).
Copy the example code into a .swift file, replace the placeholders with your values, and run the project.

Object Storage Service:Quick Start (Swift SDK)