İngilizce dilinde oku

Aracılığıyla paylaş

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

  • Makale

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

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

Bash 
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şturulmuş 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. 4 ve 5geçerli değerler.

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 -D eklemenin standart Maven söz dizimini kullanarak değerleri parametre olarak belirtebilirsiniz, örneğin:

Bash 
-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, javaVersion parametresini ayarlayarak 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:

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

XML 
<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 mvn compile azure:runçağırarak aracı çalıştırabilirsiniz. Sağlanan yapılandırmaya bağlı olarak, daha ciddi hale gelmeden önce olası sorunlar hakkında sizi bilgilendirebilecek derleme hataları görebilir veya rapor dosyalarının oluşturulduğunu fark edebilirsiniz. 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 doğru Azure SDK for Java istemci kütüphane bağımlılıklarının sürümlerini BOM'dan alabilmesi için projenin azure-sdk-for-java BOM'e uygun şekilde referans verdiğinden emin olur.
validateLatestBomVersionUsed doğru Azure-sdk-for-java BOM daha yeni bir varsa, geri bildirimde bulunarak (veya derlemeyi başarısız kılarak) bağımlılıkların güncel tutulmasını sağlar. Çevrimiçiher zaman en son sürümü bulabilirsiniz.
validateBomVersionsAreUsed doğru Azure-sdk-for-java BOM içinden bir bağımlılık mevcut olduğunda, 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ı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 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ılmadığını denetler.
sendToMicrosoft doğru 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 çı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 kolaylaştırmak için, Java için Azure SDK ekibi, her ay Java için Azure SDK istemci BOM'unu 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 proje 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.

XML 
<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'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.

BOM'a dahil olmayan bir paketi ekleyin

Java için Azure SDK istemci BOM'u (Malzeme Listesi) yalnızca Genel Kullanıma Açık (GA) kitaplıkları içerir. Hala beta sürümünde olan bir pakete veya ürün reçetesine dahil edilenden farklı bir kitaplık sürümüne bağımlı olmak istiyorsanız, Bağımlılık bölümündeki groupId ve artifactId ile birlikte Maven bağımlılık sürümünü belirtebilirsiniz. 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.

XML 
<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ı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ü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 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:

shell 
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