Utilisation de points d’accès multi-régions avec des opérations d’API prises en charge

Amazon S3 fournit un ensemble d’opérations permettant de gérer les points d’accès multi-régions. Amazon S3 traite certaines de ces opérations de manière synchrone et d’autres de manière asynchrone. Lorsque vous invoquez une opération asynchrone, Amazon S3 autorise d’abord l’opération demandée de manière synchrone. Si l’autorisation réussit, Amazon S3 renvoie un jeton que vous pourrez utiliser pour suivre la progression et les résultats de l’opération demandée.

Note

Les demandes effectuées via la console Amazon S3 sont toujours synchrones. La console attend que la demande soit terminée avant de vous autoriser à envoyer une autre demande.

Vous pouvez consulter l'état actuel et les résultats des opérations asynchrones à l'aide de la console, ou DescribeMultiRegionAccessPointOperation dans l' AWS CLI API AWS SDKs REST. Amazon S3 fournit un jeton de suivi dans la réponse à une opération asynchrone. Vous devrez inclure ce jeton de suivi en tant qu’argument de DescribeMultiRegionAccessPointOperation. Quand vous incluez le jeton de suivi, Amazon S3 renvoie ensuite le statut actuel et les résultats de l’opération spécifiée, notamment les éventuelles erreurs ou informations pertinentes sur les ressources. Amazon S3 effectue les opérations DescribeMultiRegionAccessPointOperation de manière synchrone.

Toutes les demandes du plan de contrôle de création ou de gestion de points d'accès multirégions doivent être routées vers la région US West (Oregon). Pour les demandes de plan de données de points d'accès multirégions, il n'est pas nécessaire de spécifier les régions. Pour le plan de contrôle de basculement des points d’accès multirégions, la demande doit être routée vers l’une des cinq régions prises en charge. Pour plus d’informations sur les régions prises en charge par les points d’accès multirégionaux, consultez Restrictions et limitations des points d’accès multi-régions.

En outre, vous devez accorder l's3:ListAllMyBucketsautorisation à l'utilisateur, au rôle ou à toute autre entité AWS Identity and Access Management (IAM) qui fait une demande de gestion d'un point d'accès multirégional.

Les exemples suivants montrent comment utiliser des points d’accès multi-régions avec des opérations compatibles dans Amazon S3.

Compatibilité des points d'accès multirégionaux avec et Services AWSAWS SDKs

Pour utiliser un point d'accès multirégional avec des applications qui nécessitent un nom de compartiment Amazon S3, utilisez le nom de ressource Amazon (ARN) du point d'accès multirégional lorsque vous effectuez des demandes à l'aide d'un AWS SDK. Pour vérifier lesquels AWS SDKs sont compatibles avec les points d'accès multirégionaux, voir Compatibilité avec AWS SDKs.

Compatibilité du point d’accès multi-régions avec les opérations S3

Vous pouvez utiliser les opérations d’API du plan de données Amazon S3 suivantes pour effectuer des actions sur des objets dans des compartiments associés à votre point d’accès multirégion. Les opérations S3 suivantes peuvent accepter un point ARNs d'accès multirégional :

• AbortMultipartUpload

• CompleteMultipartUpload

• CreateMultipartUpload

• DeleteObject

• DeleteObjectTagging

• GetObject

• GetObjectAcl

• GetObjectLegalHold

• GetObjectRetention

• GetObjectTagging

• HeadObject

• ListMultipartUploads

• ListObjectsV2

• ListParts

• PutObject

• PutObjectAcl

• PutObjectLegalHold

• PutObjectRetention

• PutObjectTagging

• RestoreObject

• UploadPart

Note

Les points d’accès multirégionaux prennent en charge les opérations de copie utilisant des points d’accès multirégionaux uniquement comme destination lors de l’utilisation de l’ARN du point d’accès multirégional.

Vous pouvez utiliser les opérations de plan de contrôle Amazon S3 suivantes pour créer et gérer vos points d’accès multirégions :

• CreateMultiRegionAccessPoint

• DescribeMultiRegionAccessPointOperation

• GetMultiRegionAccessPoint

• GetMultiRegionAccessPointPolicy

• GetMultiRegionAccessPointPolicyStatus

• GetMultiRegionAccessPointRoutes

• ListMultiRegionAccessPoints

• PutMultiRegionAccessPointPolicy

• SubmitMultiRegionAccessPointRoutes

Visualisez la configuration du routage de votre point d’accès multi-régions.

AWS CLI

L’exemple de commande suivant récupère la configuration de l’itinéraire de votre point d’accès multi-régions afin que vous puissiez voir les statuts de routage actuels de vos compartiments. Pour utiliser cet exemple de commande, remplacez user input placeholders par vos propres informations.

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

Le kit SDK suivant pour le code Java récupère la configuration de l’itinéraire de votre point d’accès multi-régions afin que vous puissiez voir les statuts de routage actuels de vos compartiments. Pour utiliser cet exemple de syntaxe, remplacez user input placeholders par vos propres informations.

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

Le SDK pour le JavaScript code suivant récupère la configuration de votre itinéraire de point d'accès multirégional afin que vous puissiez voir les statuts de routage actuels de vos buckets. Pour utiliser cet exemple de syntaxe, remplacez user input placeholders par vos propres informations.

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

Le kit SDK suivant pour le code Python récupère la configuration des itinéraires de votre point d’accès multi-régions afin que vous puissiez voir les statuts de routage actuels de vos compartiments. Pour utiliser cet exemple de syntaxe, remplacez user input placeholders par vos propres informations.

s3.get_multi_region_access_point_routes(
        AccountId=111122223333,
        Mrap=arn:aws:s3::111122223333:accesspoint/abcdef0123456.mrap)['Routes']

Mettez à jour votre politique de compartiment Amazon S3 sous-jacente.

Pour accorder un accès approprié, vous devez également mettre à jour la politique sous-jacente du compartiment Amazon S3. Les exemples suivants délèguent le contrôle d’accès à la politique du point d’accès multi-régions. Une fois que vous avez délégué le contrôle d’accès à la politique de point d’accès multi-régions, la politique de compartiment n’est plus utilisée pour le contrôle d’accès lors de demandes effectuées via ce point d’accès.

Voici un exemple de politique de compartiment qui délègue le contrôle d’accès à la politique de point d’accès multi-régions. Pour utiliser cet exemple de politique de compartiment, remplacez user input placeholders par vos propres informations. Pour appliquer cette politique par le biais de la AWS CLI put-bucket-policy commande, comme indiqué dans l'exemple suivant, enregistrez la politique dans un fichier, par exemplepolicy.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"
      }
    }
  }
}

L’exemple de commande put-bucket-policy suivant associe la politique de compartiment S3 mise à jour à votre compartiment S3 :

aws s3api put-bucket-policy
  --bucket amzn-s3-demo-bucket
  --policy file:///tmp/policy.json

Mise à jour de la configuration des itinéraires d’un point d’accès multi-régions

L’exemple de commande suivant met à jour la configuration des itinéraires du point d’accès multi-régions. Les commandes d’itinéraire des points d’accès multi-régions peuvent être exécutées dans les cinq régions suivantes :

• ap-southeast-2

• ap-northeast-1

• us-east-1

• us-west-2

• eu-west-1

Dans une configuration de routage de point d’accès multi-régions, vous pouvez définir des compartiments avec un statut de routage actif ou passif. Les compartiments actifs reçoivent du trafic, tandis que les compartiments passifs n’en reçoivent pas. Vous pouvez définir le statut de routage d’un compartiment en définissant la valeur TrafficDialPercentage de ce dernier sur 100 pour actif ou 0 pour passif.

AWS CLI

L’exemple de commande suivant met à jour la configuration du routage de votre point d’accès multi-régions. Dans cet exemple, la valeur amzn-s3-demo-bucket1 est réglée sur le statut actif et amzn-s3-demo-bucket2 est réglée sur le statut passif. Pour utiliser cet exemple de commande, remplacez user input placeholders par vos propres informations.

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

Le kit SDK suivant pour le code Java met à jour la configuration de l’itinéraire de votre point d’accès multi-régions. Pour utiliser cet exemple de syntaxe, remplacez user input placeholders par vos propres informations.

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

Le SDK de JavaScript code suivant met à jour la configuration de votre itinéraire de point d'accès multirégional. Pour utiliser cet exemple de syntaxe, remplacez user input placeholders par vos propres informations.

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

Le kit SDK suivant pour le code Python met à jour la configuration de l’itinéraire de votre point d’accès multi-régions. Pour utiliser cet exemple de syntaxe, remplacez user input placeholders par vos propres informations.

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

Ajouter un objet à un compartiment dans votre point d’accès multirégion

Pour ajouter un objet au compartiment associé au point d'accès multirégional, vous pouvez utiliser PutObjectopération. Pour maintenir synchronisés tous les compartiments dans le point d’accès multirégion, activez la réplication entre régions.

Note

Pour utiliser cette opération, vous devez disposer de l’autorisation s3:PutObject pour le point d’accès multirégion. Pour plus d’informations sur les exigences relatives aux autorisations des points d’accès multirégions, consultez Autorisations.

AWS CLI

L’exemple de demande de plan de données suivant charge example.txt dans le point d’accès multirégion spécifié. Pour utiliser cet exemple, remplacez user input placeholders par vos propres informations.

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!'
)

Récupération d’objets depuis votre point d’accès multirégion

Pour récupérer des objets depuis le point d'accès multirégional, vous pouvez utiliser GetObjectopération.

Note

Pour utiliser cette opération d’API, vous devez disposer de l’autorisation s3:GetObject pour le point d’accès multirégion. Pour plus d’informations sur les exigences relatives aux autorisations des points d’accès multirégions, consultez Autorisations.

AWS CLI

L’exemple de demande de plan de données suivant récupère example.txt depuis le point d’accès multirégion spécifié et le télécharge en tant que downloaded_example.txt. Pour utiliser cet exemple, remplacez user input placeholders par vos propres informations.

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

Liste des objets stockés dans un compartiment sous-jacent à votre point d’accès multirégion

Pour renvoyer une liste d'objets stockés dans un compartiment sous-jacent à votre point d'accès multirégional, utilisez ListObjectsV2opération. Dans l’exemple de commande suivant, tous les objets du point d’accès multirégion spécifié sont répertoriés à l’aide de l’ARN du point d’accès multirégion. Dans ce cas, l’ARN du point d’accès multirégion est :

arn:aws:s3::123456789012:accesspoint/abcdef0123456.mrap

Note

Pour utiliser cette opération d’API, vous devez disposer de l’autorisation s3:ListBucket pour le point d’accès multirégion et le compartiment sous-jacent. Pour plus d'informations sur les exigences relatives aux autorisations des points d'accès multirégions, consultez Autorisations.

AWS CLI

L’exemple de demande de plan de données suivant répertorie les objets présents dans le compartiment sous-jacent au point d’accès multirégion spécifié par l’ARN. Pour utiliser cet exemple, remplacez user input placeholders par vos propres informations.

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

Utiliser une URL présignée avec des points d’accès multi-régions

Vous pouvez utiliser une URL présignée pour générer une URL permettant aux autres d’accéder à vos compartiments Amazon S3 via un point d’accès multirégion Amazon S3. Lorsque vous créez une URL présignée, vous l’associez à une action d’objet spécifique, telle qu’un chargement S3 (PutObject) ou un téléchargement S3 (GetObject). Vous pouvez partager l’URL présignée, et toute personne y ayant accès peut effectuer l’action intégrée dans l’URL comme s’il s’agissait de l’utilisateur connecté d’origine.

Les documents présignés URLs ont une date d'expiration. Lorsque le délai d’expiration est atteint, l’URL ne fonctionne plus.

Avant d'utiliser des points d'accès multirégionaux S3 présignés URLs, vérifiez la compatibilité du AWS SDK avec l'algorithme SigV4A. Vérifiez que la version de votre kit SDK prend en charge SigV4A comme mise en œuvre de la signature qui est utilisée pour signer les requêtes globales Région AWS . Pour plus d'informations sur l'utilisation de Presigned URLs avec Amazon S3, consultez Partage d'objets à l'aide de URLs Presigned.

Les exemples suivants montrent comment utiliser des points d'accès multirégionaux URLs présignés. Pour utiliser ces exemples, remplacez user input placeholders par vos propres informations.

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

Note

Pour utiliser SigV4A avec des informations d'identification de sécurité temporaires, par exemple, lorsque vous utilisez des rôles IAM, assurez-vous de demander les informations d'identification temporaires à un point de terminaison régional situé dans AWS Security Token Service (), plutôt qu'à un point de terminaison global.AWS STS Si vous utilisez le point de terminaison global pour AWS STS (sts.amazonaws.com), AWS STS cela générera des informations d'identification temporaires à partir d'un point de terminaison global, ce qui n'est pas pris en charge par Sig4A. Par conséquent, vous obtenez une erreur. Pour résoudre ce problème, utilisez l'un des points de terminaison régionaux répertoriés pour AWS STS.

Utiliser un compartiment configuré avec Requester Pays avec des points d’accès multi-régions

Si un compartiment S3 associé à vos points d’accès multirégions est configuré pour utiliser le paiement par le demandeur, le demandeur paiera à la fois la demande de compartiment, le téléchargement et tous les coûts liés aux points d’accès multirégions. Pour plus d’informations, consultez Tarification Amazon S3.

Voici un exemple de demande de plan de données adressée à un point d’accès multirégion connecté à un compartiment de type Paiement par le demandeur.

AWS CLI

Pour télécharger des objets depuis un point d'accès multirégional connecté à un bucket Requester Pays, vous devez le spécifier dans --request-payer requester le cadre de votre get-object de la demande. Vous devez également spécifier le nom du fichier dans le compartiment, ainsi que l’emplacement où le fichier téléchargé doit être stocké.

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

Pour télécharger des objets à partir d’un point d’accès multirégion connecté à un compartiment de type Paiement par le demandeur, vous devez spécifier RequestPayer.REQUESTER dans le cadre de votre demande GetObject. Vous devez également spécifier le nom du fichier dans le compartiment, ainsi que l’emplacement où il doit être stocké.

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