View a markdown version of this page

設定 HTTP 代理 - AWS SDK for Java 2.x
在程式碼中設定使用外部設定設定 HTTP 代理使用設定的組合nonProxyHosts 萬用字元行為

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

設定 HTTP 代理

您可以使用程式碼、設定 Java 系統屬性或設定環境變數來設定 HTTP 代理。

在程式碼中設定

您可以在建置服務用戶端時，使用用戶端特定的ProxyConfiguration建置器在程式碼中設定代理。下列程式碼顯示 Amazon S3 服務用戶端所使用的 Apache 型 HTTP 用戶端代理組態範例。

SdkHttpClient httpClient1 = ApacheHttpClient.builder()
    .proxyConfiguration(ProxyConfiguration.builder()
        .endpoint(URI.create("http://proxy.example.com"))
        .username("username")
        .password("password")
        .addNonProxyHost("localhost")
        .build())
    .build();

S3Client s3Client = S3Client.builder()
    .httpClient(httpClient)
    .build();

本主題中每個 HTTP 用戶端的 區段會顯示代理組態範例。

使用外部設定設定 HTTP 代理

即使您未在程式碼中明確使用ProxyConfiguration建置器，軟體開發套件仍會尋找外部設定來設定預設代理組態。

根據預設，軟體開發套件會先搜尋 JVM 系統屬性。如果找到一個屬性，開發套件會使用 值和任何其他系統屬性值。如果沒有可用的系統屬性，軟體開發套件會尋找代理環境變數。

SDK 可以使用下列 Java 系統屬性和環境變數。

Java 系統屬性
系統屬性 說明 HTTP 用戶端支援

http.proxyHost

HTTP 代理伺服器的主機名稱

全部

http.proxyPort

HTTP 代理伺服器的連接埠號碼

全部
http.proxyUser

HTTP 代理身分驗證的使用者名稱

全部

http.proxyPassword

 HTTP 代理身分驗證的密碼

全部
http.nonProxyHosts

應直接到達的主機清單，繞過代理。使用 HTTPS 時，此清單也有效。

全部
https.proxyHost

HTTPS 代理伺服器的主機名稱

Netty、CRT

https.proxyPort

HTTPS 代理伺服器的連接埠號碼

Netty、CRT
https.proxyUser

HTTPS 代理身分驗證的使用者名稱

 Netty、CRT
https.proxyPassword HTTPS 代理身分驗證的密碼 Netty、CRT
環境變數
環境變數 說明 HTTP 用戶端支援
HTTP_PROXY1

具有 HTTP 結構描述的有效 URL

全部

HTTPS_PROXY1

具有 HTTPS 結構描述的有效 URL

Netty、CRT
NO_PROXY2

應直接到達的主機清單，繞過代理。此清單對 HTTP 和 HTTPS 都有效。

全部

全部 - 開發套件提供的所有 HTTP 用戶端 –UrlConnectionHttpClient、ApacheHttpClient、NettyNioAsyncHttpClient、AwsCrtAsyncHttpClient。

Netty - Netty 型 HTTP 用戶端 (NettyNioAsyncHttpClient)。

CRT - AWS CRT 型 HTTP 用戶端 (AwsCrtHttpClient 和 AwsCrtAsyncHttpClient)。

1查詢的環境變數，無論是 HTTP_PROXY還是 HTTPS_PROXY，取決於用戶端 中的配置設定ProxyConfiguration。預設方案為 HTTP。下列程式碼片段說明如何將配置變更為用於環境變數解析的 HTTPS。

SdkHttpClient httpClient = ApacheHttpClient.builder()
    .proxyConfiguration(ProxyConfiguration.builder()
        .scheme("https")
        .build())
    .build();

2 NO_PROXY環境變數支援主機名稱之間的混合 "|" 和 "，" 分隔符號。如需支援的萬用字元格式，請參閱 nonProxyHosts 萬用字元行為。

使用設定的組合

您可以在程式碼、系統屬性和環境變數中使用 HTTP 代理設定的組合。

範例– 系統屬性和程式碼提供的組態
// Command line with the proxy password set as a system property.
$ java -Dhttp.proxyPassword=SYS_PROP_password -cp ... App

// Since the 'useSystemPropertyValues' setting is 'true' (the default), the SDK will supplement 
// the proxy configuration in code with the 'http.proxyPassword' value from the system property.
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
            .proxyConfiguration(ProxyConfiguration.builder()
                    .endpoint(URI.create("http://localhost:1234"))
                    .username("username")
                    .build())
            .build();

// Use the apache HTTP client with proxy configuration.
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
                    .httpClient(apacheHttpClient)
                    .build();

SDK 會解析下列代理設定。

Host = localhost
Port = 1234
Password = SYS_PROP_password
UserName = username
Non ProxyHost = null
範例– 同時提供系統屬性和環境變數

每個 HTTP 用戶端的ProxyConfiguration建置器都提供名為 useSystemPropertyValues和 的設定useEnvironmentVariablesValues。根據預設，這兩個設定都是 true。當 時true，軟體開發套件會自動將系統屬性或環境變數中的值用於ProxyConfiguration建置器未提供的選項。

重要

系統屬性優先於環境變數。如果找到 HTTP 代理系統屬性，軟體開發套件會從系統屬性擷取所有值，而從環境變數擷取所有值。如果您想要將環境變數優先於系統屬性，請將 useSystemPropertyValues設定為 false。

在此範例中，下列設定可供執行時間使用：

// System properties 
http.proxyHost=SYS_PROP_HOST.com
http.proxyPort=2222
http.password=SYS_PROP_PASSWORD
http.user=SYS_PROP_USER

// Environment variables 
HTTP_PROXY="http://EnvironmentUser:EnvironmentPassword@ENV_VAR_HOST:3333"
NO_PROXY="environmentnonproxy.host,environmentnonproxy2.host:1234"

使用下列其中一個陳述式建立服務用戶端。沒有任何陳述式會明確設定代理設定。

DynamoDbClient client = DynamoDbClient.create();
DynamoDbClient client = DynamoDbClient.builder().build();
DynamoDbClient client = DynamoDbClient.builder()
    .httpClient(ApacheHttpClient.builder()
        .proxyConfiguration(ProxyConfiguration.builder()
            .build())
        .build())
    .build();

開發套件會解析下列代理設定：

Host = SYS_PROP_HOST.com
Port = 2222
Password = SYS_PROP_PASSWORD
UserName = SYS_PROP_USER
Non ProxyHost = null

由於服務用戶端具有預設代理設定，因此 SDK 會搜尋系統屬性，然後搜尋環境變數。由於系統屬性設定優先於環境變數，因此 SDK 只會使用系統屬性。

如果系統屬性的使用變更為 false，如下列程式碼所示，開發套件只會解析環境變數。

DynamoDbClient client = DynamoDbClient.builder()
    .httpClient(ApacheHttpClient.builder()
        .proxyConfiguration(ProxyConfiguration.builder()
            .useSystemPropertyValues(Boolean.FALSE)
            .build())
        .build())
    .build();

使用 HTTP 解析的代理設定如下：

Host = ENV_VAR_HOST
Port = 3333
Password = EnvironmentPassword
UserName = EnvironmentUser
Non ProxyHost = environmentnonproxy.host, environmentnonproxy2.host:1234

nonProxyHosts 萬用字元行為

使用 nonProxyHosts，您可以指定略過代理的主機。透過ProxyConfiguration建置器、http.nonProxyHosts系統屬性或NO_PROXY環境變數設定此值。每個來源都支援下列項目格式。

  • 確切主機： example.com （僅符合指定的主機）

  • 前置萬用字元：*.example.com（符合網域和所有子網域）

  • 裸機萬用字元：*（略過所有主機）

  • CIDR 範圍：10.0.0.0/8（符合範圍內的所有 IP 地址）

HTTP 用戶端的行為差異

HTTP 用戶端類型和項目來源會影響兩個重要的比對行為。

相較於外部設定的建置器項目

當您透過ProxyConfiguration建置器上的 或 addNonProxyHost(String)方法提供萬用字元項目 (*.example.com nonProxyHosts(Set) 或 *) 時，萬用字元僅適用於 AWS 以 CRT 為基礎的 HTTP 用戶端 (AwsCrtHttpClient 和 AwsCrtAsyncHttpClient)。

Apache、 Netty和 URLConnection型用戶端PatternSyntaxException會為您透過建置器提供的萬用字元項目擲回 。

當項目來自http.nonProxyHosts系統屬性或NO_PROXY環境變數時，萬用字元適用於所有用戶端。

重要

如果您需要萬用字元才能跨所有 HTTP 用戶端運作，請使用http.nonProxyHosts系統屬性或NO_PROXY環境變數，而非建置器。

前置萬用字元項目的根網域比對

以 AWS CRT 為基礎的用戶端和其他 HTTP 用戶端會以不同的方式處理*.example.com模式：

  • 以 CRT 為基礎的用戶端： *.example.com 符合根網域 (example.com) 和子網域 （例如 api.example.com)。

  • Apache、 Netty和 URLConnection型用戶端： 僅*.example.com符合子網域。根網域example.com不相符，開發套件會透過代理路由它。

依項目來源的萬用字元行為摘要

下表摘要說明當您透過http.nonProxyHosts系統屬性或NO_PROXY環境變數提供項目時，相符的行為。所有用戶端都支援來自這些來源的萬用字元。

項目格式 非 CRT 用戶端 (Apache、 Netty和 URLConnection) 以 CRT 為基礎的用戶端

精確主機 (example.com)

榮譽

榮譽

前置萬用字元 (*.example.com)

榮譽 （僅限子網域）

榮譽 （根網域和子網域）

裸機萬用字元 (*)

榮譽

榮譽

CIDR 範圍 (10.0.0.0/8)

榮譽

榮譽