適用於 Java 的 Azure SDK 中的 HTTP 用戶端和管線

發行項
12/13/2023

本文提供在 Azure SDK for Java 中使用 HTTP 用戶端和管線功能的概觀。這項功能可為開發人員提供一致、強大且彈性的體驗，使用所有適用於Java的 Azure SDK 連結庫。

HTTP 用戶端

適用於 Java 的 Azure SDK 是使用 HttpClient 抽象概念來實作。此抽象概念可讓插入式架構接受多個 HTTP 用戶端連結庫或自定義實作。不過，為了簡化大部分使用者的相依性管理，所有 Azure 用戶端連結庫都相依於 azure-core-http-netty。因此， Netty HTTP 用戶端是所有適用於 Java 的 Azure SDK 連結庫中使用的預設用戶端。

雖然 Netty 是預設 HTTP 用戶端，但 SDK 提供三個用戶端實作，視您在專案中已有的相依性而定。這些實作適用於：

注意

JDK HttpClient 與適用於 Java 的 Azure SDK 結合，僅支援 JDK 12 和更新版本。

取代預設 HTTP 用戶端

如果您想要另一個實作，您可以在組建組態檔中排除它，以移除 Netty 的相依性。在 Maven pom.xml 檔案中，您會排除 Netty 相依性並包含另一個相依性。

下列範例示範如何從連結庫的實際相依性中排除Netty相 azure-security-keyvault-secrets 依性。請務必從所有適當的 com.azure 連結庫排除 Netty，如下所示：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-security-keyvault-secrets</artifactId>
    <version>4.2.2.</version>
    <exclusions>
      <exclusion>
        <groupId>com.azure</groupId>
        <artifactId>azure-core-http-netty</artifactId>
      </exclusion>
    </exclusions>
</dependency>

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-http-okhttp</artifactId>
  <version>1.3.3</version>
</dependency>

注意

如果您移除 Netty 相依性，但未在其位置提供任何實作，則應用程式無法啟動。實 HttpClient 作必須存在於 classpath 上。

設定 HTTP 用戶端

當您建置服務用戶端時，預設會使用 HttpClient.createDefault()。此方法會根據提供的 HTTP 用戶端實作傳回基本 HttpClient 實例。如果您需要更複雜的 HTTP 用戶端，例如 Proxy，每個實作都會提供一個建置器，可讓您建構已設定 HttpClient 的實例。建置者為 NettyAsyncHttpClientBuilder、 OkHttpAsyncHttpClientBuilder和 JdkAsyncHttpClientBuilder。

下列範例示範如何使用 Netty、OkHttp 和 JDK 11 HTTP 用戶端來建 HttpClient 置實例。這些實例會透過 http://localhost:3128 Proxy，並使用密碼 weakPassword 向使用者範例進行驗證。

// Netty
HttpClient httpClient = new NettyAsyncHttpClientBuilder()
    .proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
        .setCredentials("example", "weakPassword"))
    .build();

// OkHttp
HttpClient httpClient = new OkHttpAsyncHttpClientBuilder()
    .proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
        .setCredentials("example", "weakPassword"))
    .build();

// JDK 11 HttpClient
HttpClient client = new JdkAsyncHttpClientBuilder()
    .proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
        .setCredentials("example", "weakPassword"))
    .build();

您現在可以將建構的 HttpClient 實例傳遞至服務客戶端產生器，以做為與服務通訊的用戶端。下列範例會使用新的 HttpClient 實例來建置 Azure 儲存體 Blob 用戶端。

BlobClient blobClient = new BlobClientBuilder()
    .connectionString(<connection string>)
    .containerName("container")
    .blobName("blob")
    .httpClient(httpClient)
    .build();

針對管理連結庫，您可以在管理員設定期間設定 HttpClient 。

AzureResourceManager azureResourceManager = AzureResourceManager.configure()
    .withHttpClient(httpClient)
    .authenticate(credential, profile)
    .withDefaultSubscription();

HTTP 管線

HTTP 管線是達成 Azure Java 用戶端連結庫中一致性和可診斷性的重要元件之一。 HTTP 管線是由下列專案所組成：

HTTP 傳輸
HTTP 管線原則

您可以在建立用戶端時提供自己的自訂 HTTP 管線。如果您沒有提供管線，用戶端連結庫會建立一個設定為使用該特定客戶端連結庫的。

HTTP 傳輸

HTTP 傳輸負責建立與伺服器的連線，以及傳送和接收 HTTP 訊息。 HTTP 傳輸會形成 Azure SDK 用戶端連結庫的閘道，以與 Azure 服務互動。如本文稍早所述，Azure SDK for Java 預設會使用 Netty 進行 HTTP 傳輸。不過，SDK 也提供插入式 HTTP 傳輸，因此您可以在適當的情況下使用其他實作。 SDK 也為 OkHttp 提供兩個 HTTP 傳輸實作，以及 JDK 11 和更新版本隨附的 HTTP 用戶端。

HTTP 管線原則

管線是由針對每個 HTTP 要求-回應往返執行的一連串步驟所組成。每個原則都有專用的用途，並針對要求或回應或有時兩者都採取動作。由於所有客戶端連結庫都有標準『Azure Core』層，因此此層可確保每個原則在管線中依序執行。當您傳送要求時，原則會依新增至管線的順序執行。當您收到來自服務的回應時，原則會以反向順序執行。所有新增至管線的原則都會在您傳送要求之前和收到響應之後執行。原則必須決定是否要根據要求、回應或兩者採取行動。例如，記錄原則會記錄要求和回應，但驗證原則只對修改要求感興趣。

Azure Core 架構會提供原則所需的要求和響應數據，以及執行原則的任何必要內容。然後，原則可以使用指定的數據執行其作業，並將控件傳遞至管線中的下一個原則。

HTTP pipeline diagram

HTTP 管線原則位置

當您對雲端服務提出 HTTP 要求時，請務必處理暫時性失敗，並重試失敗的嘗試。由於這項功能是常見的需求，Azure Core 會提供重試原則，可監看暫時性失敗，並自動重試要求。

因此，此重試原則會將整個管線分割成兩個部分：重試原則之前執行的原則，以及重試原則之後執行的原則。在重試原則之前新增的原則只會針對每個 API 作業執行一次，並在重試原則之後新增的原則執行次數為重試次數。

因此，建置 HTTP 管線時，您應該瞭解要針對每個要求重試或每個 API 作業執行一次原則。

常見的 HTTP 管線原則

REST 型服務的 HTTP 管線具有驗證、重試、記錄、遙測，以及在標頭中指定要求標識碼的原則設定。 Azure Core 已預先載入這些常見的 HTTP 原則，您可以新增至管線。

原則	GitHub 連結
重試原則	RetryPolicy.java
驗證原則	BearerTokenAuthenticationPolicy.java
記錄原則	HttpLoggingPolicy.java
要求標識符原則	RequestIdPolicy.java
遙測原則	UserAgentPolicy.java

自定義 HTTP 管線原則

HTTP 管線原則提供方便的機制來修改或裝飾要求和回應。您可以將自定義原則新增至使用者或用戶端連結庫開發人員所建立的管線。將原則新增至管線時，您可以指定此原則是否應依呼叫或每次重試執行。

若要建立自定義 HTTP 管線原則，您只需擴充基底原則類型並實作一些抽象方法。然後，您可以將原則插入管線。

HTTP 要求中的自定義標頭

適用於 Java 的 Azure SDK 用戶端連結庫提供一致的方式，透過 Context 公用 API 中的物件定義自定義標頭，如下列範例所示：

// Add your headers
HttpHeaders headers = new HttpHeaders();
headers.set("my-header1", "my-header1-value");
headers.set("my-header2", "my-header2-value");
headers.set("my-header3", "my-header3-value");

// Call API by passing headers in Context.
configurationClient.addConfigurationSettingWithResponse(
    new ConfigurationSetting().setKey("key").setValue("value"),
    new Context(AddHeadersFromContextPolicy.AZURE_REQUEST_HTTP_HEADERS_KEY, headers));

// The three headers are now be added to the outgoing HTTP request.

如需詳細資訊，請參閱 AddHeadersFromContextPolicy 類別。

預設 TLS/SSL 連結庫

根據預設，所有用戶端連結庫都會使用 Tomcat 原生 Boring SSL 連結庫來啟用 TLS/SSL 作業的原生層級效能。 Boring SSL 連結庫是一個 Uber JAR，其中包含 Linux、macOS 和 Windows 的原生連結庫，相較於 JDK 內的預設 TLS/SSL 實作，可提供更佳的效能。

減少 Tomcat-Native TLS/SSL 相依性大小

根據預設，Tomcat-Native Boring SSL 連結庫的uber JAR 會用於適用於Java的 Azure SDK。若要減少此相依性的大小，您必須依 netty-tcnative 將相依性與os分類器包含，如下列範例所示：

<project>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-tcnative-boringssl-static</artifactId>
      <version>2.0.25.Final</version>
      <classifier>${os.detected.classifier}</classifier>
    </dependency>
    ...
  </dependencies>
  ...
  <build>
    ...
    <extensions>
      <extension>
        <groupId>kr.motd.maven</groupId>
        <artifactId>os-maven-plugin</artifactId>
        <version>1.4.0.Final</version>
      </extension>
    </extensions>
    ...
  </build>
  ...
</project>

使用 JDK TLS/SSL

如果您想要使用預設的 JDK TLS/SSL，而不是 Tomcat-Native Boring SSL，則必須排除 Tomcat 原生 Boring SSL 連結庫。請注意，根據我們的測試，JDK TLS/SSL 的效能比 Tomcat-Native Boring SSL 慢 30%。當您使用 com.azure:azure-core:1.28.0 或更新版本時， HttpClient實作連結庫（例如 com.azure:azure-core-http-netty）會管理 Tomcat-Native Boring SSL 的相依性。若要排除相依性，請將下列組態新增至您的 POM 檔案：

<project>
  ...
  <dependencies>
    ...
    <dependency>
     <groupId>com.azure</groupId>
       <artifactId>azure-core-http-netty</artifactId>
       <version>1.13.6</version>
       <exclusions>
         <exclusion>
           <groupId>io.netty</groupId>
           <artifactId>netty-tcnative-boringssl-static</artifactId>
         </exclusion>
       </exclusions>
    </dependency>
    ...
  </dependencies>
  ...
</project>

下一步

現在您已熟悉適用於 Java 的 Azure SDK 中的 HTTP 用戶端功能，接下來請瞭解如何進一步自定義您使用的 HTTP 用戶端。如需詳細資訊，請參閱在 Azure SDK for Java 中設定 Proxy。

共用方式為