Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Configuring AWS SDK for Swift service clients in code

When configuration is handled directly in code, the configuration scope is limited to the application that uses that code. Within that application, there are options for the global configuration of all service clients, the configuration to all clients of a certain AWS service type, or the configuration to a specific service client instance.

Configuration data types

The AWS SDK for Swift provides a configuration structure for each AWS service. Use it to control how a client connects to and interacts with that service. Customize a client's configuration to control the reliability, security, and performance of your application's connection. You can set the Region it reaches, the credentials it presents, and how it retries failed calls. For example, you might raise the maximum number of retry attempts for an application that runs on an unreliable network.

Each AWS service has its own configuration structure that you use to adjust options for that client type.

All of these structures are based on a number of protocols that together describe all the configuration options available for that client. This includes options such as the Region and credentials, which you always need to access an AWS service.

Amazon Simple Storage Service (Amazon S3) uses the S3Client.S3ClientConfig structure, described in the AWS SDK for Swift API Reference. The AWS SDK for Swift defines it like this:

extension S3Client {
    public struct S3ClientConfig: AWSClientRuntime.AWSDefaultClientConfiguration &
            AWSClientRuntime.AWSRegionClientConfiguration &
            ClientRuntime.DefaultClientConfiguration &
            ClientRuntime.DefaultHttpClientConfiguration, Swift.Sendable {

        // Service-specific properties are defined here, including:

        public var region: Swift.String?

        // ... and so on.
   }
}   

As a result, S3ClientConfig includes its own properties and also all the properties defined in those protocols, making it a complete description of an Amazon S3 client's configuration. Every AWS service defines a corresponding configuration structure.

Because the configuration is a struct, it's a value type. Declare it using var if you need to change its properties after creating it. Remember that assigning it to another variable makes a copy rather than sharing a reference.

By creating a custom configuration object and using it when creating a service client object, you can customize the client by specifying a configuration source from which credentials and other options are taken. Otherwise, you can directly specify the credentials instead of letting the SDK obtain them automatically.

Configuring a client

When only changing common options, you can often specify the custom values for your configuration when instantiating the service’s client object. If the client class constructor doesn't support the option you need to change, then create and specify a configuration object with the type that corresponds to the client class.

Creating a client with only a custom Region

Most services let you directly specify the Region when you call their constructors. For example, to create an Amazon S3 client configured for the Region af-south-1, specify the region parameter when creating the client, as shown.

do {
    let s3 = try S3Client(region: "af-south-1")

    // Use the client.
} catch {
    // Handle the error.
    dump(error, name: "Error accessing S3 service")
}

This lets you handle a common client configuration scenario (specifying a Region while using the default values for all other options) without going through the full configuration process. That process is covered in the next topic.

Creating and using a custom configuration

To customize the configuration of an AWS service, create a configuration object of the appropriate type for the service. Then pass that configuration object into the service client's constructor as the value of its config parameter.

For example, to configure an Amazon S3 client, create a value of type S3Client.S3ClientConfig. Set the properties to change, and then pass the configuration into S3Client(config:). The AWS SDK for Swift API Reference describes both.

The following example creates a new Amazon S3 client configured with the following options:

        // Create an Amazon S3 client configuration object that specifies the
        // region as "us-east-1", an exponential backoff strategy, the
        // adaptive retry mode, and the maximum number of retries as 5.

        await SDKLoggingSystem().initialize(logLevel: .debug)

        let config: S3Client.S3ClientConfig

        do {
            config = try await S3Client.S3ClientConfig(
                awsRetryMode: .standard,
                maxAttempts: 3,
                region: "us-east-1"
            )
        } catch {
            print("Error: Unable to create configuration")
            dump(error)
            exit(1)
        }

        // Create an Amazon S3 client using the configuration created above.

        let client = S3Client(config: config)

If an error occurs creating the configuration, an error message is displayed and the details are dumped to the console. The program then exits. In a real world application, a more constructive approach should be taken when handling this error, such as falling back to a different configuration or using the default configuration, if doing so is appropriate for your application.