本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用適用於 Kotlin 的 SDK 來使用 Amazon S3 多區域存取點
<a name="use-services-s3-mrap"></a>

Amazon S3 多區域存取點提供全域端點，應用程式可用來滿足來自位於多個 Amazon S3 儲存貯體的請求 AWS 區域。您可以使用多區域存取點，以單一區域中使用的相同架構建置多區域應用程式，然後在世界任何地方執行這些應用程式。

Amazon S3 使用者指南包含[有關多區域存取點](https://docs.aws.amazon.com//AmazonS3/latest/userguide/MultiRegionAccessPoints.html)的更多背景資訊。

## 使用多區域存取點
<a name="mrap-s3control-config"></a>

若要建立多區域存取點，請先在您要提供請求的每個 AWS 區域中指定一個儲存貯體。下列程式碼片段會建立兩個儲存貯體。

### 建立儲存貯體
<a name="mrap-s3-create-buckets"></a>

下列 函數會建立兩個儲存貯體，以使用多區域存取點。一個儲存貯體位於 區域`us-east-1`，另一個儲存貯體位於 區域`us-west-1`。

做為第一個引數傳入的 S3 用戶端的建立會顯示在 下的第一個範例中[使用物件和多區域存取點](#mrap-s3client-config)。

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

您可以使用 Kotlin SDK 的 [S3 控制用戶端](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/s3control/aws.sdk.kotlin.services.s3control/-s3-control-client/index.html)來建立、刪除和取得多區域存取點的相關資訊。

在 S3 控制成品上新增相依性，如下列程式碼片段所示。（您可以導覽至 *X.Y.Z* 連結，以查看可用的最新版本。)

```
...
implementation(platform("aws.sdk.kotlin:bom:[https://github.com/awslabs/aws-sdk-kotlin/releases/latest](https://github.com/awslabs/aws-sdk-kotlin/releases/latest)"))
implementation("aws.sdk.kotlin:s3control")
...
```

將 S3 控制用戶端設定為使用 AWS 區域 `us-west-2` ，如下列程式碼所示。所有 S3 控制用戶端操作都必須以`us-west-2`區域為目標。

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

使用 S3 控制用戶端透過指定儲存貯體名稱 （先前建立） 來建立多區域存取點，如下列程式碼所示。

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

由於多區域存取點的建立是非同步操作，因此您可以使用從立即回應中收到的字符來檢查建立程序的狀態。狀態檢查傳回成功訊息後，您可以使用 `GetMultiRegionAccessPoint`操作來取得多區域存取點的別名。別名是 ARN 的最後一個元件，您需要此元件才能進行物件層級操作。

### 使用字符檢查狀態
<a name="mrap-s3-control-poll"></a>

使用 `DescribeMultiRegionAccessPointOperation`檢查上次操作的狀態。在`requestStatus`值變成「SUCCEEDED」之後，您就可以使用多區域存取點。

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

## 使用物件和多區域存取點
<a name="mrap-s3client-config"></a>

您可以使用 [S3 用戶端](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/s3/aws.sdk.kotlin.services.s3/-s3-client/index.html)來處理多區域存取點中的物件。您可以在多區域存取點上使用的儲存貯體中物件上的許多操作。如需詳細資訊和完整的操作清單，請參閱[多區域存取點與 S3 操作的相容性](https://docs.aws.amazon.com//AmazonS3/latest/userguide/MrapOperations.html#mrap-operations-support)。

使用多區域存取點的操作會使用非對稱 SigV4 (SigV4a) 簽署演算法進行簽署。若要設定 SigV4a，請先將下列相依性新增至您的專案。（您可以導覽至 *X.Y.Z* 連結，以查看可用的最新版本。)

```
...
implementation(platform("aws.sdk.kotlin:bom:[https://github.com/awslabs/aws-sdk-kotlin/releases/latest](https://github.com/awslabs/aws-sdk-kotlin/releases/latest)"))
implementation(platform("aws.smithy.kotlin:bom:[https://github.com/smithy-lang/smithy-kotlin/releases/latest](https://github.com/smithy-lang/smithy-kotlin/releases/latest)"))

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

新增相依性之後，請將 S3 用戶端設定為使用 SigV4a 簽署演算法，如下列程式碼所示。

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

設定 S3 用戶端之後，S3 針對多區域存取點支援的操作也會運作相同。唯一的差別是儲存貯體參數必須是多區域存取點的 ARN。您可以從 Amazon S3 主控台或以程式設計方式取得 ARN，如先前傳回 ARN 的 `createMrap`函數所示。

下列程式碼範例顯示 `GetObject`操作中使用的 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
    }
```