Arbeiten Sie mit Amazon S3 Multiregion Access Points mithilfe des SDK für Kotlin

Amazon S3 Multiregion Access Points bieten einen globalen Endpunkt, über den Anwendungen Anfragen von Amazon S3 S3-Buckets bearbeiten können, die sich in mehreren befinden. AWS-Regionen Sie können Multi-Region-Access Points verwenden, um multiregionale Anwendungen mit derselben Architektur zu erstellen, die in einer einzelnen Region verwendet wird, und diese Anwendungen dann überall auf der Welt ausführen.

Das Amazon S3 S3-Benutzerhandbuch enthält weitere Hintergrundinformationen zu Multi-Region-Access Points.

Arbeiten Sie mit Access Points für mehrere Regionen

Um einen Access Point mit mehreren Regionen zu erstellen, geben Sie zunächst einen Bucket in jeder AWS Region an, die Sie Anfragen bearbeiten möchten. Das folgende Snippet erstellt zwei Buckets.

        suspend fun setUpTwoBuckets(
            s3: S3Client,
            bucketName1: String,
            bucketName2: String,
        ) {
            println("Create two buckets in different regions.")
            // The shared aws config file configures the default Region to be us-east-1.
            s3.createBucket(
                CreateBucketRequest {
                    bucket = bucketName1
                },
            )
            s3.waitUntilBucketExists {
                bucket = bucketName1
            }
            println("  Bucket [$bucketName1] created.")

            // Override the S3Client to work with us-west-1 for the second bucket.
            s3.withConfig {
                region = "us-west-1"
            }.use { s3West ->
                s3West.createBucket(
                    CreateBucketRequest {
                        bucket = bucketName2
                        createBucketConfiguration = CreateBucketConfiguration {
                            locationConstraint = BucketLocationConstraint.UsWest1
                        }
                    },
                )
                s3West.waitUntilBucketExists {
                    bucket = bucketName2
                }
                println("  Bucket [$bucketName2] created.")
            }
        }

Sie verwenden den S3-Control-Client des Kotlin SDK, um Multi-Region-Access Points zu erstellen, zu löschen und Informationen darüber abzurufen.

Fügen Sie eine Abhängigkeit vom S3-Steuerartefakt hinzu, wie im folgenden Codeausschnitt gezeigt. (Sie können zu dem X.Y.Z Link navigieren, um die neueste verfügbare Version zu sehen.)

...
implementation(platform("aws.sdk.kotlin:bom:X.Y.Z"))
implementation("aws.sdk.kotlin:s3control")
...

Konfigurieren Sie den S3-Steuerungsclient so, dass AWS-Region us-west-2 er damit funktioniert, wie im folgenden Code gezeigt. Alle S3-Control-Client-Operationen müssen auf die us-west-2 Region abzielen.

        suspend fun createS3ControlClient(): S3ControlClient {
            // Configure your S3ControlClient to send requests to US West (Oregon).
            val s3Control = S3ControlClient.fromEnvironment {
                region = "us-west-2"
            }
            return s3Control
        }

Verwenden Sie den S3-Kontrollclient, um einen Multi-Region-Access Point zu erstellen, indem Sie die (zuvor erstellten) Bucket-Namen angeben, wie im folgenden Code gezeigt.

    suspend fun createMrap(
        s3Control: S3ControlClient,
        accountIdParam: String,
        bucketName1: String,
        bucketName2: String,
        mrapName: String,
    ): String {
        println("Creating MRAP ...")
        val createMrapResponse: CreateMultiRegionAccessPointResponse =
            s3Control.createMultiRegionAccessPoint {
                accountId = accountIdParam
                clientToken = UUID.randomUUID().toString()
                details {
                    name = mrapName
                    regions = listOf(
                        Region {
                            bucket = bucketName1
                        },
                        Region {
                            bucket = bucketName2
                        },
                    )
                }
            }
        val requestToken: String? = createMrapResponse.requestTokenArn

        // Use the request token to check for the status of the CreateMultiRegionAccessPoint operation.
        if (requestToken != null) {
            waitForSucceededStatus(s3Control, requestToken, accountIdParam)
            println("MRAP created")
        }

        val getMrapResponse =
            s3Control.getMultiRegionAccessPoint(
                input = GetMultiRegionAccessPointRequest {
                    accountId = accountIdParam
                    name = mrapName
                },
            )
        val mrapAlias = getMrapResponse.accessPoint?.alias
        return "arn:aws:s3::$accountIdParam:accesspoint/$mrapAlias"
    }

Da es sich bei der Erstellung eines Access Points mit mehreren Regionen um einen asynchronen Vorgang handelt, verwenden Sie das Token, das Sie aus der unmittelbaren Antwort erhalten, um den Status des Erstellungsprozesses zu überprüfen. Nachdem bei der Statusüberprüfung eine Erfolgsmeldung zurückgegeben wurde, können Sie den GetMultiRegionAccessPoint Vorgang verwenden, um den Alias des Multi-Region Access Points abzurufen. Der Alias ist die letzte Komponente des ARN, die Sie für Operationen auf Objektebene benötigen.

        suspend fun waitForSucceededStatus(
            s3Control: S3ControlClient,
            requestToken: String,
            accountIdParam: String,
            timeBetweenChecks: Duration = 1.minutes,
        ) {
            var describeResponse: DescribeMultiRegionAccessPointOperationResponse
            describeResponse = s3Control.describeMultiRegionAccessPointOperation(
                input = DescribeMultiRegionAccessPointOperationRequest {
                    accountId = accountIdParam
                    requestTokenArn = requestToken
                },
            )

            var status: String? = describeResponse.asyncOperation?.requestStatus
            while (status != "SUCCEEDED") {
                delay(timeBetweenChecks)
                describeResponse = s3Control.describeMultiRegionAccessPointOperation(
                    input = DescribeMultiRegionAccessPointOperationRequest {
                        accountId = accountIdParam
                        requestTokenArn = requestToken
                    },
                )
                status = describeResponse.asyncOperation?.requestStatus
                println(status)
            }
        }

Arbeiten Sie mit Objekten und Access Points für mehrere Regionen

Sie verwenden den S3-Client, um mit Objekten in multiregionalen Access Points zu arbeiten. Viele der Operationen, die Sie für Objekte in Buckets verwenden, können Sie auch auf Access Points mit mehreren Regionen verwenden. Weitere Informationen und eine vollständige Liste der Operationen finden Sie unter Kompatibilität von Access Points in mehreren Regionen mit S3-Vorgängen.

Operationen mit Access Points in mehreren Regionen werden mit dem Signaturalgorithmus Asymmetric Sigv4 (SigV4a) signiert. Um SigV4a zu konfigurieren, fügen Sie Ihrem Projekt zunächst die folgenden Abhängigkeiten hinzu. (Sie können zu dem X.Y.Z Link navigieren, um die neueste verfügbare Version zu sehen.)

...
implementation(platform("aws.sdk.kotlin:bom:X.Y.Z"))
implementation(platform("aws.smithy.kotlin:bom:X.Y.Z"))

implementation("aws.smithy.kotlin:aws-signing-default")
implementation("aws.smithy.kotlin:http-auth-aws")
implementation("aws.sdk.kotlin:s3")
...

Nachdem Sie die Abhängigkeiten hinzugefügt haben, konfigurieren Sie den S3-Client so, dass er den SigV4A-Signaturalgorithmus verwendet, wie im folgenden Code gezeigt.

        suspend fun createS3Client(): S3Client {
            // Configure your S3Client to use the Asymmetric SigV4 (SigV4a) signing algorithm.
            val sigV4aScheme = SigV4AsymmetricAuthScheme(DefaultAwsSigner)
            val s3 = S3Client.fromEnvironment {
                authSchemes = listOf(sigV4aScheme)
            }
            return s3
        }

Nachdem Sie den S3-Client konfiguriert haben, funktionieren die Operationen, die S3 für Access Points mit mehreren Regionen unterstützt, genauso. Der einzige Unterschied besteht darin, dass der Bucket-Parameter der ARN des Multi-Region Access Points sein muss. Sie können den ARN von der Amazon S3 S3-Konsole oder programmgesteuert abrufen, wie zuvor in der createMrap Funktion, die einen ARN zurückgibt, gezeigt wurde.

Das folgende Codebeispiel zeigt den in einer GetObject Operation verwendeten ARN.

    suspend fun getObjectFromMrap(
        s3: S3Client,
        mrapArn: String,
        keyName: String,
    ): String? {
        val request = GetObjectRequest {
            bucket = mrapArn // Use the ARN instead of the bucket name for object operations.
            key = keyName
        }

        var stringObj: String? = null
        s3.getObject(request) { resp ->
            stringObj = resp.body?.decodeToString()
            if (stringObj != null) {
                println("Successfully read $keyName from $mrapArn")
            }
        }
        return stringObj
    }