Use client services with the SDK for Swift

Each AWS service is exposed through one or more Swift classes. Each class provides a number of functions that you can call to issue requests to AWS services, including Amazon S3, DynamoDB, IAM, and others. Functions that access the network are designed to operate in the background so that your application can continue to run while awaiting the response. The SDK then notifies you when the response arrives.

The process of sending requests to AWS services is as follows:

1. Create a service client object with the desired configuration, such as the specific AWS Region.

2. Create an input parameters object with the values and data needed to make the request. For example, when sending a request to Amazon S3, you need to specify the bucket name and the key of the data that you want to access. For a request method named SomeOperation, the input parameters object is created using a function called SomeOperationInput().

3. Call the service object method that sends the desired request, with the parameters object created in the previous step.

4. Use await to wait for the response, and handle thrown exceptions to appropriately handle error conditions.

5. Examine the contents of the returned structure for the results you need. Every SDK for Swift function returns a structure with a type whose name is the same as the service action performed by the function, followed by the word Output. For example, when calling the Amazon S3 function S3Client.createBucket(input:), the return type is CreateBucketOutput.

Create and use AWS client objects

Before you can send requests to an AWS service, you must first instantiate a client object corresponding to the service. These client classes are helpfully named using the service name and the word Client. Examples include S3Client and IAMClient.

After creating the client object, use it to make your requests. When you're done, release the object. If the service connection is open, it is closed for you automatically.

do {
    let s3 = try await S3Client()
        
    // ...
} catch {
    dump(error)
}

If an error occurs while trying to instantiate an AWS service — or at any time while using the service — an exception is thrown. Your catch block should handle the error appropriately.

Unless you are in a testing environment in which you expect a knowledgeable user to have configured reasonable default options, specify the appropriate service configuration when instantiating the client object. This is described in Configure a client.

Specify service client function parameters

When calling service client methods, you pass input parameters within objects created using factory functions provided for that purpose. For example, before calling the getObject() method on the Amazon S3 service class S3Client, you need to create the input parameter object using the factory function GetObjectInput().

do {
    let s3 = try S3Client()
    let inputObject = GetObjectInput(bucket: "bucketName", key: "keyName")
    let output = try await s3.getObject(input: inputObject)
        
    // ...
} catch {
    dump(error)
}

In this example, GetObjectInput() is used to create an input object for the getObject(input:) method. The resulting input object specifies that the desired data has the keyName key and should be fetched from the Amazon S3 bucket named bucketName.

Call SDK functions

Nearly all AWS SDK for Swift functions are asynchronous and can be called using Swift's async/await model.

To call one of the SDK's asynchronous functions from synchronous code, call the function from a Swift Task created and run from your synchronous code.

Call SDK functions asynchronously

The following function fetches and returns the content of a file named text/motd.txt using Amazon S3.

func getMOTD() async throws -> String? {
    let s3 = try S3Client()
    let motdInput = GetObjectInput(bucket: "supergame-datastore",
                                    key: "text/motd.txt")
    let output = try await s3.getObject(input: motdInput)

    guard let data = output.body?.toBytes().toData() else {
        return nil
    }
    return String(decoding: data, as: UTF8.self)
}

The getMOTD() function can only be called from another async function, and returns a string that contains the text in the MOTD file or nil if the file is empty. It throws an exception on errors. Thus, you call the getMOTD() function.

do {
    let motd = try await getMOTD()
    // ...
} catch {
    dump(error)
}

Here, the fetched "message of the day" text is available in the variable motd immediately following the call to getMOTD(). If an error occurs attempting to fetch the text, an appropriate exception is delivered to the catch clause. The standard Swift variable error describes the problem that occurred.

Call SDK functions from synchronous code

To call AWS SDK for Swift functions from synchronous code, enclose the code that needs to run asynchronously in a Task. The Task uses await for each SDK function call that returns its results asynchronously. You might need to use an atomic flag or other means to know that the operation has finished.

Note

It's important to properly manage asynchronous requests. Be sure that any operation that's dependent on a previous result waits until that result is available before it begins. When used properly, the async/await model handles most of this for you.

func updateMOTD() {
    Task() {
        var motd: String = ""

        do {
            let s3 = try S3Client()
            let motdInput = GetObjectInput(bucket: "supergame-datastore",
                            key: "text/motd.txt")
            let output = try await s3.getObject(input: motdInput)

            if let bytes = output.body?.toBytes() {
                motd = String(decoding: bytes.toData(), as: UTF8.self)
            }
        } catch {
            motd = ""
        }

        setMOTD(motd)
    }
}

In this example, the code inside the Task block runs asynchronously, returning no output value to the caller. It fetches the contents of a text file located at the key text/motd.txt and calls a function named setMOTD(), with the contents of the file decoded into a UTF-8 string.

SDK function calls that might encounter errors are preceded by the try keyword. This indicates that they might result in an exception. A do/catch block is used to capture any thrown exceptions and set the motd variable to an empty string, which indicates that no message is available.

A call to this updateMOTD() function will spawn the task and return almost immediately. While the program continues to run, the asynchronous task code fetches and uses the text from the specified file on Amazon S3. When the task has completed, the Task automatically ends.