将多区域接入点与支持的 API 操作结合使用
Amazon S3 提供了一组操作用来管理多区域访问点。Amazon S3 同步处理其中一些操作，异步处理另一些操作。当您调用异步操作时，Amazon S3 首先同步授权请求的操作。如果授权成功，Amazon S3 将返回一个令牌，您可以使用该令牌来跟踪所请求操作的进度和结果。
通过 Amazon S3 控制台发出的请求始终是同步的。控制台等待，直到请求完成，然后再允许您提交另一个请求。
您可以使用控制台查看异步操作的当前状态和结果，也可以使用 AWS CLI、AWS SDK 或 REST API 中的 DescribeMultiRegionAccessPointOperation。Amazon S3 在响应异步操作时提供跟踪令牌。您将该跟踪令牌作为 DescribeMultiRegionAccessPointOperation。当您包括跟踪令牌时，Amazon S3 会返回指定操作的当前状态和结果，包括任何错误或相关资源信息。Amazon S3 执行 DescribeMultiRegionAccessPointOperation 同步操作。
所有创建或维护多区域接入点的控制面板请求都必须路由到 US West (Oregon) 区域。对于多区域接入点数据面板请求，无需指定区域。对于多区域接入点失效转移控制面板，请求必须路由到五个支持的区域之一。有关支持多区域接入点的区域的更多信息，请参阅多区域接入点限制和限制。
此外，您必须将 s3:ListAllMyBuckets 权限授予请求管理多区域接入点的用户、角色或其他 AWS Identity and Access Management（IAM）实体。
以下示例演示如何在 Amazon S3 中将多区域接入点与兼容操作结合使用。
多区域接入点与 AWS 服务和 AWS SDK 的兼容性
要在需要 Amazon S3 存储桶名称的应用程序中使用多区域接入点，请在使用 AWS SDK 发出请求时使用多区域接入点的 Amazon 资源名称（ARN）。要检查哪些 AWS SDK 与多区域接入点兼容，请参阅与 AWS SDK 的兼容性。
多区域接入点与 S3 操作的兼容性
您可以使用以下 Amazon S3 数据面板 API 操作，对桶中与您的多区域接入点关联的对象执行操作。以下 S3 操作可以接受多区域接入点 ARN：
当使用多区域接入点 ARN 时，多区域接入点仅支持使用多区域接入点的复制操作作为目标。
您可以使用以下 Amazon S3 控制面板操作来创建和管理多区域接入点：
查看您的多区域接入点路由配置
- AWS CLI
-
以下示例命令检索您的多区域接入点路由配置，以便您可以查看桶的当前路由状态。要使用此示例命令，请将 user input
placeholders
aws s3control get-multi-region-access-point-routes
--region eu-west-1
--account-id 111122223333
--mrap arn:aws:s3::111122223333:accesspoint/abcdef0123456.mrap
- SDK for Java
-
以下 SDK for Java 代码检索您的多区域接入点路由配置，以便您可以查看桶的当前路由状态。要使用此示例语法，请将 user input
placeholders
S3ControlClient s3ControlClient = S3ControlClient.builder()
.region(Region.US_EAST_1)
.credentialsProvider(credentialsProvider)
.build();
GetMultiRegionAccessPointRoutesRequest request = GetMultiRegionAccessPointRoutesRequest.builder()
.accountId("111122223333")
.mrap("arn:aws:s3::111122223333:accesspoint/abcdef0123456.mrap")
.build();
GetMultiRegionAccessPointRoutesResponse response = s3ControlClient.getMultiRegionAccessPointRoutes(request);
- SDK for JavaScript
-
以下 SDK for JavaScript 代码检索您的多区域接入点路由配置，以便您可以查看桶的当前路由状态。要使用此示例语法，请将 user input
placeholders
const REGION = 'us-east-1'
const s3ControlClient = new S3ControlClient({
region: REGION
})
export const run = async () => {
try {
const data = await s3ControlClient.send(
new GetMultiRegionAccessPointRoutesCommand({
AccountId: '111122223333',
Mrap: 'arn:aws:s3::111122223333:accesspoint/abcdef0123456.mrap',
})
)
console.log('Success', data)
return data
} catch (err) {
console.log('Error', err)
}
}
run()
- SDK for Python
-
以下 SDK for Python 代码检索您的多区域接入点路由配置，以便您可以查看桶的当前路由状态。要使用此示例语法，请将 user input
placeholders
s3.get_multi_region_access_point_routes(
AccountId=111122223333,
Mrap=arn:aws:s3::111122223333:accesspoint/abcdef0123456.mrap)['Routes']
更新您的底层 Amazon S3 存储桶策略
要授予适当的访问权限，您还必须更新底层 Amazon S3 存储桶策略。以下示例将访问控制委托给多区域接入点策略。在将访问控制委托给多区域接入点策略后，当通过多区域接入点发出请求时，桶策略不再用于访问控制。
以下是将访问控制委托给多区域接入点策略的示例桶策略。要使用这一示例桶策略，请将 user input
placeholdersput-bucket-policy 命令应用此策略，如下一个示例所示，请将策略保存在文件中，例如 policy.json。
{
"Version": "2012-10-17",
"Statement": {
"Principal": { "AWS": "*" },
"Effect": "Allow",
"Action": ["s3:*"],
"Resource": ["arn:aws:s3:::111122223333/*", "arn:aws:s3:::amzn-s3-demo-bucket"],
"Condition": {
"StringEquals": {
"s3:DataAccessPointAccount": "444455556666"
}
}
}
}
以下 put-bucket-policy 示例命令将更新后的 S3 存储桶策略与您的 S3 存储桶关联起来：
aws s3api put-bucket-policy
--bucket amzn-s3-demo-bucket
--policy file:///tmp/policy.json
更新多区域接入点路由配置
以下示例命令更新多区域接入点路由配置。可以对以下五个区域运行多区域接入点路由命令：
-
ap-southeast-2
-
ap-northeast-1
-
us-east-1
-
us-west-2
-
eu-west-1
在多区域接入点路由配置中，您可以将桶设置为主动或被动路由状态。主动桶接收流量，而被动桶不接收流量。您可以通过将桶的 TrafficDialPercentage 值设置为 100（表示主动）或 0（表示被动）来设置桶的路由状态。
- AWS CLI
-
以下示例命令将更新您的多区域接入点路由配置。在此示例中，amzn-s3-demo-bucket1amzn-s3-demo-bucket2user input placeholders
aws s3control submit-multi-region-access-point-routes
--region ap-southeast-2
--account-id 111122223333
--mrap arn:aws:s3::111122223333:accesspoint/abcdef0123456.mrap
--route-updates Bucket=amzn-s3-demo-bucket1,TrafficDialPercentage=100
Bucket=amzn-s3-demo-bucket2,TrafficDialPercentage=0
- SDK for Java
-
以下 SDK for Java 代码将更新您的多区域接入点路由配置。要使用此示例语法，请将 user input
placeholders
S3ControlClient s3ControlClient = S3ControlClient.builder()
.region(Region.ap-southeast-2)
.credentialsProvider(credentialsProvider)
.build();
SubmitMultiRegionAccessPointRoutesRequest request = SubmitMultiRegionAccessPointRoutesRequest.builder()
.accountId("111122223333")
.mrap("arn:aws:s3::111122223333:accesspoint/abcdef0123456.mrap")
.routeUpdates(
MultiRegionAccessPointRoute.builder()
.region("eu-west-1")
.trafficDialPercentage(100)
.build(),
MultiRegionAccessPointRoute.builder()
.region("ca-central-1")
.bucket("111122223333")
.trafficDialPercentage(0)
.build()
)
.build();
SubmitMultiRegionAccessPointRoutesResponse response = s3ControlClient.submitMultiRegionAccessPointRoutes(request);
- SDK for JavaScript
-
以下 SDK for JavaScript 代码将更新您的多区域接入点路由配置。要使用此示例语法，请将 user input
placeholders
const REGION = 'ap-southeast-2'
const s3ControlClient = new S3ControlClient({
region: REGION
})
export const run = async () => {
try {
const data = await s3ControlClient.send(
new SubmitMultiRegionAccessPointRoutesCommand({
AccountId: '111122223333',
Mrap: 'arn:aws:s3::111122223333:accesspoint/abcdef0123456.mrap',
RouteUpdates: [
{
Region: 'eu-west-1',
TrafficDialPercentage: 100,
},
{
Region: 'ca-central-1',
Bucket: 'amzn-s3-demo-bucket1',
TrafficDialPercentage: 0,
},
],
})
)
console.log('Success', data)
return data
} catch (err) {
console.log('Error', err)
}
}
run()
- SDK for Python
-
以下 SDK for Python 代码将更新您的多区域接入点路由配置。要使用此示例语法，请将 user input
placeholders
s3.submit_multi_region_access_point_routes(
AccountId=111122223333,
Mrap=arn:aws:s3::111122223333:accesspoint/abcdef0123456.mrap,
RouteUpdates= [{
'Bucket': amzn-s3-demo-bucketap-southeast-2,
'TrafficDialPercentage': 10
}])
将对象添加到多区域接入点的桶中
要将对象添加到与多区域接入点关联的桶中，您可以使用 PutObject 操作。要使多区域接入点中的所有桶保持同步，请启用跨区域复制。
要使用此操作，您必须对多区域接入点拥有 s3:PutObject 权限。有关多区域接入点权限要求的更多信息，请参阅权限。
- AWS CLI
-
以下示例数据面板请求将 example.txtuser input
placeholders
aws s3api put-object --bucket arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap --key example.txt --body example.txt
- SDK for Java
-
S3Client s3Client = S3Client.builder()
.build();
PutObjectRequest objectRequest = PutObjectRequest.builder()
.bucket("arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap")
.key("example.txt")
.build();
s3Client.putObject(objectRequest, RequestBody.fromString("Hello S3!"));
- SDK for JavaScript
-
const client = new S3Client({});
async function putObjectExample() {
const command = new PutObjectCommand({
Bucket: "arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap",
Key: "example.txt",
Body: "Hello S3!",
});
try {
const response = await client.send(command);
console.log(response);
} catch (err) {
console.error(err);
}
}
- SDK for Python
-
import boto3
client = boto3.client('s3')
client.put_object(
Bucket='arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap',
Key='example.txt',
Body='Hello S3!'
)
从多区域接入点检索对象
要从多区域接入点检索对象，可以使用 GetObject 操作。
要使用此 API 操作，您必须对多区域接入点拥有 s3:GetObject 权限。有关多区域接入点权限要求的更多信息，请参阅权限。
- AWS CLI
-
以下示例数据面板请求从指定的多区域接入点检索 example.txtdownloaded_example.txtuser input
placeholders
aws s3api get-object --bucket arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap --key example.txt downloaded_example.txt
- SDK for Java
-
S3Client s3 = S3Client
.builder()
.build();
GetObjectRequest getObjectRequest = GetObjectRequest.builder()
.bucket("arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap")
.key("example.txt")
.build();
s3Client.getObject(getObjectRequest);
- SDK for JavaScript
-
const client = new S3Client({})
async function getObjectExample() {
const command = new GetObjectCommand({
Bucket: "arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap",
Key: "example.txt"
});
try {
const response = await client.send(command);
console.log(response);
} catch (err) {
console.error(err);
}
}
- SDK for Python
-
import boto3
client = boto3.client('s3')
client.get_object(
Bucket='arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap',
Key='example.txt'
)
列出存储在多区域接入点底层桶中的对象
要返回存储在多区域接入点底层桶中的对象的列表，请使用 ListObjectsV2 操作。在以下示例命令中，使用多区域接入点的 ARN 列出了指定多区域接入点的所有对象。在这种情况下，多区域接入点 ARN 为：
arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap
要使用此 API 操作，您必须对于多区域接入点和底层桶拥有 s3:ListBucket 权限。有关多区域接入点权限要求的更多信息，请参阅权限。
- AWS CLI
-
以下示例数据面板请求列出了桶中的对象，该桶位于 ARN 指定的多区域接入点的底层。要使用此示例，请将 user input placeholders
aws s3api list-objects-v2 --bucket arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap
- SDK for Java
-
S3Client s3Client = S3Client.builder()
.build();
String bucketName = "arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap";
ListObjectsV2Request listObjectsRequest = ListObjectsV2Request
.builder()
.bucket(bucketName)
.build();
s3Client.listObjectsV2(listObjectsRequest);
- SDK for JavaScript
-
const client = new S3Client({});
async function listObjectsExample() {
const command = new ListObjectsV2Command({
Bucket: "arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap",
});
try {
const response = await client.send(command);
console.log(response);
} catch (err) {
console.error(err);
}
}
- SDK for Python
-
import boto3
client = boto3.client('s3')
client.list_objects_v2(
Bucket='arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap'
)
将预签名 URL 与多区域接入点结合使用
您可以使用预签名 URL 生成一个 URL，该 URL 允许其他人通过 Amazon S3 多区域接入点访问 Amazon S3 存储桶。创建预签名 URL 时，请将它与特定的对象操作相关联，例如 S3 上传（PutObject）或 S3 下载（GetObject）。您可以共享预签名 URL，任何有权访问该 URL 的人都可以像原始签名用户一样执行嵌入在 URL 中的操作。
预签名 URL 具有到期日期。到达到期时间后，URL 将不再起作用。
在将 S3 多区域接入点与预签名 URL 结合使用之前，请检查 AWS SDK 与 SigV4A 算法的兼容性。验证您的 SDK 版本是否支持将 SigV4A 作为用于签署全局 AWS 区域请求的签名实现。有关在 Amazon S3 中使用预签名 URL 的更多信息，请参阅使用预签名 URL 共享对象。
以下示例说明如何将多区域接入点与预签名 URL 结合使用。要使用这些示例，请将 user input placeholders
- AWS CLI
-
aws s3 presign arn:aws:s3::123456789012:accesspoint/MultiRegionAccessPoint_alias/example-file.txt
- SDK for Python
-
import logging
import boto3
from botocore.exceptions import ClientError
s3_client = boto3.client('s3',aws_access_key_id='xxx',aws_secret_access_key='xxx')
s3_client.generate_presigned_url(HttpMethod='PUT',ClientMethod="put_object", Params={'Bucket':'arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap','Key':'example-file'})
- SDK for Java
-
S3Presigner s3Presigner = S3Presigner.builder()
.credentialsProvider(StsAssumeRoleCredentialsProvider.builder()
.refreshRequest(assumeRole)
.stsClient(stsClient)
.build())
.build();
GetObjectRequest getObjectRequest = GetObjectRequest.builder()
.bucket("arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap")
.key("example-file")
.build();
GetObjectPresignRequest preSignedReq = GetObjectPresignRequest.builder()
.getObjectRequest(getObjectRequest)
.signatureDuration(Duration.ofMinutes(10))
.build();
PresignedGetObjectRequest presignedGetObjectRequest = s3Presigner.presignGetObject(preSignedReq);
要将 SigV4A 与临时安全凭证结合使用 [例如，在使用 IAM 角色时]，请确保从 AWS Security Token Service（AWS STS）中的区域端点而非全局端点请求临时凭证。如果您对 AWS STS（sts.amazonaws.com）使用全局端点，则 AWS STS 将从全局端点生成临时证书，而 Sig4A 不支持全局端点。因此，您将得到错误。要解决此问题，请使用列出的任何适用于 AWS STS 的区域性端点。
将配置了申请方付款的桶与多区域接入点结合使用
如果与您的多区域接入点关联的 S3 存储桶配置为使用申请方付款，则申请方将支付桶请求费用、下载费用以及任何与多区域接入点相关的费用。有关更多信息，请参阅 Amazon S3 定价。
以下是向连接到申请方付款桶的多区域接入点发出数据面板请求的示例。
- AWS CLI
-
要从连接到申请方付款桶的多区域接入点下载对象，您必须指定 --request-payer requester 作为 get-object 请求的一部分。您还必须指定桶中文件的名称以及应存储所下载文件的位置。
aws s3api get-object --bucket MultiRegionAccessPoint_ARN --request-payer requester --key example-file-in-bucket.txt example-location-of-downloaded-file.txt
- SDK for Java
-
要从连接到申请方付款桶的多区域接入点下载对象，您必须指定 RequestPayer.REQUESTER 作为 GetObject 请求的一部分。您还必须指定桶中文件的名称及其存储位置。
GetObjectResponse getObjectResponse = s3Client.getObject(GetObjectRequest.builder()
.key("example-file.txt")
.bucket("arn:aws:s3::
123456789012:accesspoint/abcdef0123456.mrap")
.requestPayer(RequestPayer.REQUESTER)
.build()
).response();
