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.

Penting

Pastikan dependensi azure-core-http-netty Anda menggunakan versi 1.15.12 atau yang lebih baru. Jika Anda menggunakan BOM, pastikan versi BOM Anda setidaknya 1.2.36.

Versi minimum ini diperlukan untuk mengaktifkan header HTTP besar yang dikembalikan oleh Azure Resource Manager selama operasi yang berjalan lama.

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:

Nota

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

Ubah klien HTTP default

Jika Anda lebih suka implementasi lain, hapus dependensi pada Netty dengan mengecualikannya dalam file konfigurasi build. Dalam file pom.xml Maven, kecualikan dependensi Netty dan sertakan dependensi lain.

Contoh berikut menunjukkan cara mengecualikan dependensi Netty dari dependensi aktual terhadap pustaka azure-security-keyvault-secrets. Pastikan untuk mengecualikan Netty dari semua pustaka yang sesuai com.azure , seperti yang ditunjukkan dalam contoh:

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

<!-- OkHttp -->
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-http-okhttp</artifactId>
  <version>1.12.10</version>
</dependency>

<!-- JDK HttpClient -->
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-http-jdk-httpclient</artifactId>
  <version>1.0.3</version>
</dependency>

Nota

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

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 dapat Anda gunakan untuk membuat instans yang dikonfigurasi HttpClient . Para pembangun adalah NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuilder, dan JdkAsyncHttpClientBuilder.

Contoh berikut menunjukkan cara membuat HttpClient instans dengan menggunakan Netty, OkHttp, dan klien HTTP JDK. 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 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, atur HttpClient saat mengonfigurasi Manager.

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.

Cuplikan layar alur HTTP di Azure SDK untuk Java, memperlihatkan urutan eksekusi transportasi dan kebijakan untuk permintaan dan respons.

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 menyertakan kebijakan HTTP yang umum diperlukan yang dapat Anda tambahkan ke alur.

Policy Link GitHub
kebijakan percobaan kembali RetryPolicy.java
kebijakan autentikasi BearerTokenAuthenticationPolicy.java
kebijakan pencatatan HttpLoggingPolicy.java
Kebijakan ID permintaan RequestIdPolicy.java
kebijakan telemetri UserAgentPolicy.java

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 Anda atau pengembang pustaka klien buat. Saat menambahkan kebijakan ke pipeline, Anda dapat menentukan apakah kebijakan ini akan dijalankan per panggilan atau pada setiap percobaan ulang.

Untuk membuat kebijakan alur HTTP kustom, perluas jenis kebijakan dasar dan terapkan 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 menggunakan pustaka BoringSSL native Tomcat secara bawaan. Pustaka ini menyediakan performa tingkat asli untuk operasi TLS/SSL. Pustaka Boring SSL adalah berkas JAR uber yang berisi pustaka native untuk Linux, macOS, dan Windows. Ini menawarkan performa yang lebih baik dibandingkan dengan implementasi TLS/SSL default dalam JDK.

Mengurangi Tomcat-Native ukuran dependensi TLS/SSL

Secara bawaan, Azure SDK untuk Java menggunakan uber JAR pustaka Tomcat-Native Boring SSL. Untuk mengurangi ukuran dependensi ini, sertakan dependensi dengan classifier os seperti yang dijelaskan dalam netty-tcnative, seperti yang ditunjukkan pada 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 TLS/SSL bawaan JDK alih-alih Tomcat-Native Boring SSL, kecualikan pustaka Tomcat-native Boring SSL. Berdasarkan pengujian, performa JDK TLS/SSL lebih lambat 30% 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.

  • Last updated on