List objects in a bucket with Swift SDK - Object Storage Service

Use the OSS Swift SDK to list objects in a bucket with ListObjectsV2. The SDK supports two approaches: manual pagination with a continuation token, and a built-in paginator that handles token management automatically.

Prerequisites

Before you begin, ensure that you have:

The oss:ListObjects permission. For details, see Grant custom permissions to a RAM user.
The OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables configured with your access credentials.

Usage notes

The sample code uses the China (Hangzhou) region (cn-hangzhou) and a public endpoint by default. To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint instead. For supported regions and endpoints, see Regions and endpoints.

Choose a listing method

Both methods call the same ListObjectsV2 API and return the same data. The difference is in how pagination is handled.

Method	How pagination works	When to use
Manual pagination	Track `nextContinuationToken` and loop until `isTruncated` is `false`	Fine-grained control over each page, early exit on a condition
Paginator	The SDK manages the continuation token; iterate with `for try await`	Simpler code when you want to process all objects without managing tokens

List objects with manual pagination

The following example uses ListObjectsV2 with maxKeys: 10 to fetch pages of up to 10 objects, looping until all pages are retrieved.

import AlibabaCloudOSS
import Foundation

@main
struct Main {
    static func main() async {
        do {
            // Specify the region where the bucket is located. For example, cn-hangzhou for China (Hangzhou).
            let region = "cn-hangzhou"
            // Specify the bucket name.
            let bucket = "examplebucket"
            // Optional: set a custom endpoint, such as https://oss-cn-hangzhou.aliyuncs.com.
            // Leave nil to use the default public endpoint for the region.
            let endpoint: String? = nil

            // Load access credentials from environment variables.
            // Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this code.
            let credentialsProvider = EnvironmentCredentialsProvider()

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

            if let endpoint = endpoint {
                config.withEndpoint(endpoint)
            }

            let client = Client(config)

            // continueToken tracks the position across pages.
            // Start with nil to begin from the first object.
            var continueToken: String?
            var isTruncated: Bool = false

            repeat {
                let result = try await client.listObjectsV2(
                    ListObjectsV2Request(
                        bucket: bucket,
                        maxKeys: 10,
                        continuationToken: continueToken
                    )
                )

                for content in result.contents ?? [] {
                    print("key: \(content.key ?? ""), size: \(String(describing: content.size)), last modified: \(String(describing: content.lastModified))")
                }

                // If isTruncated is true, there are more pages.
                // nextContinuationToken is the starting point for the next request.
                isTruncated = result.isTruncated ?? false
                continueToken = result.nextContinuationToken
            } while isTruncated

        } catch {
            print("error: \(error)")
        }
    }
}

List objects with a paginator

listObjectsV2Paginator iterates through all pages automatically, with the SDK managing the continuation token for you.

import AlibabaCloudOSS
import Foundation

@main
struct Main {
    static func main() async {
        do {
            let region = "cn-hangzhou"
            let bucket = "examplebucket"
            let endpoint: String? = nil

            let credentialsProvider = EnvironmentCredentialsProvider()

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

            if let endpoint = endpoint {
                config.withEndpoint(endpoint)
            }

            let client = Client(config)

            // Create the paginator. No request is sent until you iterate.
            let paginator = client.listObjectsV2Paginator(
                ListObjectsV2Request(bucket: bucket)
            )

            // Each iteration fetches one page.
            for try await page in paginator {
                for content in page.contents ?? [] {
                    print("key: \(content.key ?? ""), size: \(String(describing: content.size)), last modified: \(String(describing: content.lastModified))")
                }
            }

        } catch {
            print("error: \(error)")
        }
    }
}

What's next

Complete sample code: GitHub sample
API reference: ListObjectsV2