Klien dan alur HTTP di SDK Azure untuk Java

Artikel
09/08/2023

Artikel ini menyediakan gambaran umum tentang penggunaan klien HTTP dan fungsionalitas alur dalam SDK Azure untuk Java. Fungsi ini menyediakan pengalaman yang konsisten, kuat, dan fleksibel bagi pengembang yang menggunakan semua pustaka SDK Azure untuk Java.

Klien HTTP

SDK Azure untuk Java diimplementasikan menggunakan abstraksi HttpClient. Abstraksi ini mengaktifkan arsitektur yang bisa dipasang yang menerima beberapa pustaka klien HTTP atau implementasi kustom. Namun, untuk menyederhanakan manajemen dependensi bagi sebagian besar pengguna, semua pustaka klien Azure bergantung pada azure-core-http-netty. Dengan demikian, klien HTTP Netty adalah klien default yang digunakan di semua pustaka SDK Azure untuk Java.

Meskipun Netty adalah klien HTTP default, SDK menyediakan tiga implementasi klien, tergantung pada dependensi mana yang sudah Anda miliki dalam proyek Anda. Implementasi ini adalah untuk:

Netty
OkHttp
HttpClient diperkenalkan di JDK 11

Catatan

JDK HttpClient dalam kombinasi dengan Azure SDK untuk Java hanya didukung dengan JDK 12 dan yang lebih tinggi.

Mengganti klien HTTP default

Jika Anda lebih suka implementasi lainnya, Anda dapat menghapus dependensi pada Netty dengan mengecualikannya dalam file konfigurasi build. Dalam file pom.xml Maven, Anda mengecualikan dependensi Netty dan memasukkan dependensi lain.

Contoh berikut menunjukkan kepada Anda cara untuk mengecualikan dependensi Netty dari dependensi nyata pada pustaka azure-security-keyvault-secrets. Pastikan untuk mengecualikan Netty dari semua pustaka com.azure yang sesuai, seperti yang ditunjukkan di sini:

<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>

Catatan

Jika Anda menghapus dependensi Netty tetapi tidak memberikan implementasi di tempatnya, aplikasi gagal dimulai. Implementasi HttpClient harus ada di classpath.

Mengonfigurasikan klien HTTP

Saat Anda membangun klien layanan, secara default menggunakan HttpClient.createDefault(). Metode ini mengembalikan instans HttpClient dasar berdasarkan implementasi klien HTTP yang disediakan. Jika Anda memerlukan klien HTTP yang lebih kompleks, seperti proksi, setiap implementasi menawarkan seorang pembangun yang memungkinkan Anda membuat instans HttpClient yang dikonfigurasikan. Pembangunnya adalah NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuilder, dan JdkAsyncHttpClientBuilder.

Contoh berikut menunjukkan cara membangun instans HttpClient menggunakan Netty, OkHttp, dan klien HTTP JDK 11. Instans ini melakukan proksi melalui http://localhost:3128 dan melakukan autentikasi dengan contoh pengguna dengan kata sandi 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();

Anda sekarang dapat meneruskan bangunan instans HttpClient ke pembangun klien layanan untuk digunakan sebagai klien selama berkomunikasi dengan layanan. Contoh berikut menggunakan instans HttpClient baru untuk membangun klien Azure Storage Blob.

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

Untuk pustaka manajemen, Anda dapat mengatur HttpClient selama konfigurasi Manajer.

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

Alur HTTP

Alur HTTP adalah salah satu komponen kunci dalam mencapai konsistensi dan kemampuan diagnosis di pustaka klien Java untuk Azure. Alur HTTP terdiri dari:

Transportasi HTTP
Kebijakan alur HTTP

Anda dapat menyediakan alur HTTP kustom Anda sendiri ketika membuat klien. Jika Anda tidak menyediakan alur, pustaka klien membuat yang dikonfigurasi untuk bekerja dengan pustaka klien tertentu.

Transportasi HTTP

Transportasi HTTP bertanggung jawab untuk membangun sambungan ke server, dan mengirim serta menerima pesan HTTP. Transportasi HTTP membentuk gateway untuk pustaka klien SDK Azure agar dapat berinteraksi dengan layanan Azure. Seperti yang dicatat sebelumnya dalam artikel ini, SDK Azure untuk Java menggunakan Netty secara default untuk transportasi HTTP-nya. Namun, SDK juga menyediakan transportasi HTTP yang dapat dipasang, sehingga Anda dapat menggunakan implementasi lain, jika memungkinkan. SDK juga menyediakan dua implementasi transportasi HTTP lagi untuk OkHttp dan klien HTTP yang dikirimkan dengan JDK 11 dan setelahnya.

Kebijakan alur HTTP

Alur terdiri dari urutan langkah yang dijalankan untuk setiap roundtrip permintaan-respons HTTP. Setiap kebijakan memiliki tujuan khusus dan bertindak berdasarkan permintaan atau respons atau terkadang keduanya. Karena semua pustaka klien memiliki lapisan 'Azure Core' standar, lapisan ini memastikan bahwa setiap kebijakan dijalankan secara berurutan dalam alur. Ketika Anda mengirim permintaan, kebijakan akan dijalankan dalam urutan ketika mereka ditambahkan ke alur. Ketika Anda menerima respons dari layanan, kebijakan akan dijalankan dalam urutan terbalik. Semua kebijakan ditambahkan ke eksekusi alur sebelum Anda mengirim permintaan dan setelah Anda menerima respons. Kebijakan harus memutuskan apakah akan bertindak atas permintaan, tanggapan, atau keduanya. Misalnya, kebijakan pengelogan mencatat permintaan dan respons tetapi kebijakan autentikasi hanya tertarik untuk memodifikasi permintaan.

Kerangka kerja Azure Core menyediakan kebijakan dengan data permintaan dan respons yang diperlukan bersama dengan konteks yang diperlukan untuk menjalankan kebijakan. Kebijakan ini kemudian dapat melakukan operasinya dengan data yang diberikan dan meneruskan kontrol bersamaan ke kebijakan berikutnya dalam alur.

HTTP pipeline diagram

Posisi kebijakan alur HTTP

Ketika Anda membuat permintaan HTTP ke layanan cloud, penting untuk menangani kegagalan sementara dan mencoba kembali upaya yang gagal. Karena fungsionalitas ini adalah persyaratan umum, Azure Core menyediakan kebijakan percobaan kembali yang dapat mengawasi kegagalan sementara dan secara otomatis mencoba kembali permintaannya.

Kebijakan percobaan kembali ini, oleh karena itu, membagi seluruh alur menjadi dua bagian: kebijakan yang dijalankan sebelum kebijakan percobaan kembali dan kebijakan yang dijalankan setelah kebijakan percobaan kembali. Kebijakan ditambahkan sebelum kebijakan percobaan kembali dijalankan hanya sekali per operasi API, dan kebijakan ditambahkan setelah kebijakan percobaan kembali dijalankan sebanyak percobaan kembalinya.

Jadi, ketika membangun alur HTTP, Anda harus memahami apakah akan menjalankan kebijakan untuk setiap permintaan percobaan kembali atau sekali per operasi API.

Kebijakan alur HTTP umum

Alur HTTP untuk layanan berbasis REST memiliki konfigurasi dengan kebijakan untuk autentikasi, percobaan kembali, pengelogan, telemetri, dan penentuan ID permintaan di header. Azure Core telah dimuat sebelumnya dengan kebijakan HTTP yang umum diperlukan ini yang dapat Anda tambahkan ke alur.

Kebijakan	Tautan GitHub
kebijakan coba lagi	RetryPolicy.java
kebijakan autentikasi	BearerTokenAuthenticationPolicy.java
kebijakan pengelogan	HttpLoggingPolicy.java
kebijakan ID permintaan	RequestIdPolicy.java
kebijakan telemetri	UserAgentPolicy.java

Kebijakan alur HTTP kustom

Kebijakan alur HTTP menyediakan mekanisme yang mudah untuk memodifikasi atau mendekorasi permintaan dan respons. Anda dapat menambahkan kebijakan kustom ke alur yang dibuat oleh pengguna atau pengembang pustaka klien. Ketika menambahkan kebijakan ke alur, Anda dapat menentukan apakah kebijakan ini harus dijalankan per panggilan atau per percobaan kembali.

Untuk membuat kebijakan alur HTTP kustom, Anda cukup memperpanjang jenis kebijakan dasar dan mengimplementasikan beberapa metode abstrak. Anda kemudian dapat memasangkan kebijakan ke dalam alur.

Header kustom dalam permintaan HTTP

Pustaka klien Azure SDK for Java menyediakan cara yang konsisten untuk menentukan header yang disesuaikan melalui Context objek di API publik, seperti yang ditunjukkan dalam contoh berikut:

// 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.

Untuk informasi selengkapnya, lihat Kelas AddHeadersFromContextPolicy.

Pustaka TLS/SSL default

Semua pustaka klien, secara default, menggunakan pustaka SSL Membosankan asli Tomcat untuk mengaktifkan performa tingkat asli untuk operasi TLS/SSL. Pustaka Boring SSL adalah JAR uber yang berisi pustaka asli untuk Linux, macOS, dan Windows, dan memberikan performa yang lebih baik dibandingkan dengan implementasi TLS/SSL default dalam JDK.

Kurangi ukuran dependensi Tomcat-Native TLS/SSL

Secara default, JAR uber pustaka Tomcat-Native Boring SSL digunakan di Azure SDK untuk Java. Untuk mengurangi ukuran dependensi ini, Anda perlu menyertakan dependensi dengan pengklasifikasi os sesuai netty-tcnative, seperti yang ditunjukkan dalam contoh berikut:

<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>

Menggunakan JDK TLS/SSL

Jika Anda lebih suka menggunakan JDK TLS/SSL default alih-alih Tomcat-Native Boring SSL, maka Anda perlu mengecualikan pustaka SSL Membosankan asli Tomcat. Ketahuilah bahwa, berdasarkan pengujian kami, performa JDK TLS/SSL 30% lebih lambat dibandingkan dengan Tomcat-Native Boring SSL. Saat Anda menggunakan com.azure:azure-core:1.28.0 atau lebih baru, HttpClientpustaka -implementing (seperti com.azure:azure-core-http-netty) mengelola dependensi pada Tomcat-Native Boring SSL. Untuk mengecualikan dependensi, tambahkan konfigurasi berikut ke file POM Anda:

<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>

Langkah berikutnya

Sekarang setelah Anda terbiasa dengan fungsionalitas klien HTTP di Azure SDK untuk Java, pelajari cara menyesuaikan klien HTTP yang Anda gunakan lebih lanjut. Untuk informasi selengkapnya, lihat Mengonfigurasi proksi di Azure SDK untuk Java.