在適用於 Java 的 Azure SDK 中設定 Proxy

2025-06-17

本文提供如何設定 Azure SDK for Java 以適當使用 Proxy 的概觀。

HTTP Proxy 組態

適用於 Java 的 Azure 用戶端函式庫提供多種方式來為 HttpClient 設定 Proxy。

每個提供 Proxy 的方法都有自己的優缺點，並提供不同層級的封裝。當您為 HttpClient設定代理伺服器時，它會在其生命周期內使用該代理伺服器。將 Proxy 系結至個別 HttpClient 可讓應用程式使用多個 HttpClient 實例，其中每個實例都可以使用不同的 Proxy 來滿足應用程式的 Proxy 需求。

Proxy 組態選項如下：

使用環境代理
使用組態代理
使用明確的 Proxy

使用環境代理

根據預設，HTTP 用戶端產生器會檢查環境是否有 Proxy 設定。此程式會使用適用於 Java Configuration 的 Azure SDK API。當建立器建立用戶端時，它會使用藉由呼叫 Configuration.getGlobalConfiguration()所擷取的「全域組態」複本進行設定。此呼叫會在系統環境的任何 HTTP Proxy 設定中讀取。

當建置者檢查環境時，它會依指定的順序搜尋下列環境組態：

HTTPS_PROXY
HTTP_PROXY
https.proxy*
http.proxy*

*表示已知的 Java Proxy 屬性。如需詳細資訊，請參閱 Oracle 檔中的 Java 網路和 Proxy 。

如果建置者找到任何環境組態，它會藉由呼叫 ProxyOptions來建立 ProxyOptions.fromConfiguration(Configuration.getGlobalConfiguration()) 實例。本文在下方提供更多關於 ProxyOptions 類型的詳細資訊。

這很重要

若要使用任何 Proxy 設定，Java 會要求您將系統環境屬性 java.net.useSystemProxies 設定為 true。

您也可以建立 HTTP 用戶端實例，而該實例不會使用系統環境變數中的任何 Proxy 組態。若要覆寫預設行為，您會在 HTTP 用戶端產生器中明確設定不同的 Configuration 設定。當您在產生器中設定 Configuration 時，它將不再呼叫 Configuration.getGlobalConfiguration()。例如，如果您使用configuration(Configuration)呼叫Configuration.NONE，則可以明確地防止構建器檢查環境中的組態設定。

下列範例使用 HTTP_PROXY 具有值的 localhost:8888 環境變數，以使用 Fiddler 作為 Proxy。此程式代碼示範如何建立 Netty 和 OkHttp HTTP 用戶端。（如需 HTTP 用戶端設定的詳細資訊，請參閱 HTTP 用戶端和管線。

export HTTP_PROXY=localhost:8888

HttpClient nettyHttpClient = new NettyAsyncHttpClientBuilder().build();
HttpClient okhttpHttpClient = new OkHttpAsyncHttpClientBuilder().build();

若要防止使用環境 Proxy，請將 HTTP 客戶端建構器配置為 Configuration.NONE，如下列範例所示：

HttpClient nettyHttpClient = new NettyAsyncHttpClientBuilder()
    .configuration(Configuration.NONE)
    .build();

HttpClient okhttpHttpClient = new OkHttpAsyncHttpClientBuilder()
    .configuration(Configuration.NONE)
    .build();

使用組態代理伺服器

您可以設定 HTTP 用戶端產生器，以使用已接受自環境的相同 Proxy 設定的自定義 Configuration ，而不是從環境讀取。此組態提供可重複使用的設定，其範圍限定為有限的使用案例。當 HTTP 用戶端產生器建置 HttpClient時，它會使用從 ProxyOptions 傳回的 ProxyOptions.fromConfiguration(<Configuration passed into the builder>)。

下列範例會使用http.proxy*Configuration物件中設定的組態，以設置驗證 Fiddler 為代理伺服器的代理。

Configuration configuration = new Configuration()
    .put("java.net.useSystemProxies", "true")
    .put("http.proxyHost", "localhost")
    .put("http.proxyPort", "8888")
    .put("http.proxyUser", "1")
    .put("http.proxyPassword", "1");

HttpClient nettyHttpClient = new NettyAsyncHttpClientBuilder()
    .configuration(configuration)
    .build();

HttpClient okhttpHttpClient = new OkHttpAsyncHttpClientBuilder()
    .configuration(configuration)
    .build();

使用顯式代理伺服器

Java 用戶端連結庫隨附類別 ProxyOptions ，做為設定 Proxy 的 Azure 用戶端連結庫類型。您可以使用 ProxyOptions 用來傳送 Proxy 要求、Proxy 位址、Proxy 驗證認證和非 Proxy 主機的網路通訊協議進行設定。只需要 Proxy 網路協定和 Proxy 位址。使用驗證認證時，您必須同時設定使用者名稱和密碼。

下列範例建立一個簡單的 ProxyOptions 實例，用來將請求代理到預設 Fiddler 位址（localhost:8888）：

ProxyOptions proxyOptions = new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 8888));

下列範例會建立一個經過認證的 ProxyOptions，用來代理將請求轉發至需要代理驗證的 Fiddler 示例：

// Fiddler uses username "1" and password "1" with basic authentication as its proxy authentication requirement.
ProxyOptions proxyOptions = new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 8888))
    .setCredentials("1", "1");

您可以直接使用 ProxyOptions 設定 HTTP 用戶端產生器，以指定要使用的明確代理伺服器。此配置是設置代理伺服器的最詳盡方法，但通常不如可變的 Configuration 在更新代理需求時來得靈活。

下列範例使用 ProxyOptions 將 Fiddler 作為代理伺服器：

ProxyOptions proxyOptions = new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 8888));

HttpClient nettyHttpClient = new NettyAsyncHttpClientBuilder()
    .proxy(proxyOptions)
    .build();

HttpClient okhttpHttpClient = new OkHttpAsyncHttpClientBuilder()
    .proxy(proxyOptions)
    .build();

後續步驟

現在您已熟悉適用於 Java 的 Azure SDK 中的 Proxy 設定，請參閱在適用於 Java 的 Azure SDK 中設定追蹤，以進一步瞭解應用程式內的流程，以及協助診斷問題。

共用方式為