快速入門：使用 Azure 應用程式設定建立 Java Quarkus 應用程式

在本快速入門中，您會將 Azure 應用程式設定併入 Java Quarkus 應用程式，以集中儲存和管理應用程式設定，與程式碼分開。

先決條件

• 具有有效訂閱的 Azure 帳戶。 免費創建一個。
• Azure CLI 2.68.0 或更新版本。
• 應用程式組態存放區。 如需詳細資訊，請參閱 快速入門：建立 Azure App Configuration 存放區。
• Java 開發套件 （JDK） 版本 17。
• Apache Maven 3.9.8 版或更高版本。

新增索引鍵值組

將下列索引鍵值組新增至 App Configuration 存放區。 如需如何使用 Azure CLI 將索引鍵/值組新增至存放區的詳細資訊，請參閱 建立索引鍵/值。

Key	價值觀
/application/config.message	您好

創建一個 Quarkus 應用程序

在本節中，您將使用 Azure 應用程式組態擴充功能和 REST 擴充功能建立 Quarkus 應用程式。 REST 延伸模組可用來建立 REST 服務，以從 App Configuration 存放區傳回組態值。 如需詳細資訊，請參閱 Quarkus Azure 應用程式設定。

使用以下命令創建 Quarkus 應用程序：

mvn io.quarkus.platform:quarkus-maven-plugin:create \
    -DprojectGroupId=com.example \
    -DprojectArtifactId=quarkus-app-configuration \
    -Dextensions='io.quarkiverse.azureservices:quarkus-azure-app-configuration,rest' \
    -DjavaVersion="17"

該應用程式是在名為 quarkus-app-configuration 的新目錄中建立的。 以下是該應用程序的結構：

quarkus-app-configuration
├── src
│   ├── main/java/com/example
│   │   ├── GreetingResource.java
│   └── test/java/com/example
│       └── GreetingResourceTest.java
├── pom.xml

pom.xml 檔案包含應用程式的相依性，包括 Azure 應用程式設定延伸模組和 REST 延伸模組。 下列 XML 是典型範例：

<dependency>
    <groupId>io.quarkiverse.azureservices</groupId>
    <artifactId>quarkus-azure-app-configuration</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest</artifactId>
</dependency>

GreetingResource.java檔案包含 REST 服務。 您可以修改此檔案，以稍後從 App Configuration 存放區傳回組態值。

GreetingResourceTest.java檔案包含 REST 服務的單元測試。 您可以修改此檔案，以驗證從 REST 服務傳回的值是否等於 App Configuration 存放區中的值。

連線至應用程式組態存放區

現在您已經有了 App Configuration 商店和具有 Azure App Configuration 擴展的 Quarkus 應用程序，您可以將應用程序連接到商店。

撰寫應用程式程序代碼

使用下列步驟設定應用程式：

1. 開啟src/main/java/com/example目錄下的GreetingResource.java文件，並將內容替換為以下程式碼：

   package com.example;
   
   import jakarta.ws.rs.GET;
   import jakarta.ws.rs.Path;
   import jakarta.ws.rs.Produces;
   import jakarta.ws.rs.core.MediaType;
   
   import org.eclipse.microprofile.config.inject.ConfigProperty;
   
   @Path("/hello")
   public class GreetingResource {
   
       @ConfigProperty(name = "/application/config.message")
       String value;
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return value;
       }
   }
   

   修改後的程式碼會使用 MicroProfile Config @ConfigProperty 註解，將 App Configuration 存放區中的索引鍵 /application/config.message 值注入到 value 欄位，並在 REST 服務中傳回該值。

2. 開啟自動產生的單元測試，該單元測試位於 src/test/java/com/example 目錄的 GreetingResourceTest.java 檔案中。 以下列程式代碼取代檔案的內容：

   package com.example;
   
   import io.quarkus.test.junit.QuarkusTest;
   import org.junit.jupiter.api.Test;
   
   import javax.inject.Inject;
   
   import static io.restassured.RestAssured.given;
   import static org.hamcrest.CoreMatchers.is;
   
   @QuarkusTest
   public class GreetingResourceTest {
       @Test
       public void testHelloEndpoint() {
           given()
               .when().get("/hello")
               .then()
               .statusCode(200)
               .body(is("Hello"));
       }
   }
   

   修改後的程式碼會斷言從 REST 服務傳回的值等於 App Configuration 存放區中的值。 此值為Hello，適用於您先前新增的金鑰/application/config.message。

這些對應用程式的程式碼變更都是必要的。 在執行應用程式之前，您必須設定驗證和與應用程式設定存放區的連線。

設定 App Configuration 存放區的驗證

除了使用存取金鑰進行身份驗證外，Quarkus Azure 應用程式組態擴充功能還支援使用 Azure 身分識別用戶端程式庫使用 DefaultAzureCredential Microsoft Entra ID 進行身份驗證。

您可以在本快速入門中使用 Microsoft Entra ID 進行驗證。 如需詳細資訊，請參閱DefaultAzureCredential適用於 Java 的 Azure 身分識別用戶端程式庫。

使用下列步驟設定 App Configuration 存放區的驗證：

1. 使用下列命令設定環境變數，將 <...> 預留位置替換為您先前建立的值：

   export RESOURCE_GROUP_NAME="<resource-group-name>"
   export APP_CONFIG_NAME="<app-configuration-store-name>"
   

2. 使用下列命令將角色指派 App Configuration Data Reader 給登入的使用者：

   # Retrieve the app configuration resource ID
   export APP_CONFIGURATION_RESOURCE_ID=$(az appconfig show \
       --resource-group $RESOURCE_GROUP_NAME \
       --name "${APP_CONFIG_NAME}" \
       --query 'id' \
       --output tsv)
   # Assign the "App Configuration Data Reader" role to the current signed-in identity
   az role assignment create \
       --assignee $(az ad signed-in-user show --query 'id' --output tsv) \
       --role "App Configuration Data Reader" \
       --scope $APP_CONFIGURATION_RESOURCE_ID
   

3. 將 App Configuration 存放區的端點匯出至使用下列命令命名的環境變數 QUARKUS_AZURE_APP_CONFIGURATION_ENDPOINT ：

   export QUARKUS_AZURE_APP_CONFIGURATION_ENDPOINT=$(az appconfig show \
       --resource-group "${RESOURCE_GROUP_NAME}" \
       --name "${APP_CONFIG_NAME}" \
       --query endpoint \
       --output tsv)
   

   備註

   環境變數 QUARKUS_AZURE_APP_CONFIGURATION_ENDPOINT 的值用於 Quarkus Azure App Configuration 擴充功能的設定屬性 quarkus.azure.app.configuration.endpoint 中，以設定與 Azure App Configuration 存放區的連線。 或者，您可以在 src/main/resources 目錄的 application.properties 檔案中直接設定此內容，如下列範例所示。 請務必以您的實際價值替換 <your-app-configuration-store-endpoint> 。

   quarkus.azure.app.configuration.endpoint=<your-app-configuration-store-endpoint>
   

於本機建置並執行應用程式

使用下列步驟在本機建置和執行應用程式：

1. 使用下列命令在 JVM 模式下建置和執行應用程式：

   # Build, test and package the app
   mvn clean package
   
   # Run the app
   java -jar ./target/quarkus-app/quarkus-run.jar
   

   備註

   或者，您可以在原生模式下執行範例。 若要使用原生模式，您必須安裝 GraalVM，或使用建置器映像檔來建置原生執行檔。 如需詳細資訊，請參閱 建置原生可執行檔。 本快速入門使用 Docker 作為容器執行階段來建置 Linux 原生可執行檔。 如果您尚未安裝 Docker，可以從 Docker 網站下載。

   使用下列命令在 Linux 環境中建置和執行原生可執行檔：

   mvn package -Dnative -Dquarkus.native.container-build
   ./target/storage-blob-1.0.0-SNAPSHOT-runner
   

2. 使用下列命令測試您的應用程式：

   curl localhost:8080/hello
   

   您應該會在輸出中看到 Hello，因為 Hello 是您在 App Configuration 存放區中添加的鍵 /application/config.message 的值。

3. 按 控制+C 停止應用程式。

清理資源

若要避免 Azure 費用，您應該清除不需要的資源。 當您不再需要 App Configuration 存放區時，請使用下列命令來移除資源群組和所有相關資源：

az group delete --name $RESOURCE_GROUP_NAME --yes --no-wait

另請參閱

• Quarkus Azure App Configuration
• 使用 OpenID Connect 使用 Microsoft Entra ID 保護 Quarkus 應用程式
• 在 Azure Container Apps 上使用 Quarkus 部署 Java 應用程式
• 在 Azure Kubernetes Service 叢集上使用 Quarkus 部署 Java 應用程式
• 在 Azure Functions 上使用 Quarkus 部署無伺服器 Java 應用程式