Uso de puntos de acceso de varias regiones con operaciones API admitidas - Amazon Simple Storage Service
Compatibilidad de punto de acceso de varias regiones con Servicios de AWS y los SDK de AWSCompatibilidad de punto de acceso de varias regiones con operaciones de S3Consultar la configuración de enrutamiento de puntos de acceso de varias regionesActualizar la política de bucket de Amazon S3 subyacenteActualizar una configuración de enrutamiento del punto de acceso multirregionalAñadir un objeto a un bucket en el punto de acceso de varias regionesRecuperar objetos de un punto de acceso de varias regionesEnumerar los objetos que están almacenados en un bucket subyacente a su punto de acceso de varias regionesUtilice una URL prefirmada con puntos de acceso de varias regionesUso de un bucket que se configura con pago por solicitante con puntos de acceso de varias regiones

Uso de puntos de acceso de varias regiones con operaciones API admitidas

Amazon S3 proporciona un conjunto de operaciones para administrar puntos de acceso de varias regiones. Amazon S3 procesa algunas de estas operaciones de forma sincrónica y otras asíncrona. Cuando se invoca una operación asincrónica, Amazon S3 primero autoriza sincrónicamente la operación solicitada. Si la autorización se realiza correctamente, Amazon S3 devuelve un token que puede utilizar para realizar un seguimiento del progreso y los resultados de la operación solicitada.

nota

Las solicitudes que se realizan a través de la consola de Amazon S3 siempre son sincrónicas. La consola espera hasta que se complete la solicitud antes de permitirle enviar otra solicitud.

Puede ver el estado actual y los resultados de las operaciones asíncronas mediante la consola, o puede usar DescribeMultiRegionAccessPointOperation en la AWS CLI, los SDK de AWS o la API de REST. Amazon S3 proporciona un token de seguimiento en la respuesta a una operación asincrónica. Incluya ese token de seguimiento como argumento para DescribeMultiRegionAccessPointOperation. Si incluye el token de seguimiento, Amazon S3 devuelve el estado actual y los resultados de la operación especificada, incluidos los errores o la información pertinente de los recursos. Amazon S3 realiza operaciones de DescribeMultiRegionAccessPointOperation de forma sincrónica.

Todas las solicitudes de plano de control para crear o mantener puntos de acceso de varias regiones se dirigen a la región US West (Oregon). Para las solicitudes de plano de datos de puntos de acceso de varias regiones, no es necesario especificar las regiones. Para el plano de control de la conmutación por error del punto de acceso de varias regiones, la solicitud debe dirigirse a una de las cinco regiones admitidas. Para obtener más información acerca de la regiones admitidas por el punto de acceso multiregional, consulte Restricciones y limitaciones de puntos de acceso de varias regiones.

Además, deberá otorgar el permiso s3:ListAllMyBuckets al usuario, rol u otra entidad de AWS Identity and Access Management (IAM) que realice una solicitud para administrar un punto de acceso de varias regiones.

Los ejemplos siguientes muestran cómo utilizar puntos de acceso de varias regiones con operaciones compatibles en Amazon S3.

Compatibilidad de punto de acceso de varias regiones con Servicios de AWS y los SDK de AWS

Para usar un punto de acceso de varias regiones con aplicaciones que requieren un nombre de bucket de Amazon S3, utilice el nombre de recurso de Amazon (ARN) del punto de acceso de varias regiones al realizar solicitudes con un SDK de AWS. Para comprobar si los SDK de AWS son compatibles con los puntos de acceso de varias regiones, consulte Compatibilidad con los SDK de AWS.

Compatibilidad de punto de acceso de varias regiones con operaciones de S3

Puede utilizar las siguientes operaciones de la API del plano de datos de Amazon S3 para realizar acciones en los objetos de los buckets asociados a su punto de acceso de varias regiones. Las siguientes operaciones de S3 pueden aceptar ARN de punto de acceso multirregional:

nota

Los puntos de acceso de varias regiones admiten operaciones de copia con puntos de acceso de varias regiones solo como destino o cuando se utiliza el ARN del punto de acceso de varias regiones.

Puede utilizar las siguientes operaciones del plano de control de Amazon S3 para crear y administrar sus puntos de acceso de varias regiones:

Consultar la configuración de enrutamiento de puntos de acceso de varias regiones

AWS CLI

El comando de ejemplo siguiente recupera la configuración de enrutamiento del punto de acceso multirregional para que pueda ver los estados de enrutamiento actuales de los buckets. Para utilizar este comando de ejemplo, sustituya user input placeholders por su propia información.

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

El código de SDK para Java siguiente recupera la configuración de enrutamiento del punto de acceso multirregional para que pueda ver los estados de enrutamiento actuales de los buckets. Para utilizar esta sintaxis de ejemplo, sustituya user input placeholders por su propia información.

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

El código de SDK para JavaScript siguiente recupera la configuración de enrutamiento del punto de acceso multirregional para que pueda ver los estados de enrutamiento actuales de los buckets. Para utilizar esta sintaxis de ejemplo, sustituya user input placeholders por su propia información.

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

El código de SDK para Python siguiente recupera la configuración de enrutamiento del punto de acceso multirregional para que pueda ver los estados de enrutamiento actuales de los buckets. Para utilizar esta sintaxis de ejemplo, sustituya user input placeholders por su propia información.

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

Actualizar la política de bucket de Amazon S3 subyacente

Para conceder el acceso adecuado, también debe actualizar la política de bucket de Amazon S3 subyacente. En el siguiente ejemplo se delega el control de acceso a la política de punto de acceso de varias regiones. Tras delegar el control de acceso a la política de punto de acceso de varias regiones, la política de bucket ya no se utiliza para el control de acceso cuando las solicitudes se realizan a través de ese punto de acceso de varias regiones.

A continuación, se muestra un ejemplo de política de bucket que delega el control de acceso a la política de punto de acceso multirregional. Para utilizar esta política de bucket de ejemplo, sustituya user input placeholders por su propia información. Para aplicar esta política mediante el comando AWS CLI put-bucket-policy, tal como se muestra en el siguiente ejemplo, guarde la política en un archivo, por ejemplo, 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"
      }
    }
  }
}

El comando de ejemplo put-bucket-policy siguiente asocia la política de bucket de S3 actualizada al bucket de S3:

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

Actualizar una configuración de enrutamiento del punto de acceso multirregional

El comando de ejemplo siguiente actualiza la configuración de enrutamiento del punto de acceso multirregional. Puede ejecutar comandos de enrutamiento de puntos de acceso de varias regiones en cualquiera de las siguientes cinco regiones:

  • ap-southeast-2

  • ap-northeast-1

  • us-east-1

  • us-west-2

  • eu-west-1

En una configuración de enrutamiento de puntos de acceso de varias regiones, puede configurar los buckets en un estado de enrutamiento activo o pasivo. Los buckets activos reciben tráfico, mientras que los buckets pasivos no. Puede establecer el estado de enrutamiento de un bucket configurando el valor TrafficDialPercentage del bucket en 100 para activo o 0 para pasivo.

AWS CLI

El comando de ejemplo siguiente actualiza la configuración de enrutamiento del punto de acceso multirregional. En este ejemplo, amzn-s3-demo-bucket1 se establece en estado activo y amzn-s3-demo-bucket2 en pasivo. Para utilizar este comando de ejemplo, sustituya user input placeholders por su propia información.

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

El código de SDK para Java siguiente actualiza la configuración de enrutamiento del punto de acceso multirregional. Para utilizar esta sintaxis de ejemplo, sustituya user input placeholders por su propia información.

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

El código de SDK para JavaScript siguiente actualiza la configuración de enrutamiento del punto de acceso multirregional. Para utilizar esta sintaxis de ejemplo, sustituya user input placeholders por su propia información.

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

El código de SDK para Python siguiente actualiza la configuración de enrutamiento del punto de acceso multirregional. Para utilizar esta sintaxis de ejemplo, sustituya user input placeholders por su propia información.

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

Añadir un objeto a un bucket en el punto de acceso de varias regiones

Para añadir un objeto al bucket asociado al punto de acceso de varias regiones, puede utilizar la operación PutObject. Para mantener sincronizados todos los buckets del punto de acceso de varias regiones, habilite la replicación entre regiones.

nota

Para utilizar esta operación, debe tener el permiso s3:PutObject para el punto de acceso de varias regiones. Para obtener más información acerca de los requisitos de los permisos del punto de acceso de varias regiones, consulte Permisos.

AWS CLI

El siguiente ejemplo de solicitud de plano de datos carga example.txt en el punto de acceso de varias regiones especificado. Para utilizar este ejemplo, reemplace los user input placeholders con su propia información.

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

Recuperar objetos de un punto de acceso de varias regiones

Para recuperar objetos del punto de acceso de varias regiones, puede utilizar la operaciónGetObject.

nota

Para utilizar esta operación de la API, debe tener el permiso s3:GetObject para el punto de acceso de varias regiones. Para obtener más información acerca de los requisitos de los permisos del punto de acceso de varias regiones, consulte Permisos.

AWS CLI

El siguiente ejemplo de solicitud de plano de datos recupera example.txt del punto de acceso de varias regiones especificado y lo descarga como downloaded_example.txt. Para utilizar este ejemplo, reemplace los user input placeholders con su propia información.

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

Enumerar los objetos que están almacenados en un bucket subyacente a su punto de acceso de varias regiones

Para devolver una lista de objetos que están almacenados en un bucket subyacente a su punto de acceso de varias regiones, use la operación ListObjectsV2. En el siguiente comando de ejemplo, todos los objetos del punto de acceso de varias regiones especificado se enumeran con el ARN del punto de acceso de varias regiones. En este caso, el ARN del punto de acceso de varias regiones es:

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

nota

Para utilizar esta operación de la API, debe tener el permiso s3:ListBucket para el punto de acceso de varias regiones y el bucket subyacente. Para obtener más información acerca de los requisitos de los permisos del punto de acceso de varias regiones, consulte Permisos.

AWS CLI

En el siguiente ejemplo de solicitud de plano de datos se enumeran los objetos del bucket que subyace al punto de acceso de varias regiones especificado por el ARN. Para utilizar este ejemplo, reemplace los user input placeholders con su propia información.

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

Utilice una URL prefirmada con puntos de acceso de varias regiones

Puede usar una URL prefirmada para generar una URL que permita a los demás acceder a los buckets de Amazon S3 a través de un punto de acceso de varias regiones de Amazon S3. Cuando crea una URL prefirmada, la asocia a una acción de objeto específica, como una carga de S3 (PutObject) o una descarga de S3 (GetObject). Puede compartir la URL prefirmada y cualquiera que tenga acceso a ella puede realizar la acción incrustada en la URL como si fuera el usuario de la firma original.

Las URL prefirmadas tienen fecha de vencimiento. Cuando se alcance el tiempo del vencimiento, la URL dejará de funcionar.

Antes de utilizar los puntos de acceso de varias regiones de S3 con URL prefirmadas, compruebe la Compatibilidad del SDK de AWS con el algoritmo SigV4A. Compruebe que la versión del SDK sea compatible con SigV4A como implementación de firma que se utiliza para firmar las solicitudes de Región de AWS globales. Para obtener más información sobre el uso de las URL prefirmadas con Amazon S3, consulte Compartir objetos mediante URL prefirmadas.

En los siguientes ejemplos, se muestra cómo puede utilizar puntos de acceso de varias regiones con URL prefirmadas. Para utilizar estos ejemplos, sustituya user input placeholders por su propia información.

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

Para usar SigV4a con credenciales de seguridad temporales (por ejemplo, cuando se utilizan roles de IAM), asegúrese de solicitar las credenciales temporales desde un punto de conexión regional en AWS Security Token Service (AWS STS), en lugar de un punto de conexión global. Si usa el punto de conexión global para AWS STS (sts.amazonaws.com), AWS STS generará credenciales temporales a partir de un punto de conexión global, lo cual no es compatible con Sig4A. Como resultado, obtendrá un error. Para resolver este problema, utilice cualquiera de los Puntos de conexión regionales para AWS STS.

Uso de un bucket que se configura con pago por solicitante con puntos de acceso de varias regiones

Si el bucket de S3 asociado a sus puntos de acceso de varias regiones está configurado para usar Pago por solicitante, el solicitante pagará tanto por la solicitud de bucket y la descarga, como por los costos relacionados con los puntos de acceso de varias regiones. Para obtener más información, consulte Precios de Amazon S3.

Este es un ejemplo de una solicitud de plano de datos a un punto de acceso de varias regiones que está conectado a un bucket Pago por solicitante.

AWS CLI

Para descargar objetos de un punto de acceso de varias regiones que está conectado a un bucket Pago por solicitante, especifique --request-payer requester como parte de la solicitud get-object. También debe especificar el nombre del archivo en el bucket, así como la ubicación en la que debe almacenarse.

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

Para descargar objetos de un punto de acceso de varias regiones que está conectado a un bucket Pago por solicitante, especifique RequestPayer.REQUESTER como parte de la solicitud GetObject. También debe especificar el nombre del archivo en el bucket, así como la ubicación en la que debe almacenarse.

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