Mulai menggunakan Azure SDK dan Apache Maven

Artikel
02/14/2025

Artikel ini memperlihatkan kepada Anda cara menggunakan Apache Maven untuk membangun aplikasi dengan Azure SDK for Java. Dalam artikel ini, Anda menyiapkan proyek baru dengan Maven, membangun proyek dengan Maven, dan menggunakan alat gambar asli GraalVM untuk membuat biner asli khusus platform.

Proyek Azure SDK for Java menyertakan arketipe Maven yang dapat mempercepat bootstrapping proyek baru. Arketipe Azure SDK for Java Maven membuat aplikasi baru, dengan file dan struktur direktori yang mengikuti praktik terbaik. Secara khusus, arketipe Azure SDK for Java Maven membuat proyek Maven baru dengan fitur-fitur berikut:

Bergantung pada rilis BOM azure-sdk-bom paling terkini, yang memastikan bahwa semua dependensi untuk Azure SDK for Java benar-benar selaras, sehingga memberi Anda pengalaman terbaik sebagai pengembang.
Dukungan bawaan untuk kompilasi gambar asli GraalVM.
Dukungan untuk menghasilkan proyek baru dengan sekumpulan pustaka klien Azure SDK for Java tertentu.
Integrasi dengan perangkat alat pengembangan Azure SDK untuk Java, yang memberikan analisis pada waktu kompilasi proyek Anda untuk memastikan bahwa banyak praktik terbaik diikuti.

Prasyarat

Java Developer Kit, versi 8 atau yang lebih baru. Kami merekomendasikan versi 17 untuk pengalaman terbaik.
Apache Maven

Membuat proyek Maven baru

Arketipe Azure SDK for Java Maven diterbitkan ke Maven Central. Itu berarti Anda dapat menggunakan arketipe langsung untuk bootstrap aplikasi baru dengan perintah berikut:

mvn archetype:generate \
    -DarchetypeGroupId=com.azure.tools \
    -DarchetypeArtifactId=azure-sdk-archetype

Setelah Anda memasukkan perintah ini, serangkaian perintah meminta detail tentang proyek Anda sehingga arketipe dapat menghasilkan output yang tepat untuk Anda. Tabel berikut ini menjelaskan properti yang perlu Anda berikan nilainya untuk:

Nama	Deskripsi
`groupId`	(Diperlukan) Maven `groupId` untuk digunakan dalam file POM yang dibuat untuk proyek yang dihasilkan tersebut.
`artifactId`	(Diperlukan) Maven `artifactId` digunakan dalam file POM yang dibuat untuk proyek yang dihasilkan.
`package`	(Opsional) Nama paket untuk memasukkan kode yang dihasilkan. Disimpulkan dari `groupId` jika tidak ditentukan.
`azureLibraries`	(Opsional) Daftar pustaka Azure SDK untuk Java yang dipisahkan dengan tanda koma, menggunakan ID artefak Maven. Untuk melihat daftar ID artefak tersebut, kunjungi Rilis Azure SDK.
`enableGraalVM`	(Opsional) `false` untuk menunjukkan bahwa file POM Maven yang dihasilkan tidak boleh menyertakan dukungan untuk mengkompilasi aplikasi Anda ke gambar asli menggunakan GraalVM; jika tidak, `true`. Nilai defaultnya adalah `true`.
`javaVersion`	(Opsional) Versi minimum JDK yang akan ditargetkan saat membangun proyek yang dihasilkan, seperti `8`, `11`, atau `17`. Nilai default adalah rilis LTS terbaru (saat ini `17`). Nilai minimum adalah `8`.
`junitVersion`	(Opsional) Versi JUnit untuk dimasukkan sebagai dependensi. Nilai defaultnya adalah `5`. Nilai yang valid `4` dan `5`.

Secara bergantian, Anda dapat memberikan nilai-nilai ini saat memanggil perintah arketipe yang ditunjukkan sebelumnya. Pendekatan ini berguna, misalnya, untuk tujuan otomatisasi. Anda dapat menentukan nilai sebagai parameter menggunakan sintaks Maven standar untuk menambahkan -D ke nama parameter, misalnya:

-DjavaVersion=17

Dukungan versi Java

Sebagai praktik terbaik, Anda harus menggunakan rilis Java LTS saat menyebarkan ke produksi. Secara default, arketipe Azure SDK Maven memilih rilis LTS terbaru, yang saat ini menetapkan garis besar Java 17. Namun, Anda dapat mengambil alih perilaku default dengan mengatur parameter javaVersion.

Menggunakan alat build Azure SDK for Java

Proyek Azure SDK for Java mengirimkan alat build Maven yang dapat Anda sertakan dalam proyek Anda. Alat ini berjalan secara lokal dan tidak mengirimkan data apa pun ke Microsoft. Anda dapat mengonfigurasi alat untuk membuat laporan atau gagal membangun ketika kondisi tertentu terpenuhi, yang berguna untuk memastikan kepatuhan dengan banyak praktik terbaik, seperti praktik berikut:

Validasi penggunaan BOM azure-sdk-for-java yang benar, termasuk menggunakan versi terbaru, dan mengandalkannya untuk menentukan versi dependensi pada perpustakaan klien Azure SDK untuk Java. Untuk informasi selengkapnya, lihat bagian Menambahkan Azure SDK for Java ke proyek yang sudah ada.
Validasi bahwa pustaka klien Azure versi lama tidak digunakan ketika tersedia versi yang lebih baru dan lebih baik.

Laporan ini juga memberikan wawasan tentang penggunaan API beta.

Anda dapat mengonfigurasi alat build dalam file POM Maven proyek seperti yang ditunjukkan dalam contoh berikut. Pastikan untuk mengganti placeholder {latest_version} dengan versi terbaru yang tercantum daring.

<build>
  <plugins>
    <plugin>
      <groupId>com.azure.tools</groupId>
      <artifactId>azure-sdk-build-tool</artifactId>
      <version>{latest_version}</version>
    </plugin>
  </plugins>
</build>

Setelah menambahkan alat build ke dalam proyek Maven, Anda dapat menjalankan alat dengan memanggil mvn compile azure:run. Bergantung pada konfigurasi yang disediakan, Anda dapat mengharapkan untuk melihat kegagalan build atau file laporan yang dihasilkan yang dapat memberi tahu Anda tentang potensi masalah sebelum menjadi lebih serius. Kami menyarankan agar Anda menjalankan alat ini sebagai bagian dari alur CI/CD Anda. Seiring berkembangnya alat build, kami akan menerbitkan rilis baru, dan kami menyarankan agar pengembang sering memeriksa rilis baru dan memperbarui sebagaimana merujuk.

Dimungkinkan untuk mengonfigurasi alat build untuk mengaktifkan atau menonaktifkan fitur tertentu. Untuk konfigurasi ini, tambahkan bagian configuration di XML yang diperlihatkan sebelumnya. Di dalam bagian tersebut, konfigurasikan pengaturan yang diperlihatkan dalam tabel berikut. Konfigurasi apa pun yang tidak disebutkan secara eksplisit mengambil nilai default yang ditentukan dalam tabel.

Nama properti	Nilai default	Deskripsi
`validateAzureSdkBomUsed`	benar	Memastikan bahwa proyek memiliki BOM azure-sdk-for-java yang dihubungkan dengan tepat, sehingga dependensi pustaka klien Azure SDK for Java dapat mengambil versi mereka dari BOM.
`validateLatestBomVersionUsed`	benar	Memastikan bahwa dependensi tetap diperbarui dengan melaporkan kembali (atau gagal build) jika BOM azure-sdk-for-java yang lebih baru ada. Anda selalu dapat menemukan versi terbaru online .
`validateBomVersionsAreUsed`	benar	Memastikan bahwa, jika ada dependensi yang tersedia dari BOM azure-sdk-for-java, versinya tidak diganti secara manual.
`validateNoDeprecatedMicrosoftLibraryUsed`	benar	Memastikan bahwa proyek tidak menggunakan pustaka Azure generasi sebelumnya. Menggunakan pustaka baru dan generasi sebelumnya dalam satu proyek tidak mungkin menyebabkan masalah apa pun, tetapi mengakibatkan pengalaman pengembang yang tidak optimal.
`validateNoBetaLibraryUsed`	palsu	Beberapa perpustakaan klien Azure SDK untuk Java memiliki rilis beta, dengan string versi dalam bentuk `x.y.z-beta.n`. Mengaktifkan fitur ini memastikan bahwa tidak ada pustaka beta yang digunakan.
`validateNoBetaApiUsed`	benar	Azure SDK untuk pustaka klien Java terkadang memiliki rilis GA dengan metode yang dianotasi dengan `@Beta`. Pemeriksaan ini bertujuan untuk mengecek apakah ada metode seperti itu yang sedang digunakan.
`sendToMicrosoft`	benar	Menentukan apakah akan mengirim laporan build ke Microsoft untuk tujuan telemetri. Ini membantu memandu tim pengembangan tentang prioritas dalam dokumentasi, sampel, dan pengembangan API yang lebih mudah digunakan. Tidak ada konten yang dapat diidentifikasi pengguna yang dikirimkan.
`reportFile`	-	(Opsional) Menentukan lokasi untuk menulis laporan build, dalam format JSON. Jika tidak ditentukan, tidak ada laporan yang ditulis, dan ringkasan proses pembangunan, atau kegagalan pembangunan yang sesuai, ditampilkan di terminal.

Menambahkan Azure SDK untuk Java ke proyek yang sudah ada

Untuk membuat manajemen versi dependensi lebih sederhana, tim Azure SDK for Java menerbitkan Azure SDK untuk BOM klien Java setiap bulan. File BOM ini mencakup semua paket klien Azure SDK yang Tersedia Secara Umum (GA) untuk Java dengan versi dependensi yang kompatibel.

Untuk menggunakan versi dependensi untuk pustaka klien Azure SDK for Java yang ada di BOM, sertakan cuplikan berikut di dalam file proyek pom.xml. Gantikan placeholder {bom_version_to_target} dengan rilis terbaru dari Azure SDK untuk Java BOM. Ganti tempat penampung {artifactId} dengan nama paket SDK layanan Azure.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-sdk-bom</artifactId>
      <version>{bom_version_to_target}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>{artifactId}</artifactId>
  </dependency>
</dependencies>

Anda dapat menemukan semua rilis Azure SDK untuk BOM klien Java di azure-sdk-bom. Sebaiknya gunakan versi terbaru untuk memanfaatkan fitur terbaru pustaka klien Azure SDK for Java.

Menggunakan Maven untuk menentukan dependensi proyek dapat membuat pengelolaan proyek Anda lebih sederhana. Dengan Azure SDK BOM dan arketipe Azure SDK Maven, Anda dapat mempercepat proyek dan lebih yakin tentang pengelolaan versi dependensi Anda untuk jangka panjang. Sebaiknya gunakan BOM untuk menjaga dependensi tetap selaras dan terbaru.

Selain menambahkan Azure SDK BOM, sebaiknya sertakan juga alat build Azure SDK for Java. Alat ini membantu mendiagnosis banyak masalah yang umum ditemui saat membangun aplikasi, seperti yang dijelaskan sebelumnya dalam artikel ini.

Sertakan paket yang tidak ada di BOM

AZURE SDK untuk BOM klien Java hanya menyertakan pustaka Generally Available (GA). Jika Anda ingin bergantung pada paket yang masih dalam versi beta atau pada pustaka yang berbeda dari yang disertakan dalam BOM, Anda dapat menentukan versi dependensi Maven bersama dengan groupId dan artifactId di bagian dependensi. Anda dapat memilih untuk memiliki dependensi yang menggunakan versi BOM dan dependensi dengan versi yang diubah dalam file POM proyek yang sama, seperti yang ditunjukkan dalam contoh berikut:

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventhubs</artifactId> <!-- Use the dependency version that is in the BOM -->
  </dependency>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-servicebus</artifactId>
    <version>7.4.0</version> <!-- Override the Service Bus dependency version specified in the BOM -->
  </dependency>
</dependencies>

Jika Anda menggunakan pendekatan ini dan menentukan versi langsung dalam proyek, Anda mungkin mendapatkan konflik versi dependensi. Konflik ini muncul karena paket yang berbeda mungkin bergantung pada versi dependensi umum yang berbeda, dan versi ini mungkin tidak kompatibel satu sama lain. Ketika konflik terjadi, Anda dapat mengalami perilaku yang tidak diinginkan pada waktu kompilasi atau runtime. Sebaiknya Anda mengandalkan versi yang ada di Azure SDK BOM kecuali diperlukan. Untuk informasi selengkapnya tentang menangani dependensi saat menggunakan Azure SDK for Java, lihat Memecahkan masalah konflik versi dependensi.

Membangun gambar asli dengan GraalVM

Anda dapat menggunakan GraalVM untuk membuat gambar asli aplikasi Java. GraalVM mengkompilasi kode Java sebelumnya ke dalam kode mesin asli, yang dapat menghasilkan perolehan performa drastis dalam situasi tertentu. Azure SDK for Java menyediakan metadata yang diperlukan di setiap pustaka kliennya untuk mendukung kompilasi gambar asli GraalVM.

Untuk memulai, Anda perlu menginstal GraalVM dan menyiapkan sistem pengembangan Anda untuk mengkompilasi gambar asli. Proses penginstalan GraalVM sangat mudah, dan dokumentasi GraalVM menyediakan instruksi langkah demi langkah untuk menginstal GraalVM dan menggunakan GraalVM untuk menginstalnative-image. Ikuti bagian prasyarat dengan hati-hati untuk menginstal kompilator asli yang diperlukan untuk sistem operasi Anda.

Azure SDK untuk archetype Java Maven dapat mengonfigurasi build Anda untuk mendukung kompilasi image native GraalVM, tetapi Anda juga dapat menambahkannya ke build Maven yang sudah ada. Anda dapat menemukan petunjuk untuk Maven di situs web GraalVM.

Selanjutnya, Anda siap untuk melakukan pembangunan citra asli. Anda dapat menggunakan alat Maven standar untuk menggunakan gambar asli GraalVM. Untuk Maven, gunakan perintah berikut:

mvn clean package -Pnative

Setelah Anda menjalankan perintah ini, GraalVM menghasilkan executable asli untuk platform yang dijalankannya. File executable dapat ditemukan di direktori Maven /target proyek Anda. Anda sekarang dapat menjalankan aplikasi Anda dengan file yang dapat dieksekusi ini, dan harus berkinerja mirip dengan aplikasi Java standar.

Langkah berikutnya

Mulai menggunakan ekstensi Azure untuk IntelliJ dan Eclipse

Bagikan melalui