Azure SDK ve Maven ile çalışmaya başlama

Bu makalede Java için Azure SDK ile uygulama derlemek için Apache Maven'ın nasıl kullanılacağı gösterilmektedir. Bu makalede Maven ile yeni bir proje ayarlayıp Maven ile projeler oluşturacak ve platforma özgü yerel ikili dosyalar oluşturmak için GraalVM yerel görüntü araçlarını kullanacaksınız.

Java için Azure SDK projesi, yeni bir projenin önyüklemesini hızlandırabilecek bir Maven arketipi içerir. Java Maven için Azure SDK arketipi, dosyalar ve en iyi yöntemleri izleyen bir dizin yapısı ile yeni bir uygulama oluşturur. Özellikle Java Maven için Azure SDK arketipi aşağıdaki özelliklere sahip yeni bir Maven projesi oluşturur:

• Java için Azure SDK'sı için tüm bağımlılıkların uyumlu olmasını sağlayan ve size mümkün olan en iyi geliştirici deneyimini sunan en son azure-sdk-bom BOM sürümüne bağımlılık.
• GraalVM yerel görüntü derlemesi için yerleşik destek.
• Belirtilen Java istemci kitaplıkları için Azure SDK kümesiyle yeni proje oluşturma desteği.
• Birçok en iyi yönteme uyulmasını sağlamak için projenizin derleme zamanı analizini sağlayan Java için Azure SDK derleme araçlarıyla tümleştirme.

Önkoşullar

• Java Developer Kit, sürüm 8 veya üzeri. En iyi deneyim için sürüm 17'yi kullanın.
• Apache Maven

Yeni maven projesi oluşturma

Java Maven arketipinin Azure SDK Maven Central'da mevcuttur. Aşağıdaki komutu çalıştırarak archetype'ı doğrudan yeni bir uygulamayı önyüklemek için kullanabilirsiniz:

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

Bu komutu girdikten sonra, arketipin sizin için doğru çıkışı oluşturabilmesi için bir dizi istem projenizle ilgili ayrıntıları sorar. Aşağıdaki tabloda, değerlerini sağlamanız gereken özellikler açıklanmaktadır:

Ad	Açıklama
groupId	(Gerekli) Oluşturulan proje için POM dosyasında kullanılacak Maven groupId.
artifactId	(Gerekli) Oluşturulan proje için POM dosyasında kullanılacak Maven artifactId.
package	(İsteğe bağlı) Oluşturulan kodu yerleştirecek paket adı. belirtilmezse groupId'dan çıkarılır sonucuna varılır.
azureLibraries	(İsteğe bağlı) Maven artifact kimliklerini kullanarak Azure SDK for Java kitaplıklarının virgülle ayrılmış bir listesi. Bu tür eser kimliklerinin listesi için bkz. Azure SDK Yayınları.
enableGraalVM	(İsteğe bağlı) oluşturulan Maven POM dosyasının GraalVM kullanarak uygulamanızı yerel bir görüntüye derleme desteği içermemesi gerektiğini belirtmek için false; aksi takdirde true. Varsayılan değer true.
javaVersion	(İsteğe bağlı) Oluşturulan projeyi oluştururken hedeflenen JDK'nin 8, 11veya 17gibi en düşük sürümü. Varsayılan değer en son LTS sürümüdür (şu anda 17). En düşük değer 8.
junitVersion	(İsteğe bağlı) Bağımlılık olarak eklenecek JUnit sürümü. Varsayılan değer 5. Geçerli değerler: 4 ve 5.

Alternatif olarak, daha önce gösterilen archetype komutunu çağırdığınızda bu değerleri sağlayabilirsiniz. Bu yaklaşım, örneğin otomasyon amacıyla kullanışlıdır. Değerleri, parametre adına -D eklemeye yönelik standart Maven söz dizimini kullanarak parametreler olarak belirtebilirsiniz; örneğin:

-DjavaVersion=17

Java sürümü desteği

En iyi uygulama olarak, üretim ortamına dağıtım yaparken Java LTS sürümünü kullanın. Varsayılan olarak, Azure SDK Maven arketipi şu anda java 17 temeli ayarlayan en son LTS sürümünü seçer. Ancak, javaVersion parametresini ayarlayarak varsayılan davranışı geçersiz kılabilirsiniz.

Java için Azure SDK derleme aracını kullanma

Java projesinin Azure SDK, projelerinize ekleyebileceğiniz bir Maven derleme aracı içerir. Bu araç yerel olarak çalışır ve Microsoft hiçbir veri göndermez. Aracı bir rapor oluşturacak şekilde yapılandırabilir veya belirli koşullar karşılandığında derlemede başarısız olabilirsiniz. Bu özellik, aşağıdaki uygulamalar gibi en iyi yöntemlerle uyumluluğun sağlanmasına yardımcı olur:

• azure-sdk-for-java ürün reçetesinin doğru kullanımının doğrulanması, en son sürümün kullanılması ve buna dayanarak Azure SDK için Java istemci kütüphanelerindeki bağımlılık sürümlerini tanımlamak dahil. Daha fazla bilgi için Var olan bir proje Java için Azure SDK ekleme bölümüne bakın.
• Daha yeni ve geliştirilmiş sürümler mevcut olduğunda geçmiş Azure istemci kitaplıklarının kullanılmadığını doğrulama.

Rapor ayrıca beta API'lerinin kullanımı hakkında içgörü sağlar.

Derleme aracını, aşağıdaki örnekte gösterildiği gibi bir proje Maven POM dosyasında yapılandırabilirsiniz. {latest_version} yer tutucusunu, çevrimiçi olarak listelenen en son sürümüyle değiştirdiğinizden emin olun.

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

Derleme aracını bir Maven projesine ekledikten sonra, aracı mvn compile azure:run çağrısıyla çalıştırın. Sağladığınız yapılandırmaya bağlı olarak, daha ciddi hale gelmeden önce olası sorunlar konusunda sizi bilgilendirebilecek derleme başarısızlıklarıyla veya oluşturulan rapor dosyalarıyla karşılaşmanız beklenebilir. Bu aracı CI/CD işlem hattınızın bir parçası olarak çalıştırın. Derleme aracı geliştikçe geliştirme ekibi yeni sürümler yayımlar. Yeni sürümleri sık sık denetleyin ve uygun şekilde güncelleştirin.

Derleme aracını belirli özellikleri etkinleştirmek veya devre dışı bırakmak için yapılandırabilirsiniz. Bu yapılandırma için, daha önce gösterilen XML'de bir configuration bölümü ekleyin. Bu bölümde, aşağıdaki tabloda gösterilen ayarları yapılandırın. Açıkça belirtilmemiş tüm yapılandırmalar tabloda belirtilen varsayılan değeri alır.

Özellik adı	Varsayılan değer	Açıklama
validateAzureSdkBomUsed	doğru	Projenin azure-sdk-for-java BOM'a doğru şekilde başvurmasını sağlar; böylece Azure SDK for Java istemci kitaplığı bağımlılıkları sürümlerini BOM'dan alır.
validateLatestBomVersionUsed	doğru	Bağımlılıkların güncel kalmasını, daha yeni bir azure-sdk-for-java BOM'u varsa bunu bildirerek (veya derlemeyi başarısız sayarak) sağlar. Çevrimiçiher zaman en son sürümü bulabilirsiniz.
validateBomVersionsAreUsed	doğru	Bir bağımlılık azure-sdk-for-java BOM tarafından sağlanıyorsa, sürümün elle geçersiz kılınmamasını sağlar.
validateNoDeprecatedMicrosoftLibraryUsed	doğru	Projenin önceki nesil Azure kitaplıklarını kullanmamasını sağlar. Yeni ve önceki nesil kitaplıkları tek bir projede kullanmak herhangi bir soruna neden olmaz, ancak en iyi olmayan geliştirici deneyimiyle sonuçlanır.
validateNoBetaLibraryUsed	yanlış	Bazı Java için Azure SDK istemci kitaplıklarının beta sürümleri mevcuttur ve bu sürümlerin sürüm dizeleri x.y.z-beta.nbiçimindedir. Bu özelliğin etkinleştirilmesi, beta kitaplık kullanılmamasını sağlar.
validateNoBetaApiUsed	doğru	Java için Azure SDK istemci kitaplıkları, bazen @Betaile işaretlenmiş yöntemler içeren Genel Kullanıma Sunulan (GA) sürümlerine sahiptir. Bu denetim, bu tür yöntemlerin kullanılıp kullanılmaymadığını denetler.
sendToMicrosoft	doğru	Derleme raporunun telemetri amacıyla Microsoft'a gönderilip gönderilmeymeyeceğini belirtir. Bu rapor, geliştirme ekibine belgelerin, örneklerin ve geliştirilmiş kolaylık API'lerinin önceliklerini belirleme konusunda yol göstermesine yardımcı olur. Kullanıcı tarafından tanımlanabilir içerik gönderilmez.
reportFile	-	(İsteğe bağlı) Derleme raporunun JSON biçiminde çıktısının yazılacağı konumu belirtir. Belirtilmezse, hiçbir rapor yazılmaz ve derlemenin özeti veya uygun derleme hataları terminalde gösterilir.

Mevcut projeye Java için Azure SDK ekleme

Bağımlılık sürümü yönetimini basitleştirmek için, Java için Azure SDK ekibi her ay Java istemcisi için Azure SDK Malzeme Listesi’ni (BOM) yayımlar. Bu BOM dosyası, uyumlu bağımlılık sürümlerine sahip Java istemci paketleri için tüm Genel Kullanıma Açık (GA) Azure SDK içerir.

BOM'un listelediğini Java istemci kitaplığının Azure SDK bağımlılık sürümlerini kullanmak için projenin pom.xml dosyasına aşağıdaki kod parçacığını ekleyin. yer tutucusunun yerine Java BOMiçin Azure SDK'nın en son sürümünü yazın. {artifactId} yer tutucusunu Azure hizmet SDK'sı paket adıyla değiştirin.

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

Java için Azure SDK istemci BOM'un tüm sürümlerini azure-sdk-bom'de bulabilirsiniz. Java istemci kitaplıkları için Azure SDK en yeni özelliklerinden yararlanmak için en son sürümü kullanın.

Proje bağımlılıklarını tanımlamak için Maven kullanmak, projelerinizi yönetmeyi kolaylaştırabilir. Azure SDK BOM ve Azure SDK Maven arketipini kullanarak projenizi hızlandırabilir ve uzun vadede bağımlılık sürümü oluşturma konusunda daha emin olabilirsiniz. Bağımlılıkları birbiriyle uyumlu ve güncel tutmak için BOM'u kullanın.

Azure SDK BOM'sini eklemenin yanı sıra, Java için Azure SDK derleme aracını da ekleyin. Bu araç, bu makalede daha önce açıklandığı gibi uygulama oluştururken sık karşılaşılan birçok sorunu tanılamaya yardımcı olur.

BOM'a dahil olmayan bir paketi ekleyin

Java için Azure SDK istemci BOM’u yalnızca genel kullanıma sunulan (GA) kitaplıkları içerir. Hâlâ beta sürümünde olan bir paketi veya BOM’a dahil edilenden farklı bir kütüphane sürümünü kullanmak istiyorsanız, bağımlılık bölümünde Maven bağımlılık sürümünü groupId ve artifactId ile birlikte belirtin. Aşağıdaki örnekte gösterildiği gibi, aynı proje POM dosyasında hem BOM sürümlerini kullanan bağımlılıkları hem de geçersiz kılınmış sürümlerle bağımlılıkları seçebilirsiniz.

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

Bu yaklaşımı kullanır ve doğrudan projenizde sürümleri belirtirseniz bağımlılık sürümü çakışmaları alabilirsiniz. Bu çakışmalar, farklı paketlerin ortak bağımlılıkların farklı sürümlerine bağlı olabileceği ve bu sürümlerin birbiriyle uyumlu olmayabileceği için ortaya çıkar. Çakışmalar oluştuğunda, derleme zamanında veya çalışma zamanında istenmeyen davranışlarla karşılaşabilirsiniz. Gerekmediği sürece Azure SDK ürün reçetesindeki sürümleri kullanabilirsiniz. Java için Azure SDK'sını kullanırken bağımlılıklarla ilgilenme hakkında daha fazla bilgi için bkz. bağımlılık sürümü çakışmalarıyla ilgili sorunları giderme.

GraalVM ile yerel görüntü oluşturma

Java uygulamasının yerel görüntüsünü oluşturmak için GraalVM kullanabilirsiniz. GraalVM, Java kodunu önceden yerel makine koduna derler ve bu da belirli durumlarda önemli performans kazançları sağlayabilir. Java için Azure SDK, GraalVM yerel görüntü derlemesini desteklemek için istemci kitaplıklarının her birinde gerekli meta verileri sağlar.

Başlamak için GraalVM'yi yükleyin ve geliştirme sisteminizi yerel görüntüleri derlemeye hazırlayın. GraalVM için yükleme işlemi basittir ve GraalVM belgeleri GraalVM yüklemek ve yerel görüntüyüklemek için GraalVM kullanarak için adım adım yönergeler sağlar. İşletim sisteminiz için gerekli yerel derleyicileri yüklemek için önkoşullar bölümünü dikkatle izleyin.

Java Maven için Azure SDK arketipi, derlemenizi GraalVM yerel görüntü derlemesini destekleyecek şekilde yapılandırabilir, ancak bunu mevcut bir Maven derlemesine de ekleyebilirsiniz. Maven ile ilgili yönergeleri GraalVM web sitesinde bulabilirsiniz.

Ardından yerel görüntü derlemesi çalıştırmaya hazırsınız. GraalVM yerel görüntüsünü kullanmak için standart Maven araçlarını kullanabilirsiniz. Maven için aşağıdaki komutu kullanın:

mvn clean package -Pnative

Bu komutu çalıştırdıktan sonra GraalVM, üzerinde çalıştığı platform için yerel bir yürütülebilir dosya çıkışı oluşturur. Yürütülebilir dosya, projenizin Maven /target dizininde görünür. Artık uygulamanızı bu yürütülebilir dosyayla çalıştırabilirsiniz ve standart bir Java uygulamasına benzer şekilde çalışmalıdır.

Sonraki adımlar

IntelliJ ve Eclipse için Azure uzantılarını kullanmaya başlama