Azure SDK ve Apache 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 ürün reçetesi sürümü bağımlılığı.
• 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 öneririz.
• Apache Maven

Yeni bir Maven projesi oluşturma

Java Maven için Azure SDK arketipi Maven Central'da yayımlanır. Bu, aşağıdaki komutla yeni bir uygulamayı önyüklemek için arketipi doğrudan kullanabileceğiniz anlamına gelir:

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 oluşturulan POM dosyasında kullanılacak Maven groupId .
artifactId	(Gerekli) Oluşturulan proje için oluşturulan POM dosyasında kullanılacak Maven artifactId .
package	(İsteğe bağlı) Oluşturulan kodu yerleştirecek paket adı. belirtilmezse dosyasından groupId çıkarılır.
azureLibraries	(İsteğe bağlı) Maven yapıt kimliklerini kullanarak Java kitaplıkları için Azure SDK'sının virgülle ayrılmış listesi. Bu tür yapıt kimliklerinin listesi için bkz . Azure SDK Sürümleri.
enableGraalVM	(İsteğe bağlı) false değeri, oluşturulan Maven POM dosyasının GraalVM kullanarak uygulamanızı yerel bir görüntüye derleme desteği içermemesi gerektiğini belirtir; aksi takdirde true. Varsayılan değer true değeridir.
javaVersion	(İsteğe bağlı) 8, 11 veya 17 gibi oluşturulan projeyi oluştururken hedeflenen en düşük JDK sürümü. Varsayılan değer en son LTS sürümüdür (şu anda 17). En düşük değer 8'dir.
junitVersion	(İsteğe bağlı) Bağımlılık olarak eklenecek JUnit sürümü. Varsayılan değer 5'tir. 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. Parametre adına eklemenin -D standart Maven söz dizimini kullanarak değerleri parametre 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ü kullanmanız gerekir. Varsayılan olarak, Azure SDK Maven arketipi şu anda java 17 temeli ayarlayan en son LTS sürümünü seçer. Ancak, parametresini ayarlayarak javaVersion varsayılan davranışı geçersiz kılabilirsiniz.

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

Java için Azure SDK projesi, projelerinize ekleyebileceğiniz bir Maven derleme aracı sunar. Bu araç yerel olarak çalışır ve Microsoft'a veri iletmez. Aracı bir rapor oluşturacak veya belirli koşullar karşılandığında derlemede başarısız olacak şekilde yapılandırabilirsiniz. Bu, aşağıdaki uygulamalar gibi çok sayıda en iyi yöntemle uyumluluğu sağlamak için yararlıdır:

• En son sürümü kullanmak ve Java istemci kitaplıkları için Azure SDK'da bağımlılık sürümlerini tanımlamak için bu ürün reçetesinin doğru kullanımını azure-sdk-for-java doğrulama. Daha fazla bilgi için Var olan bir projeye 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. Yer tutucuyu {latest_version} çevrimiçi listelenen en son sürümle değiştirerek değiştirmeyi unutmayın.

<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 çağırarak mvn compile azure:runaracı çalıştırabilirsiniz. Sağlanan yapılandırmaya bağlı olarak, daha ciddi hale gelmeden önce olası sorunlar hakkında sizi bilgilendirebilecek derleme hatalarını veya rapor dosyalarının oluşturulduğunu görebilirsiniz. Bu aracı CI/CD işlem hattınızın bir parçası olarak çalıştırmanızı öneririz. Derleme aracı geliştikçe yeni sürümler yayımlayacağız ve geliştiricilerin yeni sürümleri sık sık denetlemesini ve uygun şekilde güncelleştirmesini öneririz.

Derleme aracını belirli özellikleri etkinleştirmek veya devre dışı bırakmak için yapılandırmak mümkündür. 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	true	Java istemci kitaplığı bağımlılıkları için Azure SDK'sının ürün reçetesinden sürümlerini alabilmesi için projenin uygun şekilde başvuruda bulunduğu azure-sdk-for-java ürün reçetesine sahip olmasını sağlar.
validateLatestBomVersionUsed	true	Daha yeni bir azure-sdk-for-java ürün reçetesi varsa, geri raporlama yaparak (veya derlemede başarısız olarak) bağımlılıkların güncel tutulmasını sağlar. Her zaman en son sürümü çevrimiçi bulabilirsiniz.
validateBomVersionsAreUsed	true	Azure-sdk-for-java bom'dan bir bağımlılığın kullanılabildiği durumlarda sürümün el ile geçersiz kılınmamasını sağlar.
validateNoDeprecatedMicrosoftLibraryUsed	true	Projenin önceki nesil Azure kitaplıklarını kullanmamasını sağlar. Yeni ve önceki nesil kitaplıkların tek bir projede kullanılması herhangi bir soruna neden olmaz, ancak en iyi olmayan geliştirici deneyimiyle sonuçlanır.
validateNoBetaLibraryUsed	yanlış	Bazı Java istemci kitaplıkları için Azure SDK'sının sürümünde x.y.z-beta.nsürüm dizeleri bulunan beta sürümleri vardır. Bu özelliğin etkinleştirilmesi, beta kitaplık kullanılmamasını sağlar.
validateNoBetaApiUsed	true	Java için Azure SDK istemci kitaplıkları bazen ile ek açıklamalı yöntemler içeren GA sürümlerine @Betasahiptir. Bu denetim, bu tür yöntemlerin kullanılıp kullanılmadığını denetler.
sendToMicrosoft	true	Derleme raporunun telemetri amacıyla Microsoft'a gönderilip gönderilmeymeyeceğini belirtir. Bu, 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 yazacak 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 kolaylaştırmak için Java için Azure SDK ekibi her ay Java için Azure SDK istemci ürün reçetesini yayımlar. Bu BOM dosyası, uyumlu bağımlılık sürümlerine sahip tüm Genel Kullanıma Açık (GA) Java istemci paketlerini içerir.

BOM'daki Java istemci kitaplığı için Azure SDK'sının bağımlılık sürümlerini kullanmak için, pom.xml projesi dosyasına aşağıdaki kod parçacığını ekleyin. Yer tutucuyu {bom_version_to_target} Java BOM için Azure SDK'nın en son sürümüyle değiştirin. Yer tutucusunu {artifactId} 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 ürün reçetesinin tüm sürümlerini azure-sdk-bom adresinde bulabilirsiniz. Java istemci kitaplıkları için Azure SDK'sının en yeni özelliklerinden yararlanmak için en son sürümü kullanmanızı öneririz.

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 arketipi ile projenizi hızlandırabilir ve uzun vadede bağımlılık sürümü oluşturma konusunda daha fazla güvenebilirsiniz. Bağımlılıkları uyumlu ve güncel tutmak için BOM kullanmanızı öneririz.

Azure SDK BOM'unu eklemeye ek olarak, Java için Azure SDK derleme aracını da eklemenizi öneririz. 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.

Ürün reçetesine dahil olmayan bir paket ekleme

Java için Azure SDK istemci ürün reçetesi yalnızca Genel Kullanıma Açık (GA) kitaplıkları içerir. Hala beta sürümünde olan bir pakete veya ÜR'ye dahil edilenden farklı bir kitaplık sürümüne bağımlı olmak istiyorsanız, ve ile birlikte groupId ve artifactId bağımlılık bölümünde Maven bağımlılık sürümünü belirtebilirsiniz. Aşağıdaki örnekte gösterildiği gibi, aynı proje POM dosyasında geçersiz kılınmış sürümlerle bom sürümlerini ve bağımlılıklarını kullanan bağımlılıklar olmasını 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ın nedeni, farklı paketlerin ortak bağımlılıkların farklı sürümlerine bağlı olması ve bu sürümlerin birbiriyle uyumlu olmamasıdır. Çakışmalar oluştuğunda, derleme zamanında veya çalışma zamanında istenmeyen davranışlarla karşılaşabilirsiniz. Gerekli olmadığı sürece Azure SDK BOM'daki sürümlere güvenmenizi öneririz. 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ını 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üklemeniz ve geliştirme sisteminizi yerel görüntüleri derlemeye hazırlamanız gerekir. GraalVM için yükleme işlemi basittir ve GraalVM belgeleri GraalVM'yi yüklemek ve yerel görüntü yüklemek için GraalVM'yi kullanmak 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