# 使用 Amazon S3 双堆栈端点
<a name="dual-stack-endpoints"></a>

Amazon S3 双堆栈端点支持通过 IPv6 和 IPv4 向 S3 存储桶发出请求。本节介绍如何使用双堆栈端点。

**Topics**
+ [Amazon S3 双堆栈端点](#dual-stack-endpoints-description)
+ [从 Amazon CLI 使用双堆栈端点](#dual-stack-endpoints-cli)
+ [从 Amazon SDK 使用双堆栈端点](#dual-stack-endpoints-sdks)
+ [从 REST API 使用双堆栈端点](#dual-stack-endpoints-examples-rest-api)

## Amazon S3 双堆栈端点
<a name="dual-stack-endpoints-description"></a>

当您向双堆栈端点发出请求时，存储桶 URL 解析为 IPv6 或 IPv4 地址。有关如何通过 IPv6 访问存储桶的更多信息，请参阅[通过 IPv6 向 Amazon S3 发出请求](ipv6-access.md)。

当使用 REST API 时，您通过使用端点名称（URI）直接访问 Amazon S3 端点。通过使用虚拟托管类型或路径类型端点名称，您可以通过双堆栈端点访问 S3 存储桶。Amazon S3 只支持区域双堆栈端点名称，这意味着，您必须在名称中指定区域。

双堆栈虚拟托管类型和路径类型端点名称使用以下命名惯例：
+ 虚拟托管型双堆栈端点：

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

   
+ 路径型双堆栈端点：

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

有关端点名称样式的更多信息，请参阅[访问和列出 Amazon S3 存储桶](https://docs.amazonaws.cn//AmazonS3/latest/userguide/access-bucket-intro.html)。有关 Amazon S3 端点的列表，请参阅《Amazon Web Services 一般参考》**中的[区域和端点](https://docs.amazonaws.cn/general/latest/gr/s3.html)。

**重要**  
您可对双堆栈端点使用传输加速。有关更多信息，请参阅[开始使用 Amazon S3 Transfer Acceleration](https://docs.amazonaws.cn//AmazonS3/latest/userguide/transfer-acceleration-getting-started.html)。

**注意**  
访问 Amazon S3 的两种类型的虚拟私有云（VPC）端点（*接口 VPC 端点*和*网关 VPC 端点*）现在支持双堆栈。有关 Amazon S3 的 VPC 端点的更多信息，请参阅[适用于 Amazon S3 的 Amazon PrivateLink](https://docs.amazonaws.cn//AmazonS3/latest/userguide/privatelink-interface-endpoints.html)。

如果使用 Amazon Command Line Interface（Amazon CLI）和 Amazon SDK，可使用参数或标志以更改为双堆栈端点。您还可以在配置文件中直接将双堆栈端点指定为覆盖 Amazon S3 端点。下面几节介绍如何从 Amazon CLI 和 Amazon SDK 使用双堆栈端点。

## 从 Amazon CLI 使用双堆栈端点
<a name="dual-stack-endpoints-cli"></a>

本节提供用于向双堆栈端点发出请求的 Amazon CLI 命令示例。有关设置 Amazon CLI 的说明，请参阅[使用 Amazon CLI 进行 Amazon S3 开发](setup-aws-cli.md)。

在 Amazon Config 文件中的配置文件中将配置值 `use_dualstack_endpoint` 设置为 `true`，使 `s3` 和 `s3api` Amazon CLI 命令发出的所有 Amazon S3 请求定向到指定区域的双堆栈端点。您可以在配置文件或命令中使用 `--region` 选项指定区域。

通过 Amazon CLI 使用双堆栈端点时，支持 `path` 和 `virtual` 寻址类型。配置文件中设置的寻址类型控制着主机名或 URL 中是否包含存储桶名称。默认情况下，CLI 尝试使用虚拟类型，但是如果需要，会改为使用路径类型。有关更多信息，请参阅 [Amazon CLI Amazon S3 配置](https://docs.amazonaws.cn/cli/latest/topic/s3-config.html)。

您也可以使用命令进行配置更改，如下例所示，在默认配置文件中将 `use_dualstack_endpoint` 设置为 `true`，将 `addressing_style` 设置为 `virtual`。

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

如果需要只对指定的 Amazon CLI 命令（并非所有命令）使用双堆栈端点，可以使用以下任一方法：
+ 您可以通过将任何 `--endpoint-url` 或 `https://s3.dualstack.{{aws-region}}.amazonaws.com` 命令的 `http://s3.dualstack.{{aws-region}}.amazonaws.com` 参数设置为 `s3` 或 `s3api` 来对每条命令使用双堆栈端点。

  ```
  $ aws s3api list-objects --bucket {{bucketname}} --endpoint-url https://s3.dualstack.{{aws-region}}.amazonaws.com
  ```
+ 您可以在 Amazon Config 文件中设置单独的配置文件。例如，创建一个将 `use_dualstack_endpoint` 设置为 `true` 的配置文件和一个不设置 `use_dualstack_endpoint` 的配置文件。在运行命令时，根据是否需要使用双堆栈端点来指定要使用的配置文件。

**注意**  
当使用 Amazon CLI 时，当前不能对双堆栈端点使用传输加速。但是，即将推出对 Amazon CLI 的支持。有关更多信息，请参阅[启用和使用 S3 Transfer Acceleration](https://docs.amazonaws.cn//AmazonS3/latest/userguide/transfer-acceleration.html#transfer-acceleration-requirements)。

## 从 Amazon SDK 使用双堆栈端点
<a name="dual-stack-endpoints-sdks"></a>

本节提供一些示例，介绍如何使用 Amazon SDK 来访问双堆栈端点。

### Amazon SDK for Java双堆栈端点示例
<a name="dual-stack-endpoints-examples-java"></a>

以下示例演示如何使用 Amazon SDK for Java 在创建 Amazon S3 客户端时启用双堆栈端点。

有关创建和测试有效 Java 示例的说明，请参阅《Amazon SDK for Java 开发人员指南》中的[入门](https://docs.amazonaws.cn/sdk-for-java/v1/developer-guide/getting-started.html)。

```
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();
        }
    }
}
```

如果要在 Windows 上使用Amazon SDK for Java，可能必须设置以下 Java 虚拟机 (JVM) 属性：

```
java.net.preferIPv6Addresses=true
```

### Amazon .NET SDK 双堆栈端点示例
<a name="dual-stack-endpoints-examples-dotnet"></a>

在使用 Amazon SDK for .NET 时，请使用 `AmazonS3Config` 类来启用双堆栈端点，如下例所示。

```
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());
            }
        }
    }
}
```

有关设置和运行代码示例的信息，请参阅《适用于 .NET 的 Amazon SDK 开发人员指南》**中的[适用于 .NET 的 Amazon SDK 入门](https://docs.amazonaws.cn/sdk-for-net/latest/developer-guide/net-dg-setup.html)。

## 从 REST API 使用双堆栈端点
<a name="dual-stack-endpoints-examples-rest-api"></a>

有关如何使用 REST API 向双堆栈端点发出请求的信息，请参阅[通过使用 REST API 向双堆栈终端节点发出请求](RESTAPI.md#rest-api-dual-stack)。