マルチリージョンアクセスポイントでのサポートされている 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) リージョンにルーティングされる必要があります。マルチリージョンアクセスポイントのデータプレーンリクエストでは、リージョンを指定する必要はありません。マルチリージョンアクセスポイントのフェイルオーバーコントロールプレーンの場合、リクエストは 5 つのサポートされているリージョンのいずれかにルーティングされる必要があります。マルチリージョンアクセスポイントのサポートされているリージョンの詳細については、「マルチリージョンアクセスポイントの制約および制限事項」を参照してください。

さらに、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 を使用できます。

• AbortMultipartUpload

• CompleteMultipartUpload

• CreateMultipartUpload

• DeleteObject

• DeleteObjectTagging

• GetObject

• GetObjectAcl

• GetObjectLegalHold

• GetObjectRetention

• GetObjectTagging

• HeadObject

• ListMultipartUploads

• ListObjectsV2

• ListParts

• PutObject

• PutObjectAcl

• PutObjectLegalHold

• PutObjectRetention

• PutObjectTagging

• RestoreObject

• UploadPart

注記

マルチリージョンアクセスポイントは、マルチリージョンアクセスポイント ARN を使用する場合に限り、マルチリージョンアクセスポイントを宛先とするコピー操作をサポートします。

マルチリージョンアクセスポイントの作成と管理には、次の Amazon S3 コントロールプレーンオペレーションを使用できます。

• CreateMultiRegionAccessPoint

• DescribeMultiRegionAccessPointOperation

• GetMultiRegionAccessPoint

• GetMultiRegionAccessPointPolicy

• GetMultiRegionAccessPointPolicyStatus

• GetMultiRegionAccessPointRoutes

• ListMultiRegionAccessPoints

• PutMultiRegionAccessPointPolicy

• SubmitMultiRegionAccessPointRoutes

マルチリージョンアクセスポイントのルーティング設定を表示する

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 placeholders をユーザー自身の情報に置き換えます。このポリシーを AWS CLI put-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

マルチリージョンアクセスポイントのルート設定を更新する

以下のコマンド例では、マルチリージョンアクセスポイントのルート設定も更新します。マルチリージョンアクセスポイントのルートコマンドは、次の 5 つのリージョンに対して実行できます。

• ap-southeast-2

• ap-northeast-1

• us-east-1

• us-west-2

• eu-west-1

マルチリージョンアクセスポイントのルーティング設定では、バケットをアクティブまたはパッシブのルーティングステータスに設定できます。アクティブバケットはトラフィックを受信しますが、パッシブバケットは受信しません。バケットの TrafficDialPercentage 値を 100 に設定するとアクティブ、0 に設定するとパッシブになり、バケットのルーティングステータスを設定できます。

AWS CLI

以下のコマンド例では、マルチリージョンアクセスポイントのルーティング設定も更新します。この例では、amzn-s3-demo-bucket1 がアクティブステータスに設定され、amzn-s3-demo-bucket2 がパッシブに設定されています。このコマンドの例を実行するには、user 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-bucket,
            'Region': ap-southeast-2, 
            'TrafficDialPercentage': 10
        }])

マルチリージョンアクセスポイントのバケットへのオブジェクトの追加

マルチリージョンアクセスポイントに関連付けられているバケットにオブジェクトを追加するには、PutObject オペレーションを使用できます。マルチリージョンアクセスポイントのすべてのバケットを同期させるには、[クロスリージョンレプリケーション] を有効にします。

注記

このオペレーションを使用するには、マルチリージョンアクセスポイントの s3:PutObject アクセス許可が必要です。マルチリージョンアクセスポイントのアクセス許可の要件の詳細については、「アクセス許可」を参照してください。

AWS CLI

次の例のデータプレーンリクエストは、指定されたマルチリージョンアクセスポイントに example.txt をアップロードします。この例を実行するには、user 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.txt を取得し、それを downloaded_example.txt としてダウンロードします。この例を実行するには、user 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 を使用すると、他のユーザーが Amazon S3 マルチリージョンアクセスポイントを介して Amazon S3 バケットにアクセスするための URL を生成することができます。署名付き URL を作成したら、その署名付き URL を S3 アップロード (PutObject) や S3 ダウンロード (GetObject) などの特定のオブジェクトアクションに関連付けます。署名付き URL を共有すると、URL へのアクセス権を持つユーザーは、URL に埋め込まれたアクションを、元の署名ユーザーであるかのように実行できます。

署名付き URL には有効期限があります。有効期限に達すると、URL は機能しなくなります。

署名付き URL で S3 マルチリージョンアクセスポイントを使用する前に、Sigv4A アルゴリズムと AWS SDK との互換性を確認してください。ご使用の SDK バージョンが、グローバル AWS リージョン リクエストの署名に使用される署名実装として SigV4AA をサポートしていることを確認してください。Amazon S3 での署名付き URL の使用について詳しくは、「Sharing objects by using presigned 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

リクエスタ支払いバケットに接続したマルチリージョンアクセスポイントからオブジェクトをダウンロードするには、get-object リクエストの一部として --request-payer requester を指定する必要があります。また、バケット内のファイルの名前と、ダウンロードファイルを保存する場所を指定する必要があります。

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

リクエスタ支払いバケットに接続したマルチリージョンアクセスポイントからオブジェクトをダウンロードするには、GetObject リクエストの一部として RequestPayer.REQUESTER を指定する必要があります。また、バケット内のファイルの名前と、ファイルを保存する場所を指定する必要があります。

GetObjectResponse getObjectResponse = s3Client.getObject(GetObjectRequest.builder()
    .key("example-file.txt")
    .bucket("arn:aws:s3::
123456789012:accesspoint/abcdef0123456.mrap")
    .requestPayer(RequestPayer.REQUESTER)
    .build()
).response();