تمرين-قم بإعداد تطبيق Java الخاص بك باستخدام Maven

نُقدم نموذجًا لتطبيق Java الخاص بك. استنساخ نموذج إعادة الشراء على نظامك.

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

افتح Windows File Explorer وانتقل إلى نماذج إعادة الشراء المستنسخة. أدخل الدليل الفرعي java_lab.

يحتوي القالب على ملف pom.xml Maven الذي يسحب بالفعل التبعيات المطلوبة لمشروعك. افتح هذا الملف ثم تفحصه للبحث عن التبعية التالية:

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

سحب هذه التبعية في أحدث إصدار من Azure Cosmos DB Java SDK. يمكنك إغلاق هذا الملف.

بعد ذلك، ستقوم ببناء وتشغيل Hello World. باستخدام IDE أو الوحدة الطرفية، افتح هذا المشروع. اعتمادا على IDE الخاص بك، قد يكون هناك خيار لفتح ملف pom.xml في دليل java الفرعي كمشروع.

بعد فتح المشروع، انتقل إلى src/main/java/com/azure/cosmos/examples/mslearnbasicapp وافتح CosmosApp.java، وهو نموذج لتطبيق Java الذي سنطوره. يجب أن يبدو مثل هذا:

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.");
    }
}

كما هو الحال، فإن كود التطبيق يقوم بتنفيذ بسيط «Hello World».

إذا كانت بيئة التطوير المتكامل (IDE) الخاص بك يوفر أدوات لإنشاء وتشغيل تطبيق Maven الخاص بك: قم ببناء وتشغيل التطبيق الخاص بك باستخدام IDE، وتأكد من أن التطبيق يسجل Hello World في الوحدة الطرفية.

إذا كنت ستستخدم المحطة الطرفية لإنشاء وتشغيل تطبيق Maven الخاص بك: استخدم الأمر التالي لإنشاء مشروع Maven:

mvn clean package

ثم قم بالتشغيل:

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

تأكد من أن التطبيق يسجل المخرجات التالية للمحطة الطرفية:

INFO: Hello World.

CosmosApp ضمن الفئة ، قم بإنشاء متغيرات الفئة الثابتة التالية لتفاصيل اتصال Azure Cosmos DB:

/** 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>";

ارجع إلى مدخل Microsoft Azure، وانتقل إلى جزء Keys ، وانسخ/الصق عنوان URI لنقطة نهاية Azure Cosmos DB والمفتاح الأساسي في تعريفات المتغيرات السابقة.

على سبيل المثال، إذا كان URI الخاص بك هو https://cosmosacct.documents.azure.com:443/، فسيبدو تعيين المتغير الجديد كما يلي: private static String endpointUri = "https://cosmosacct.documents.azure.com:443/";. إذا كان المفتاح الأساسي الخاص بك هو elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==، فسيبدو تعيين المتغير الجديد كما يلي: private static String primaryKey = "elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==";.

في CosmosApp.java، أضف تعريف المتغير الثابت التالي إلى الفئة CosmosApp:

/** 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;

على الأرجح، clientdatabaseلم يتم استيراد الفئات و و container حتى الآن إلى ملف Java الخاص بك. لذا هو الوقت المناسب للاعتناء بذلك الآن. قد تسمح لك بعض بيئات التطوير المتكاملة IDE باستيراد التبعيات تلقائيًا استنادًا إلى التعليمات البرمجية التي تكتبها، وقد يكون ذلك مفيدًا هنا. بشكل عام، نتوقع أنه عندما نعطيك كتلة من التعليمات البرمجية للصقها، قد تحتاج إلى إضافة بعض import العبارات لكي تعمل.

private void إنشاء أسلوب يسمى basicOperations بدون وسيطات في الفئة .

إضافة التعليمات البرمجية التالية لإنشاء CosmosAsyncClient مثيل في الأسلوب basicOperations، وتضمين تعليمات برمجية للتحقق ما إذا كانت قاعدة بيانات المستخدمون موجودة أم لا.

 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();

عند هذه النقطة، يحتوي الأسلوب الخاص بك basicOperations على التعليمات البرمجية للتفاعل مع Azure Cosmos DB. ومع ذلك، لم يتم استدعاء هذا الأسلوب في main، لذلك لا يزال تطبيقنا يعمل على طباعة "مرحبًا بالعالم". على سبيل التحقق، قم ببناء وتشغيل CosmosApp.java في بيئة التطوير المتكامل أو قم بتشغيل البرنامج في الجهاز باستخدام:

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

تأكد من أن التطبيق لا يزال يسجل المخرجات التالية إلى المحطة الطرفية:

INFO: Hello World.

انسخ التعليمات البرمجية التالية والصقها في main الأسلوب ، واستبدل السطر الحالي logger.info("Hello World."); .

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.");
}

سيؤدي هذا إلى تشغيل رمز Azure Cosmos DB في تطبيقنا.

إنشاء وتشغيل CosmosApp.java في IDE، أو تشغيل البرنامج في المحطة الطرفية باستخدام:

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

قد تشاهد عددًا كبيرًا من رسائل السجل في المحطة الطرفية، بعضها يتم إنشاؤه بواسطة SDK نفسه. اقرأ وتأكد من أن التطبيق يسجل المخرجات التالية في الجهاز:

INFO: Database and container validation complete

نحن نقدم لك قالبًا لتطبيق Java الخاص بك. استنساخ مستودع القالب على النظام الخاص بك

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

افتح Windows Explorer وانتقل إلى المستودع المستنسخ. أدخل الدليل الفرعي spring_lab.

يحتوي القالب على pom.xml Maven الذي يسحب بالفعل التبعيات المطلوبة لمشروعك. افتح هذا الملف ثم تفحصه للعثور على التبعية أدناه:

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

سحب هذه التبعية في أحدث إصدار من Spring Data Azure Cosmos DB. يمكنك إغلاق هذا الملف.

باستخدام IDE أو الوحدة الطرفية، افتح هذا المشروع. اعتمادا على IDE الخاص بك، قد يكون هناك خيار لفتح ملف pom.xml في الدليل الفرعي spring كمشروع. بعد فتح المشروع، انتقل إلى src/main/resources/ باستخدام أداة مستكشف الملفات. يجب أن تشاهد ملفا باسم application.properties.rename. تؤكد Spring Data على ملفات التكوين عبر معلمات التكوين ذات التعليمات البرمجية المضمنة؛ لإنشاء ملف التكوين لمشروع Spring Data، انسخ application.properties.rename إلى application.properties وافتح ملف application.properties الجديد. يجب أن ترى

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} و${ACCOUNT_KEY}، باستخدام أسلوب من اختيارك - إما نسخ القيم ولصقها في application.properties، أو تحديد متغيرات البيئة هذه في IDE الخاص بك. في الخطوة التالية ستجد القيم التي يجب أن تحتوي عليها هذه المتغيرات.

ارجع إلى مدخل Microsoft Azure، وانتقل إلى جزء Keys ، وانسخ عنوان URI لنقطة نهاية Azure Cosmos DB والمفتاح الأساسي. كما تمت مناقشتها في الخطوة السابقة، استخدم الطريقة التي تختارها لتعيين نقطة نهاية الخاصة بـمعرّف الموارد المنتظم «URI» الخاص بـ Azure Cosmos DB والمفتاح الأساسي للمتغيرات المذكورة أعلاه.

على سبيل المثال، إذا كان معرف الموارد المنتظم «URI» الخاص بك هو https://cosmosacct.documents.azure.com:443/، واخترت لصق نقطة النهاية والمفتاح الأساسي في application.properties، فإن السطر الموجود في application.properties سيبدو فيما بعد كما يلي: cosmos.uri=https://cosmosacct.documents.azure.com:443/. إذا كان المفتاح الأساسي الخاص بك هو elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==، فإن اتباع نفس العملية سيبدو تعيين المتغير الجديد كما يلي: cosmos.key=elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==.

افتح CosmosProperties.java. لقد قدمنا هذا الملف في شكل مكتمل، لذا فقط قم بفحص محتوياته.

@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 بالنظر إلى application.properties، لاحظ أن CosmosProperties أسماء الأعضاء تتوافق بشكل وثيق مع أسماء خصائص application.properties. تقدم الفئة CosmosProperties طلبات getter وsetter لبقية التطبيق للوصول إلى إعدادات التكوين من application.properties. لاحظ أنه لا توجد تعليمات برمجية هنا لسحب التكوين من application.properties - يفهم Spring Data بنية هذا الملف ويعين متغيرات الأعضاء تلقائيا بعد تحليل ملف التكوين.

سوف نستفيد من هذا الإعداد للمضي قدمًا، عندما نقوم بتكوين عميل Azure Cosmos DB.

في Cosmosampleconfiguration.java، افحص الفئة CosmosSampleConfiguration، ثم ابحث عن أسلوب cosmosClientBuilder الفارغ:

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

عند بدء التشغيل، ستقوم Spring Data تلقائيا باستدعاء هذا الأسلوب، والحصول على CosmosClientBuilder الذي يقوم هذا الأسلوب بإرجاعه، واستدعاء أسلوبه build() - عند هذه النقطة (تحت الغطاء) CosmosAsyncClient سيتم إنشاء مثيل استنادا إلى إعدادات التكوين المضمنة CosmosClientBuilderفي . يمكنك استخدام هذا الأسلوب لتكوين CosmosClientBuilder باستخدام أساليب المنشئ.

لاحظ أننا نستخدم إدخال الدالة الإنشائية (بدلاً من إدخال الحقل باستخدام @Autowired) لإنشاء مثيل properties للمتغير وملء متغيّرات الأعضاء خاصته بقيم مُوزَّعة من ملف التكوين. يضمن هذا وجود جميع التبعيات المطلوبة عند إنشاء مثيل هذه الفئة، ويسهِّل كتابة التعليمات البرمجية للاختبار في المستقبل.

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

يمكننا استخدام properties للحصول على uri والمفتاح لحساب Azure Cosmos DB، وتنفيذ cosmosClientBuilder كما هو موضح أدناه:

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

هذا التنفيذ

1. يسحب uri والمفتاح من properties
2. توصيلها بأساليب المنشئ endpoint و key
3. بالإضافة إلى ذلك تكوين اتصال الشبكة إلى خدمة Azure Cosmos DB. (في الوضع المباشر، يتحدث تطبيق العميل مباشرة إلى أقسام Azure Cosmos DB الخلفية.)

ارجع إلى CosmosSampleConfiguration.java، وابحث عن الأسلوب getDatabaseName:

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

قم بتغيير قيمة الإرجاع الافتراضية إلى "Users"، اسم قاعدة البيانات الخاصة بك. بهذه الطريقة، عندما يتصل Spring Data تلقائيا ب Azure Cosmos DB عند بدء التشغيل، فإنه سيتصل بقاعدة بيانات *Users .

انتقل إلى WebCustomer.java. ستلاحظ أن WebCustomer الفئة يسبقها @Container تعليق توضيحي:

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

@Container يأخذ وسيطتين:

• containerName: اسم حاوية Azure Cosmos DB (WebCustomers)
• ru: معدل النقل المقدم على الحاوية الخاصة بك. 400 RU /s هو افتراضي جيد لتمرين Microsoft Learn.

@Container تخصيص لحالة الاستخدام الخاصة بك، كما هو موضح:

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

عند هذه النقطة، يتم إعداد Spring Data الخاصة بك للتفاعل مع Azure Cosmos DB. بعد ذلك، ستقوم ببناء وتشغيل Hello World. انتقل إلى src/main/java/com/azure/cosmos/examples/springexamples وافتح CosmosSample.java، وهو قالب لتطبيق Spring Data الذي سنطوره. يجب أن يبدو مثل هذا:

// 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.");
    }
}

كما هو الحال، فإن كود التطبيق يقوم بتنفيذ بسيط «Hello World».

إذا كانت بيئة التطوير المتكامل (IDE) الخاص بك يوفر أدوات لإنشاء وتشغيل تطبيق Maven الخاص بك: قم ببناء وتشغيل التطبيق الخاص بك باستخدام IDE، وتأكد من أن التطبيق يسجل Hello World في الوحدة الطرفية.

إذا كنت ستستخدم المحطة الطرفية لإنشاء وتشغيل تطبيق Maven الخاص بك: استخدم الأمر التالي لإنشاء مشروع Maven:

mvn clean package

ثم قم بالتشغيل:

mvn spring-boot:run

تأكد من أن التطبيق بتسجيل الإخراج التالي إلى المحطة الطرفية وسط كافة المخرجات الأخرى:

INFO: Hello World.