Utilisation de points d'accès multirégionaux avec des opérations prises en charge API

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 appelez 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 le AWS CLI AWS SDKs, ou. REST API 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, consultezRestrictions et limitations des points d'accès multi-régions.

En outre, vous devez accorder l's3:ListAllMyBucketsautorisation à l'utilisateur, au rôle ou à l'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 AWS servicesAWS 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 API opérations suivantes sur le plan de données Amazon S3 pour effectuer des actions sur des objets dans des compartiments associés à votre point d'accès multirégional. 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 du point d'accès multirégional. ARN

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 code Java suivant permet SDK de récupérer 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.

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 JavaScript code suivant permet SDK de récupérer la configuration de l'itinéraire de votre point d'accès multirégional 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.

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 code Python ci-dessous permet SDK de récupérer 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 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 compartiments 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

Ce qui suit SDK pour le code Java met à jour la configuration de routage de votre point d'accès multirégional. 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

Ce qui suit SDK pour le JavaScript code 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

Ce qui suit SDK pour le code Python met à jour la configuration de votre route de point d'accès multirégional. 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': DOC-EXAMPLE-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égion, vous pouvez utiliser l'opération PutObject. 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 téléchargement de demandes de plan de données suivant example.txt au point d'accès multirégional spécifié. Pour utiliser cet exemple, remplacez espaces réservés à la saisie par l'utilisateur avec 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égion, vous pouvez utiliser l'opération GetObject.

Note

Pour utiliser cette API opération, vous devez disposer de l's3:GetObjectautorisation pour le point d'accès multirégional. 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 extrait example.txt à partir du point d'accès multirégional spécifié et le télécharge sous downloaded_example.txt. Pour utiliser cet exemple, remplacez espaces réservés à la saisie par l'utilisateur avec 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 la liste des objets stockés dans un compartiment sous-jacent à votre point d'accès multirégion, utilisez l'opération ListObjectsV2. Dans l'exemple de commande suivant, tous les objets du point d'accès multirégional spécifié sont répertoriés à l'aide du point ARN d'accès multirégional. Dans ce cas, le point d'accès multirégional ARN est :

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

Note

Pour utiliser cette API opération, vous devez disposer de l's3:ListBucketautorisation pour le point d'accès multirégional et le bucket 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 du compartiment qui sous-tend le point d'accès multirégional spécifié par le. ARN Pour utiliser cet exemple, remplacez espaces réservés à la saisie par l'utilisateur avec 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'
)

Utilisez un point d'accès multirégional présigné URL

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

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

Avant d'utiliser des points d'accès multirégionaux S3 présignésURLs, vérifiez la AWS SDKcompatibilité avec l'algorithme SigV4A. Vérifiez que votre SDK version prend en charge SigV4a comme implémentation de signature utilisée pour signer les demandes 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 espaces réservés à la saisie par l'utilisateur avec 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 IAM rôles, assurez-vous de demander les informations d'identification temporaires à un point de terminaison régional situé dans AWS Security Token Service ()AWS STS, plutôt qu'à un point de terminaison global. 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 à partir d'un point d'accès multirégion connecté à un compartiment de type Paiement par le demandeur, vous devez spécifier --request-payer requester dans le cadre de votre demande get-object. 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();