Usar endpoints de pilha dupla do Amazon S3

Os endpoints de pilha dupla do Amazon S3 oferecem suporte para buckets do S3 por IPv6 e IPv4. Esta seção descreve como usar os endpoints de pilha dupla.

Endpoints de pilha dupla do Amazon S3

Quando você faz uma solicitação para um endpoint de pilha dupla, o URL do bucket resolve para um endereço IPv6 ou IPv4. Para obter mais informações sobre como acessar um bucket por meio do IPv6, consulte Fazer solicitações para o Amazon S3 por meio do IPv6.

Ao usar a API REST, você acessa diretamente um endpoint do Amazon S3 usando o nome do endpoint (URI). Você pode acessar um bucket do S3 por meio de um endpoint de pilha dupla usando um nome de endpoint de estilo de hospedagem virtual ou de estilo de caminho. O Amazon S3 oferece suporte apenas a nomes regionais de endpoint de pilha dupla, o que significa que você deve especificar a região como parte do nome.

Use as seguintes convenções de atribuição de nomes para os nomes de endpoint de estilo de hospedagem virtual e de estilo de caminho de pilha dupla:

• Endpoint de pilha dupla de estilo de hospedagem virtual

  bucketname.s3.dualstack.aws-region.amazonaws.com

   

• Endpoint de pilha dupla de estilo de caminho:

  s3.dualstack.aws-region.amazonaws.com/bucketname

Para obter mais informações sobre estilo de nome de endpoints, consulte Acessar e listar um bucket do Amazon S3. Para obter uma lista dos endpoints do Amazon S3, consulte Regiões e endpoints na Referência geral da AWS.

Importante

Você pode usar a aceleração de transferência com endpoints de pilha dupla. Para ter mais informações, consulte Conceitos básicos do Amazon S3 Transfer Acceleration.

nota

Os dois tipos de endpoint da VPC para acessar o Amazon S3 (endpoints de interface da VPC e endpoints de VPC do gateway) não são compatíveis com pilha dupla. Para obter mais informações sobre os endpoints da VPC para o Amazon S3, consulte AWS PrivateLink for Amazon S3.

Ao usar a AWS Command Line Interface (AWS CLI) e os AWS SDKs, você pode utilizar um parâmetro ou um sinalizador para mudar para um endpoint de pilha dupla. Você também pode especificar o endpoint de pilha dupla diretamente como uma substituição do endpoint do Amazon S3 no arquivo de configuração. As seções a seguir descrevem como usar endpoints de pilha dupla da AWS CLI e dos AWS SDKs.

Usar endpoints de pilha dupla da AWS CLI

Esta seção fornece exemplos de comandos da AWS CLI usados para fazer solicitações a um endpoint de pilha dupla. Para obter instruções de configuração da AWS CLI, consulte Desenvolvimento com o Amazon S3 usando a AWS CLI.

Você define o valor de configuração use_dualstack_endpoint para true em um perfil no seu arquivo do AWS Config para direcionar todas as solicitações do Amazon S3 feitas pelos comandos s3 e s3api da AWS CLI ao endpoint de pilha dupla para a região especificada. Especifique a região no arquivo de configuração ou em um comando usando a opção --region.

Quando se usa endpoints de pilha dupla com a AWS CLI, os estilos de endereçamento path e virtual são compatíveis. O estilo de endereçamento, definido no arquivo de configuração, controla se o nome do bucket está no hostname ou em parte do URL. Por padrão, a CLI tentará usar o estilo virtual sempre que possível, mas voltará ao estilo de caminho se necessário. Para obter mais informações, consulte Configuração do Amazon S3 da AWS CLI.

Você também pode fazer alterações de configuração usando um comando, conforme mostrado no exemplo a seguir que define use_dualstack_endpoint para true e addressing_style para virtual no perfil padrão.

$ aws configure set default.s3.use_dualstack_endpoint true
$ aws configure set default.s3.addressing_style virtual

Se quiser usar um endpoint de pilha dupla apenas para comandos especificados da AWS CLI, (nem todos os comandos), você pode usar qualquer um dos métodos a seguir:

• Você pode usar o endpoint de pilha dupla por comando, definindo o parâmetro --endpoint-url como https://s3.dualstack.aws-region.amazonaws.com ou http://s3.dualstack.aws-region.amazonaws.com para qualquer comando s3 ou s3api.

  $ aws s3api list-objects --bucket bucketname --endpoint-url https://s3.dualstack.aws-region.amazonaws.com

• Você pode configurar perfis separados em seu arquivo do AWS Config. Por exemplo, crie um perfil que defina use_dualstack_endpoint como true e um perfil que não defina use_dualstack_endpoint. Quando executar um comando, especifique qual perfil deseja usar, dependendo de querer ou não usar o endpoint de pilha dupla.

nota

Atualmente, ao usar a AWS CLI, você não pode usar a aceleração de transferência com endpoints de pilha dupla. Contudo, o suporte para a AWS CLI estará disponível em breve. Para obter mais informações, consulte Usando a AWS CLI.

Usar endpoints de pilha dupla dos AWS SDKs

Esta seção fornece exemplos de como acessar um endpoint de pilha dupla usando os AWS SDKs.

AWS SDK for JavaExemplo do endpoint de pilha dupla do

O exemplo a seguir mostra como habilitar endpoints de pilha dupla ao criar um cliente do Amazon S3 usando o AWS SDK for Java.

Para obter instruções sobre criar e testar um exemplo funcional Java, consulte Testar exemplos de código Java no Amazon S3.

import com.amazonaws.AmazonServiceException;
import com.amazonaws.SdkClientException;
import com.amazonaws.auth.profile.ProfileCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;

public class DualStackEndpoints {

    public static void main(String[] args) {
        Regions clientRegion = Regions.DEFAULT_REGION;
        String bucketName = "*** Bucket name ***";

        try {
            // Create an Amazon S3 client with dual-stack endpoints enabled.
            AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
                    .withCredentials(new ProfileCredentialsProvider())
                    .withRegion(clientRegion)
                    .withDualstackEnabled(true)
                    .build();

            s3Client.listObjects(bucketName);
        } catch (AmazonServiceException e) {
            // The call was transmitted successfully, but Amazon S3 couldn't process
            // it, so it returned an error response.
            e.printStackTrace();
        } catch (SdkClientException e) {
            // Amazon S3 couldn't be contacted for a response, or the client
            // couldn't parse the response from Amazon S3.
            e.printStackTrace();
        }
    }
}

Se estiver usando o AWS SDK for Java no Windows, você talvez tenha de definir a seguinte propriedade da máquina virtual Java (JVM):

java.net.preferIPv6Addresses=true

AWSExemplo do endpoint de pilha dupla do SDK para .NET

Ao usar o AWS SDK for .NET você, você usa a classe AmazonS3Config para permitir o uso de um endpoint de pilha dupla, como mostrado no exemplo a seguir.

using Amazon;
using Amazon.S3;
using Amazon.S3.Model;
using System;
using System.Threading.Tasks;

namespace Amazon.DocSamples.S3
{
    class DualStackEndpointTest
    {
        private const string bucketName = "*** bucket name ***";
        // Specify your bucket region (an example region is shown).
        private static readonly RegionEndpoint bucketRegion = RegionEndpoint.USWest2;
        private static IAmazonS3 client;

        public static void Main()
        {
            var config = new AmazonS3Config
            {
                UseDualstackEndpoint = true,
                RegionEndpoint = bucketRegion
            };
            client = new AmazonS3Client(config);
            Console.WriteLine("Listing objects stored in a bucket");
            ListingObjectsAsync().Wait();
        }

        private static async Task ListingObjectsAsync()
        {
            try
            {
                var request = new ListObjectsV2Request
                {
                    BucketName = bucketName,
                    MaxKeys = 10
                };
                ListObjectsV2Response response;
                do
                {
                    response = await client.ListObjectsV2Async(request);

                    // Process the response.
                    foreach (S3Object entry in response.S3Objects)
                    {
                        Console.WriteLine("key = {0} size = {1}",
                            entry.Key, entry.Size);
                    }
                    Console.WriteLine("Next Continuation Token: {0}", response.NextContinuationToken);
                    request.ContinuationToken = response.NextContinuationToken;
                } while (response.IsTruncated == true);
            }
            catch (AmazonS3Exception amazonS3Exception)
            {
                Console.WriteLine("An AmazonS3Exception was thrown. Exception: " + amazonS3Exception.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.ToString());
            }
        }
    }
}

Para uma amostra completa da .NET para objetos de listagem, consulte Listar chaves de objeto programaticamente.

Para obter informações sobre como criar e testar um exemplo funcional .NET, consulte Executar os exemplos de código do Amazon S3 .NET.

Usar endpoints de pilha dupla da API REST

Para obter informações sobre fazer solicitação para endpoints de pilha dupla usando a API REST, consulte Fazer solicitações para endpoints de pilha dupla usando a API REST.