Travaillez avec les points d'accès multirégionaux Amazon S3 à l'aide du SDK pour Kotlin

Les points d'accès multirégionaux Amazon S3 fournissent un point de terminaison global que les applications peuvent utiliser pour traiter les demandes provenant de compartiments Amazon S3 situés dans plusieurs compartiments. Régions AWS Vous pouvez utiliser des points d'accès multirégionaux pour créer des applications multirégionales avec la même architecture que celle utilisée dans une seule région, puis exécuter ces applications n'importe où dans le monde.

Le guide de l'utilisateur Amazon S3 contient des informations générales supplémentaires sur les points d'accès multirégionaux.

Travaillez avec des points d'accès multirégionaux

Pour créer un point d'accès multirégional, commencez par spécifier un compartiment dans chaque AWS région dans laquelle vous souhaitez traiter les demandes. L'extrait de code suivant crée deux compartiments.

        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.")
            }
        }

Vous utilisez le client de contrôle S3 du SDK Kotlin pour créer, supprimer et obtenir des informations sur les points d'accès multirégionaux.

Ajoutez une dépendance à l'artefact de contrôle S3, comme indiqué dans l'extrait suivant. (Vous pouvez accéder au X.Y.Z lien pour voir la dernière version disponible.)

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

Configurez le client de contrôle S3 pour qu'il fonctionne Région AWS us-west-2 comme indiqué dans le code suivant. Toutes les opérations du client de contrôle S3 doivent cibler la us-west-2 région.

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

Utilisez le client de contrôle S3 pour créer un point d'accès multirégional en spécifiant les noms des compartiments (créés précédemment) comme indiqué dans le code suivant.

    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"
    }

La création d'un point d'accès multirégional étant une opération asynchrone, vous utilisez le jeton que vous recevez de la réponse immédiate pour vérifier l'état du processus de création. Une fois que la vérification de statut a renvoyé un message de réussite, vous pouvez utiliser l'GetMultiRegionAccessPointopération pour obtenir l'alias du point d'accès multirégional. L'alias est le dernier composant de l'ARN dont vous avez besoin pour les opérations au niveau de l'objet.

        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)
            }
        }

Travaillez avec des objets et des points d'accès multirégionaux

Vous utilisez le client S3 pour travailler avec des objets dans des points d'accès multirégionaux. La plupart des opérations que vous effectuez sur des objets dans des compartiments peuvent être effectuées sur des points d'accès multirégionaux. Pour plus d'informations et une liste complète des opérations, consultez la section Compatibilité des points d'accès multirégionaux avec les opérations S3.

Les opérations avec des points d'accès multirégionaux sont signées à l'aide de l'algorithme de signature asymétrique SigV4 (SigV4a). Pour configurer SigV4A, ajoutez d'abord les dépendances suivantes à votre projet. (Vous pouvez accéder au X.Y.Z lien pour voir la dernière version disponible.)

...
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")
...

Après avoir ajouté les dépendances, configurez le client S3 pour qu'il utilise l'algorithme de signature Sigv4a comme indiqué dans le code suivant.

        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
        }

Après avoir configuré le client S3, les opérations prises en charge par S3 pour les points d'accès multirégionaux fonctionnent de la même manière. La seule différence est que le paramètre du bucket doit être l'ARN du point d'accès multirégional. Vous pouvez obtenir l'ARN depuis la console Amazon S3 ou par programmation, comme indiqué précédemment dans la createMrap fonction qui renvoie un ARN.

L'exemple de code suivant montre l'ARN utilisé dans une GetObject opération.

    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
    }