在 Azure SDK for Java 中配置代理

项目
05/30/2023

本文概述如何配置 Azure SDK for Java 以正确使用代理。

HTTP 代理配置

适用于 Java 的 Azure 客户端库提供多种方式来为 HttpClient 配置代理。

提供代理的每种方法都有其各自的优点和缺点，并提供不同的封装级别。为 HttpClient 配置代理后，它将在其剩余的生存期内使用该代理。将代理绑定到单独的 HttpClient 允许应用程序使用多个 HttpClient 实例，其中每个实例均可使用不同的代理来满足应用程序的代理要求。

代理配置选项包括：

使用环境代理
使用配置代理
使用显式代理

使用环境代理

默认情况下，HTTP 客户端生成器将检查代理配置的环境。此过程使用 Azure SDK for Java Configuration API。当生成器创建客户端时，会使用通过调用 Configuration.getGlobalConfiguration() 检索到的“全局配置”副本来配置该客户端。此调用将从系统环境中读取任何 HTTP 代理配置。

当生成器检查环境时，它将按指定的顺序搜索下列环境配置：

HTTPS_PROXY
HTTP_PROXY
https.proxy*
http.proxy*

* 表示熟知的 Java 代理属性。有关详细信息，请参阅 Oracle 文档中的 Java Networking and Proxies（Java 网络和代理）。

如果生成器发现任何环境配置，则通过调用 ProxyOptions.fromConfiguration(Configuration.getGlobalConfiguration()) 创建 ProxyOptions 实例。本文在下面提供了有关 ProxyOptions 类型的更多详细信息。

重要

若要使用任何代理配置，Java 要求你将系统环境属性 java.net.useSystemProxies 设置为 true。

你还可以创建不使用系统环境变量中存在的任何代理配置的 HTTP 客户端实例。若要替代默认行为，请在 HTTP 客户端生成器中显式设置配置不同的 Configuration。在生成器中设置 Configuration 时，它将不再调用 Configuration.getGlobalConfiguration()。例如，如果使用 Configuration.NONE 调用 configuration(Configuration)，则可以显式阻止生成器检查配置环境。

以下示例使用值为 localhost:8888 的 HTTP_PROXY 环境变量来使用 Fiddler 作为代理。此代码演示如何创建 Netty 和 OkHttp HTTP 客户端。（有关 HTTP 客户端配置的详细信息，请参阅 HTTP 客户端和管道。）

export HTTP_PROXY=localhost:8888

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

若要防止使用环境代理，请使用 Configuration.NONE 配置 HTTP 客户端生成器，如以下示例中所示：

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

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

使用配置代理

可以将 HTTP 客户端生成器配置为使用自定义 Configuration（具有与已从环境中接受的代理设置相同的代理设置），而不是从环境中读取。此配置提供具有可重用配置的能力，这些配置适用于受限的用例。当 HTTP 客户端生成器生成 HttpClient 时，它将使用从 ProxyOptions.fromConfiguration(<Configuration passed into the builder>) 返回的 ProxyOptions。

以下示例使用 Configuration 对象中设置的 http.proxy* 配置，将对 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 类，该类充当配置代理的 Azure 客户端库类型。你可以使用用于发送代理请求的网络协议、代理地址、代理身份验证凭据和非代理主机来配置 ProxyOptions。只有代理网络协议和代理地址是必填项。使用身份验证凭据时，必须同时设置用户名和密码。

以下示例创建一个简单的 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();

后续步骤

现在你已熟悉 Azure SDK for Java 中的代理配置，请参阅在 Azure SDK for Java 中配置跟踪，更好地了解应用程序中的流并帮助诊断问题。

通过