Alıştırma - Maven kullanarak Java uygulamanızı ayarlama

  • 15 dakika

Bu ünitede verilen kodları istediğiniz IDE ortamında düzenleyerek basit bir konsol uygulaması oluşturacaksınız. Sonrasında isterseniz kendi seçeceğiniz bir terminali kullanarak kodu çalıştırabilirsiniz.

Azure Cosmos DB kaynaklarını oluşturma

Microsoft Learn, bu laboratuvarı tamamlamak için kullanabileceğiniz ücretsiz bir Azure korumalı alanı sunar. Gerekli hesapları ve kaynakları bu korumalı alanda oluşturursunuz. Bu abonelikte bir Azure Cosmos DB hesabı ayarlayacak ve ardından bir veritabanı ve bir kapsayıcı oluşturacaksınız.

  1. Korumalı alanı etkinleştirmek için kullandığınız hesapla Azure portalında oturum açın.
  2. Azure portalını kullanarak yeni bir Azure Cosmos DB hesabı oluşturun ve istediğiniz adı verin. Hesabınız için kaynak grubu seçme adımına geldiğinizde [Sandbox resource group] adlı kaynak grubunu bulun ve seçin.
  3. Azure Cosmos DB hesabınızda Users adlı bir veritabanı oluşturun.
  4. Kullanıcılar veritabanında, /userId bölüm anahtarına sahip WebCustomers adlı bir kapsayıcı oluşturun. WebCustomers için 400 RU/sn sağlayın.

Çalışma dizininizi oluşturma

  1. Java uygulamanızı oluşturmak için kullanabileceğiniz bir şablon verilmiştir. Şablon deposunu sisteminize kopyalayın.

    git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git

  2. Windows Dosya Gezgini'ni açın ve kopyaladığınız depoya gidin. java_lab alt dizinine gidin.

    Önemli

    Bu modülde java_lab alt dizinindeki dosyalar üzerinde çalışacaksınız.

  3. Şablonda projeniz için gerekli bağımlılıkları çeken bir Maven pom.xml dosyası bulunur. Bu dosyayı açın ve aşağıdaki bağımlılığı bulun:

    <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>4.8.0</version>
</dependency>

    Bu bağımlılık, Azure Cosmos DB Java SDK'sının en son sürümünü çeker. Bu dosyayı kapatabilirsiniz.

  4. Şimdi Merhaba Dünya kodunu derleyip çalıştıracaksınız. IDE'nizi veya terminali kullanarak bu projeyi açın. IDE'nize bağlı olarak java alt dizinindeki pom.xml dosyasını açma seçeneği bulunabilir.

    Proje açıldıktan sonra src/main/java/com/azure/cosmos/examples/mslearnbasicapp adresine gidin ve geliştireceğimiz Java uygulaması için bir şablon olan CosmosApp.java dosyasını açın. Şuna benzer şekilde görünecektir:

    import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public final class CosmosApp {

    /** For application to log INFO and ERROR. */
    private static Logger logger = LoggerFactory.getLogger(CosmosApp.class.getSimpleName());

    private CosmosApp() {
        // not called
    }

    /**
    * Main.
    * @param args Command line arguments
    */
    public static void main(final String[] args) {
        logger.info("Hello World.");
    }
}

    Uygulama kodu bu haliyle basit bir "Merhaba Dünya" iletisi yazdırır.

  5. IDE'niz Maven uygulamanızı derlemek ve çalıştırmak için araçlar sunuyorsa: IDE'yi kullanarak uygulamanızı derleyin ve çalıştırın ve uygulamanın terminalde günlüğe kaydedildiğini Hello World onaylayın.

  6. Maven uygulamanızı derlemek ve çalıştırmak için terminali kullanacaksanız: Maven projesini derlemek için aşağıdaki komutu kullanın:

    mvn clean package

    Ardından şunu çalıştırın:

    mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    Uygulamanın terminale aşağıdaki çıkışı yazdırdığını onaylayın:

    INFO: Hello World.

Uygulamayı Azure Cosmos DB’ye bağlama

  1. CosmosApp sınıfının içinde Azure Cosmos DB bağlantı bilgileriniz için aşağıdaki statik sınıf değişkenlerini oluşturun:

    /** Azure Cosmos DB endpoint URI. */
private static String endpointUri = "<your-cosmosdb-hostname>";

/** Azure Cosmos DB primary key. */
private static String primaryKey = "<your-cosmosdb-master-key>";

  2. Azure portalına geri dönün, Anahtarlar bölmesine gidin ve Azure Cosmos DB uç noktası URI'nizle birincil anahtarınızı yukarıdaki değişken tanımlarına yapıştırın.

    Örneğin URI'niz https://cosmosacct.documents.azure.com:443/ ise yeni değişken atamanız şöyle olacaktır: private static String endpointUri = "https://cosmosacct.documents.azure.com:443/";. Birincil anahtarınız elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ== ise yeni değişken atamanız şöyle görünür: private static String primaryKey = "elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==";.

CosmosAsyncClient örneğini oluşturma

Artık Azure Cosmos DB hizmetinin istemci tarafındaki gösterimi olan CosmosAsyncClient örneğini oluşturabilirsiniz. Bu istemci, istekleri hizmete göre yapılandırmak ve çalıştırmak için kullanılır.

  1. CosmosApp.java dosyasındaki CosmosApp sınıfına aşağıdaki statik değişken bildirimini ekleyin:

    /** Azure Cosmos DB client instance. */
private static CosmosAsyncClient client;

/** Azure Cosmos DB database instance. */
private static CosmosAsyncDatabase database;

/** Azure Cosmos DB container instance. */
private static CosmosAsyncContainer container;

    Büyük olasılıkla client, database ve container sınıfları henüz Java dosyanıza aktarılmamıştır. Bu aşamada bunu gerçekleştirebiliriz. Bazı IDE'ler, yazdığınız koda göre bağımlılıkları otomatik olarak içeri aktarmanıza izin verebilir ve bu işlev burada faydalı olabilir. Genelde yapıştırmanız gereken bir kod bloğu verildiğinde ilgili kodun çalışması için birkaç import deyimi eklemeniz gerekebilir.

  2. basicOperations adlı private void yöntemini oluşturun ve sınıfta bağımsız değişken kullanmayın.

  3. Aşağıdaki kodu ekleyerek basicOperations yönteminde bir CosmosAsyncClient örneği oluşturun ve Users veritabanının mevcut olup olmadığını denetlemek için gerekli kodu ekleyin.

     client = new CosmosClientBuilder()
     .endpoint(endpointUri)
     .key(primaryKey)
     .consistencyLevel(ConsistencyLevel.EVENTUAL)
     .directMode()
     .contentResponseOnWriteEnabled(true)
     .buildAsyncClient();

 database = client.getDatabase("Users");
 container = database.getContainer("WebCustomers");            

 logger.info("Database and container validation complete");

 client.close();

  4. Bu noktada basicOperations yönteminiz, Azure Cosmos DB ile etkileşim kurmak için gerekli kodu içerir. Ancak, bu yöntem içinde mainçağrılmaz, bu nedenle uygulamamız hala "Merhaba Dünya" yazdırmaya hizmet eder. Denetim olarak, IDE'de CosmosApp.java'yı derleyip çalıştırın veya aşağıdakileri kullanarak programı terminalde çalıştırın:

    mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    Uygulamanın terminale yine aşağıdaki çıkışı yazdırdığını onaylayın:

    INFO: Hello World.

  5. Aşağıdaki kodu kopyalayıp geçerli satırın main üzerine yazarak yöntemine logger.info("Hello World."); yapıştırın.

    try {
    CosmosApp p = new CosmosApp();
    p.basicOperations();
} catch (CosmosException e) {
    logger.error("Failed while executing app.", e);
} finally {
    logger.info("End of demo, press any key to exit.");
}

    Bu işlem, uygulamanızdaki Azure Cosmos DB kodunu tetikler.

  6. CosmosApp.java uygulamasını IDE'de derleyip çalıştırın veya şu komutu kullanarak programı terminalde çalıştırın:

    mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    Terminalde bazıları SDK tarafından oluşturulanlar olmak üzere çok sayıda günlük iletisi görebilirsiniz. Günlük iletilerini inceleyin ve uygulamanın terminale aşağıdaki çıkışı yazdırdığını onaylayın:

    INFO: Database and container validation complete

Bu ünitede, Azure Cosmos DB Java uygulamanızın temelini hazırladınız. Maven uygulamanızı ayarladınız, basit bir "Merhaba Dünya" projesi oluşturdunuz ve projeyi Azure Cosmos DB uç noktasına bağlanacak şekilde düzenlediniz.

  1. Java uygulamanızı oluşturmak için verilen şablondan faydalanabilirsiniz. Şablon deposunu sisteminize kopyalama

    git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git

  2. Windows Gezgini'ni açın ve kopyalanan depoya gidin. spring_lab alt dizinine gidin.

    Önemli

    Bu modülde spring_lab alt dizinindeki dosyalar üzerinde çalışacaksınız.

  3. Şablonda projeniz için gerekli bağımlılıkları çeken bir Maven pom.xml dosyası bulunur. Bu dosyayı açın ve aşağıdaki bağımlılığı bulun:

    <dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-spring-data-cosmos</artifactId>
  <version>3.24.0</version>
</dependency>

    Bu bağımlılık, Spring Data Azure Cosmos DB’nin en son sürümünü çeker. Bu dosyayı kapatabilirsiniz.

Uygulamayı Azure Cosmos DB’ye bağlama

  1. IDE'nizi veya terminali kullanarak bu projeyi açın. IDE'nize bağlı olarak spring alt dizinindeki pom.xml dosyasını açma seçeneği bulunabilir. Proje açıldıktan sonra dosya gezgini aracını kullanarak src/main/resources/ adresine gidin. application.properties.rename adlı bir dosya görmeniz gerekir. Spring Data, sabit kodlanmış yapılandırma parametreleri yerine yapılandırma dosyalarını vurgular; Spring Data projeniz için yapılandırma dosyasını oluşturmak üzere application.properties.rename öğesini application.properties öğesine kopyalayın ve yeni application.properties dosyasını açın. Şunu görmeniz gerekir:

    cosmos.uri=${ACCOUNT_HOST}
cosmos.key=${ACCOUNT_KEY}
cosmos.secondaryKey=${SECONDARY_ACCOUNT_KEY}

dynamic.collection.name=spel-property-collection
# Populate query metrics
cosmos.queryMetricsEnabled=true

    ${ACCOUNT_HOST} ve ${ACCOUNT_KEY} değerlerini, seçtiğiniz bir yöntemi kullanarak dolduracaksınız - değerleri application.properties içine yapıştırın veya IDE’nizde bu ortam değişkenlerini tanımlayın. Sonraki adımda, bu değişkenlerin sahip olması gereken değerleri bulacaksınız.

  2. Azure portalına geri dönün, Anahtarlar bölmesine gidin ve Azure Cosmos DB uç noktası URI'nizle birincil anahtarınızı kopyalayın. Önceki adımda anlatıldığı gibi, Azure Cosmos DB uç nokta URI’sini ve birincil anahtarınızı belirtilen değişkenlere atamak için tercih ettiğiniz yöntemi kullanın.

    Örneğin, URI’niz https://cosmosacct.documents.azure.com:443/ ise ve uç noktayı ve birincil anahtarı application.properties içine yapıştırmayı seçerseniz, application.properties içindeki satır şöyle görünür: cosmos.uri=https://cosmosacct.documents.azure.com:443/. Birincil anahtarınız elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ== ise, aynı işlemi izleyerek yeni değişken atamanız şöyle görünür: cosmos.key=elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==.

Azure Cosmos DB istemcisini yapılandırma

Spring Data Azure Cosmos DB başlangıçta Azure Cosmos DB istemcisinin otomatik olarak örneğini oluşturur. Azure Cosmos DB istemcisi, hizmete karşı istekleri yürütmek için kullanılan Azure Cosmos DB hizmetinin istemci tarafı gösterimidir. Kodunuz, Azure Cosmos DB istemcisini, application.properties öğesinden alınan özelliklerle birlikte bir oluşturucu yöntemleri kümesini kullanarak örneğini oluşturmadan önce yapılandırabilir.

  1. CosmosProperties.java’yı açın. Bu dosya tamamlanmış bir biçimde sağlanmıştır, bu nedenle yalnızca içeriğini incelemeniz yeterlidir.

    @ConfigurationProperties(prefix = "cosmos")
public class CosmosProperties {

    private String uri;

    private String key;

    private String secondaryKey;

    private boolean queryMetricsEnabled;

    public String getUri() {
        return uri;
    }

    public void setUri(String uri) {
        this.uri = uri;
    }

    public String getKey() {
        return key;
    }

    public void setKey(String key) {
        this.key = key;
    }

    public String getSecondaryKey() {
        return secondaryKey;
    }

    public void setSecondaryKey(String secondaryKey) {
        this.secondaryKey = secondaryKey;
    }

    public boolean isQueryMetricsEnabled() {
        return queryMetricsEnabled;
    }

    public void setQueryMetricsEnabled(boolean enableQueryMetrics) {
        this.queryMetricsEnabled = enableQueryMetrics;
    }
}

    uri, key, secondaryKey, queryMetricsEnabled sınıf üyelerini gözlemleyin. application.properties dosyasına yeniden bakarak, CosmosProperties üye adlarının application.properties özellik adlarına yakından karşılık geldiğini gözlemleyin. CosmosProperties sınıfı, uygulamanızın geri kalanında application.properties yapılandırma ayarlarına erişmek için alıcıları ve ayarlayıcıları sunar. Burada application.properties öğesinden yapılandırmayı çekmek için kod olmadığına dikkat edin - Spring Data bu dosyanın yapısını anlar ve yapılandırma dosyasını ayrıştırdıktan sonra üye değişkenlerini otomatik olarak ayarlar.

    İleride Azure Cosmos DB istemcisini yapılandırırken bu kurulumu kullanacağız.

  2. CosmosSampleConfiguration.java içinde, CosmosSampleConfiguration sınıfını inceleyin ve boş cosmosClientBuilder yöntemini bulun:

    @Bean
public CosmosClientBuilder cosmosClientBuilder() {
    return null;
}

    Başlangıçta, Spring Data otomatik olarak bu yöntemi çağırır, bu yöntemin döndürdüğü CosmosClientBuilder öğesini alır ve build() yöntemini çağırır. Bu noktada, CosmosClientBuilder içinde yer alan yapılandırma ayarları temel alınarak bir CosmosAsyncClient örneği oluşturulur. Bu yöntemi, oluşturucu yöntemlerini kullanarak CosmosClientBuilder yapılandırmak için kullanabilirsiniz.

  3. Değişkenin örneğini oluşturmak ve üye değişkenlerini yapılandırma dosyasından propertiesayrıştırılmış değerlerle doldurmak için kullanarak @Autowired) alan ekleme yerine oluşturucu ekleme kullandığımıza dikkat edin. Bu, bu sınıfın örneği oluşturulduğunda tüm gerekli bağımlılıkların mevcut olmasını sağlar ve gelecekte test kodu yazmayı kolaylaştırır.

    //use constructor injection for spring dependencies 
public CosmosSampleConfiguration(CosmosProperties properties){
    this.properties = properties;
}

    Azure Cosmos DB hesabımız için uri ve anahtarı almak ve aşağıda gösterildiği gibi cosmosClientBuilder uygulamak için properties kullanabiliriz:

    @Bean
public CosmosClientBuilder cosmosClientBuilder() {
    DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();
    return new CosmosClientBuilder()
        .endpoint(properties.getUri())
        .key(properties.getKey())
        .directMode(directConnectionConfig);
}

    Bu uygulama

    1. properties öğesinden uri ve anahtarı alır
    2. Bunları endpoint ve key oluşturucu yöntemlerine ekler
    3. Ayrıca, Azure Cosmos DB hizmetine ağ bağlantısını yapılandırır. (Doğrudan modda istemci uygulamanız doğrudan arka uç Azure Cosmos DB bölümleriyle iletişim kurar.)

  4. CosmosSampleConfiguration.java dosyasına dönün ve getDatabaseName yöntemini bulun:

    @Override
protected String getDatabaseName() { return ""; }

    Varsayılan dönüş değerini, veritabanınızın adı olan "Users" olarak değiştirin. Bu şekilde, Spring Data başlangıçta Azure Cosmos DB’ye otomatik olarak bağlandığında, *Kullanıcılar veritabanına bağlanır.

  5. WebCustomer.java’ya gidin. WebCustomer sınıfının önünde @Container bir ek açıklaması olduğunu fark edeceksiniz:

    @Container(containerName = "", ru = "")

    @Container iki bağımsız değişken alır:

    • containerName: Azure Cosmos DB kapsayıcısının adı (WebCustomers)
    • ru: Kapsayıcınızda sağlanan aktarım hızı. 400 RU/s, bir Microsoft Learn alıştırması için iyi bir varsayılan değerdir.

    Aşağıda gösterildiği gibi @Container öğesini kullanım örneğiniz için özelleştirin:

    @Data
@NoArgsConstructor
@AllArgsConstructor
@Container(containerName = "WebCustomers", ru = "400")
public class WebCustomer {

  6. Bu noktada, Spring Data projeniz Azure Cosmos DB ile etkileşimde bulunmak üzere ayarlanır. Şimdi Merhaba Dünya kodunu derleyip çalıştıracaksınız. src/main/java/com/azure/cosmos/examples/springexamples adresine gidin ve geliştireceğimiz Spring Data uygulaması için bir şablon olan CosmosSample.java dosyasını açın. Şuna benzer şekilde görünecektir:

    // Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.cosmos.examples.springexamples;

import com.azure.cosmos.CosmosException;
import com.azure.cosmos.examples.springexamples.common.CouponsUsed;
import com.azure.cosmos.examples.springexamples.common.OrderHistory;
import com.azure.cosmos.examples.springexamples.common.ShippingPreference;
import com.azure.cosmos.models.CosmosItemResponse;
import com.azure.cosmos.models.PartitionKey;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

@SpringBootApplication
public class CosmosSample implements CommandLineRunner {

    private final Logger logger = LoggerFactory.getLogger(CosmosSample.class);

    private ReactiveWebCustomerRepository reactiveWebCustomerRepository;

    //constructor dependency injection
    public CosmosSample(ReactiveWebCustomerRepository reactiveWebCustomerRepository){
        this.reactiveWebCustomerRepository = reactiveWebCustomerRepository;
    }

    public void run(String... var1) {
        logger.info("Hello world.");
    }
}

    Uygulama kodu bu haliyle basit bir "Merhaba Dünya" iletisi yazdırır.

  7. IDE'niz Maven uygulamanızı derlemek ve çalıştırmak için araçlar sunuyorsa: IDE'yi kullanarak uygulamanızı derleyin ve çalıştırın ve uygulamanın terminalde günlüğe kaydedildiğini Hello World onaylayın.

  8. Maven uygulamanızı derlemek ve çalıştırmak için terminali kullanacaksanız: Maven projesini derlemek için aşağıdaki komutu kullanın:

    mvn clean package

    Ardından şunu çalıştırın:

    mvn spring-boot:run

    Uygulamanın terminale diğer çıkışların yanı sıra aşağıdaki çıkışı yazdırdığını onaylayın:

    INFO: Hello World.

Bu ünitede, Azure Cosmos DB Java uygulamanızın temelini hazırladınız. Maven uygulamasını özelleştirdiniz ve basit bir "Merhaba Dünya" projesini Azure Cosmos DB uç noktasına bağlanacak şekilde genişlettiniz.