上一個

下一個

練習 - 使用 Maven 設定 Java 應用程式

已完成

在此單元中，您將使用自己偏好的 IDE 來編輯程式碼，以建立基本的主控台應用程式。 您將會選擇性地使用自己偏好的終端機來執行該程式碼。

建立 Azure Cosmos DB 資源

為了協助完成此實驗室，Microsoft Learn 提供免費的 Azure 沙箱，讓您可在其中建立帳戶與資源。 您將在此訂用帳戶中設定 Azure Cosmos DB 帳戶，然後建立資料庫與容器。

1. 使用您啟用沙箱時所用的相同帳戶來登入 Azure 入口網站。
2. 透過使用 Azure 入口網站，以您選擇的名稱建立 Azure Cosmos DB 帳戶。 當商機抵達以選擇您帳戶的資源群組時，請尋找資源群組 [沙箱資源群組]，然後加以選取。
3. 在 Azure Cosmos DB 帳戶中建立名為 Users 的資料庫。
4. 在 Users 資料庫中，建立名為 WebCustomers 且具有分割區索引鍵 /userId 的容器。 針對 WebCustomers 佈建 400 RU/s。

建立工作目錄

1. 我們會提供 Java 應用程式的範本。 將範本存放庫複製到您的系統。

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

2. 開啟 Windows 檔案總管並移至複製的存放庫。 輸入 java_lab 子目錄。

   重要

   您在此課程模組中完成的所有工作都會位於 [java] 子目錄底下。

3. 此範本包含 Maven pom.xml 檔案，其已提取您專案的必要相依性。 開啟此檔案並加以檢查，以找出下列相依性：

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

   此相依性會提取最新版本的 Azure Cosmos DB Java SDK。 您可以關閉此檔案。

4. 接下來，您將建置並執行 Hello World。 透過使用您的 IDE 或終端機，開啟此專案。 視您的 IDE 而定，可能會有選項可將 java 子目錄中的 pom.xml 檔案開啟為專案。

   在專案開啟之後，移至 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"。

5. 若 IDE 會提供工具建置及執行 Maven 應用程式：使用 IDE 建置及執行應用程式，並確認應用程式會將 Hello World 記錄到終端機。

6. 如果您使用終端機來建置並執行 Maven 應用程式：使用下列命令來建置 Maven 專案：

   mvn clean package
   

   然後執行：

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

   確認應用程式會將下列輸出記錄到終端機：

   INFO: Hello World.
   

將應用程式連線到 Azure Cosmos DB

1. 在 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>";
   

2. 返回 Azure 入口網站，移至 [金鑰] 窗格，然後將 Azure Cosmos DB 端點 URI 與主金鑰複製/貼上到上述變數定義。

   例如，如果您的 URI 是 https://cosmosacct.documents.azure.com:443/，則新的變數指派看起來會像這樣：private static String endpointUri = "https://cosmosacct.documents.azure.com:443/";。 若 URI 是 elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==，則新變數指派看起來會像這樣：private static String primaryKey = "elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==";。

建立 CosmosAsyncClient 執行個體

現在請建立 CosmosAsyncClient 的執行個體，其為 Azure Cosmos DB 服務的用戶端表示法。 此用戶端會用於設定和執行針對服務的要求。

1. 在 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;
   

   最可能的情況，是 client、database 與 container 類別都尚未匯入您的 Java 檔案中。 因此我們現在應該來處理這件事。 有些 IDE 可能會讓您依據自己所輸入的程式碼自動匯入相依性，而該功能在這裡會很有用。 在一般情況下，當我們為您提供要貼上的程式碼區塊時，您通常會需要新增一些 import 陳述式才能使其運作。

2. 在類別中建立不含引數，名為 basicOperations 的 private void 方法。

3. 新增下列程式碼，以在 basicOperations 方法中建立 CosmosAsyncClient 執行個體，然後包含程式碼以檢查 Users 資料庫是否存在。

    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. 此時， basicOperations 方法會包含要與 Azure Cosmos DB 互動的程式碼。 然而，在 main 中並不會呼叫此方法，因此應用程式仍會列印 "Hello World"。作為檢查，請在 IDE 中建置並執行 CosmosApp.java，或是使用下列指令碼在終端機中執行該程式：

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

   確認應用程式仍然會將下列輸出記錄到終端機：

   INFO: Hello World.
   

5. 複製下列程式碼，並貼到 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 程式碼。

6. 在 IDE 中建置並執行 CosmosApp.java，或是使用下列指令碼在終端機中執行該程式：

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

   您可能會在終端機中看到大量的記錄訊息，其中有些是由 SDK 自身所產生。 請仔細閱讀並確認應用程式會將下列輸出記錄到終端機：

   INFO: Database and container validation complete
   

在本單元中，您會設定 Azure Cosmos DB Java 應用程式的基礎。 您會設定 Maven 應用程式、建立基本的 "Hello World" 專案，並將其展開，以將專案連線至 Azure Cosmos DB 端點。

1. 我們會提供 Java 應用程式的範本。 將範本存放庫複製到系統

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

2. 開啟 Windows 檔案總管並巡覽至複製的存放庫。 進入 [spring_lab] 子目錄。

   重要

   您在此課程模組中完成的所有工作都會位於 spring_lab 子目錄底下。

3. 此範本包含 Maven pom .xml，其已提取您專案的必要相依性。 開啟此檔案並加以檢查，以找出下列相依性：

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

   此相依性會提取最新版本的 Spring Data Azure Cosmos DB。 您可以關閉此檔案。

將應用程式連線到 Azure Cosmos DB

1. 透過使用您的 IDE 或終端機，開啟此專案。 視您的 IDE 而定，可能會有選項可將 spring 子目錄中的 pom.xml 檔案開啟為專案。 開啟專案之後，請使用檔案總管工具瀏覽至 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 中定義這些環境變數。 在下一個步驟中，您將會找出這些變數應該具有的值。

2. 返回 Azure 入口網站，移至 [金鑰] 窗格，然後複製 Azure Cosmos DB 端點 URI 與主要金鑰。 如在上一個步驟中所述，使用您選擇的方法將 Azure Cosmos DB 端點 URI 與主要金鑰指派到上述變數。

   例如，如果您的 URI 是 https://cosmosacct.documents.azure.com:443/，且您選擇將端點與主要金鑰貼到 application.properties，則 application.properties 中的行看起來將會像這樣：cosmos.uri=https://cosmosacct.documents.azure.com:443/。 如果主要金鑰是 elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==，則透過遵循相同的程序，您的新變數指派看起來會像這樣：cosmos.key=elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==。

設定 Azure Cosmos DB 用戶端

Spring Data Azure Cosmos DB 會於啟動時自動將 Azure Cosmos DB 用戶端具現化。 Azure Cosmos DB 用戶端是 Azure Cosmos DB 服務的用戶端表示，用於針對服務執行要求。 您的程式碼可以搭配從 application.properties 提取的屬性使用一組建立器方法，在將 Azure Cosmos DB 用戶端具現化之前加以設定。

1. 開啟 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 用戶端時將會利用此設定。

2. 在 CosmosSampleConfiguration.java 中，檢查 CosmosSampleConfiguration 類別並找到空的 cosmosClientBuilder 方法：

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

   在啟動時，Spring Data 將會自動呼叫此方法、取得此方法傳回的 CosmosClientBuilder，然後呼叫其 build() 方法；在那個時候，系統會 (在幕後) 根據包含在 CosmosClientBuilder 內的組態設定建立 CosmosAsyncClient 執行個體。 您可以使用此方法來使用建立器方法設定 CosmosClientBuilder。

3. 請注意，我們會使用建構函式插入 (而不是使用 @Autowired) 的欄位插入) 來具現化 properties 變數，並以從組態檔案剖析的值填入其成員變數。 這可確保建立此類別的執行個體時，所有必要的相依性會存在，並有助於未來撰寫測試程式碼。

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

   我們可以使用 properties 來取得 Azure Cosmos DB 的「URI」與「金鑰」並實作 cosmosClientBuilder，如下所示：

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

   此實作會

   1. 從 properties 提取「URI」與「金鑰」
   2. 將其插入 endpoint 與 key 建立器方法
   3. 額外地設定針對 Azure Cosmos DB 服務的網路連線。 (在「直接模式」中，您的用戶端應用程式會直接與後端 Azure Cosmos DB 分割區通訊)。

4. 返回 CosmosSampleConfiguration.java 並找到 getDatabaseName 方法：

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

   將預設的傳回值變更為 "Users"，也就是您資料庫的名稱。 如此一來，當 Spring Data 於啟動時自動連線到 Azure Cosmos DB 時，其將會連線到 Users 資料庫。

5. 瀏覽到 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 {
   

6. 此時，您的 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"。

7. 若 IDE 會提供工具建置及執行 Maven 應用程式：使用 IDE 建置及執行應用程式，並確認應用程式會將 Hello World 記錄到終端機。

8. 如果您使用終端機來建置並執行 Maven 應用程式：使用下列命令來建置 Maven 專案：

   mvn clean package
   

   然後執行：

   mvn spring-boot:run
   

   查看所有輸出，並確認應用程式會將下列輸出記錄到終端：

   INFO: Hello World.
   

在本單元中，您會設定 Azure Cosmos DB Java 應用程式的基礎。 您已自訂 Maven 應用程式，並延伸基本的 "Hello World" 專案以連線至 Azure Cosmos DB 端點。

繼續