Klien http dan alur di Azure SDK untuk Java

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

Klien HTTP

Azure SDK untuk Java diimplementasikan menggunakan abstraksi HttpClient. Abstraksi ini memungkinkan arsitektur yang dapat dicolokkan 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 Azure SDK untuk pustaka 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

Ganti klien HTTP default

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

Contoh berikut menunjukkan kepada Anda cara mengecualikan dependensi Netty dari dependensi sebenarnya 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>

Konfigurasi klien HTTP

Saat Anda membangun klien layanan, defaultnya 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 penyusun yang memungkinkan Anda membuat instans HttpClient yang dikonfigurasi. Para pembangun adalah NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuilder, dan JdkAsyncHttpClientBuilder.

Contoh berikut menunjukkan cara membuat instans HttpClient menggunakan Netty, OkHttp, dan klien HTTP JDK 11. Instans ini melakukan proksi melalui http://localhost:3128 dan mengautentikasi dengan pengguna example 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 dapat meneruskan instans HttpClient yang dibangun ke pembangun klien layanan untuk digunakan sebagai klien untuk komunikasi 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 utama dalam mencapai konsistensi dan diagnosbilitas di pustaka klien Java untuk Azure. Alur HTTP terdiri dari:

• Transportasi HTTP
• Kebijakan alur HTTP

Anda dapat menyediakan alur HTTP kustom Anda sendiri saat membuat klien. Jika Anda tidak menyediakan pipeline, pustaka klien akan membuat satu yang dikonfigurasi untuk bekerja dengan pustaka klien tersebut.

Transportasi HTTP

Transportasi HTTP bertanggung jawab untuk membuat koneksi ke server, dan mengirim dan menerima pesan HTTP. Transport HTTP berfungsi sebagai gateway bagi pustaka klien Azure SDK untuk berinteraksi dengan layanan Azure. Seperti disebutkan sebelumnya dalam artikel ini, Azure SDK untuk Java menggunakan Netty secara default untuk transportasi HTTP-nya. Namun, SDK juga menyediakan transportasi HTTP yang dapat dicolokkan sehingga Anda dapat menggunakan implementasi lain jika sesuai. SDK juga menyediakan dua implementasi transportasi HTTP lagi untuk OkHttp dan klien HTTP yang dikirim dengan JDK 11 dan yang lebih baru.

Kebijakan alur HTTP

Alur terdiri dari urutan langkah-langkah yang dijalankan untuk setiap putaran respons permintaan 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. Saat Anda mengirim permintaan, kebijakan dijalankan sesuai urutan penambahannya ke alur. Saat Anda menerima respons dari layanan, kebijakan dijalankan dalam urutan terbalik. Semua kebijakan yang ditambahkan ke jalur eksekusi akan berjalan sebelum Anda mengirim permintaan dan setelah Anda menerima respons. Kebijakan harus memutuskan apakah akan bertindak berdasarkan permintaan, respons, 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 kemudian dapat menjalankan operasinya dengan data yang diberikan dan meneruskan kontrol kepada kebijakan berikutnya dalam jalur.

Posisi kebijakan alur HTTP

Saat 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 coba lagi yang dapat mengawasi kegagalan sementara dan secara otomatis mencoba kembali permintaan.

Oleh karena itu, kebijakan coba lagi ini membagi seluruh alur menjadi dua bagian: kebijakan yang dijalankan sebelum kebijakan coba lagi dan kebijakan yang dijalankan setelah kebijakan coba lagi. Kebijakan yang ditambahkan sebelum kebijakan coba ulang dieksekusi hanya sekali per operasi API, dan kebijakan yang ditambahkan setelah kebijakan coba ulang dieksekusi sebanyak kali pengulangan.

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

Kebijakan alur HTTP umum

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

Kebijakan alur HTTP kustom

Kebijakan alur HTTP menyediakan mekanisme yang nyaman untuk memodifikasi atau menghias permintaan dan respons. Anda dapat menambahkan kebijakan kustom ke alur yang dibuat oleh pengguna atau pengembang pustaka klien. Saat menambahkan kebijakan ke pipeline, Anda dapat menentukan apakah kebijakan ini harus dijalankan per panggilan atau per-ulang.

Untuk membuat kebijakan alur HTTP kustom, Anda hanya memperluas jenis kebijakan dasar dan menerapkan beberapa metode abstrak. Anda kemudian dapat menyambungkan kebijakan ke dalam jalur pemrosesan.

Header kustom dalam permintaan HTTP

Pustaka klien Azure SDK for Java menyediakan cara yang konsisten untuk menentukan header yang dikustomisasi melalui objek Context 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, silakan lihat Kelas AddHeadersFromContextPolicy .

Pustaka TLS/SSL bawaan

Semua pustaka klien, secara default, menggunakan pustaka Tomcat-native Boring SSL untuk memungkinkan performa tingkat asli dalam 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.

Mengurangi Tomcat-Native ukuran dependensi TLS/SSL

Secara default, uber JAR dari pustaka Tomcat-Native Boring SSL digunakan dalam SDK Azure untuk Java. Untuk mengurangi ukuran dependensi ini, Anda perlu menyertakan dependensi dengan pengklasifikasi os sesuai netty-tcnative, sebagaimana 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 yang lebih baru, pustaka HttpClient-implementasi (seperti com.azure:azure-core-http-netty) mengelola ketergantungan 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.