將您的 Java 函式連線至 Azure 儲存體

發行項
06/01/2023

Azure Functions 可讓您直接將 Azure 服務和其他資源連線至函式，而不需要自行撰寫整合程式碼。這些繫結同時代表輸入和輸出，會宣告於函式定義內。繫結中的資料會提供給函式作為參數。「觸發程序」是一種特殊的輸入繫結。雖然函式只有一個觸發程序，但可以有多個輸入和輸出繫結。若要深入了解，請參閱 Azure Functions 觸發程序和繫結概念。

本文說明如何整合您在先前的快速入門文章中建立的函式與 Azure 儲存體佇列。您新增至此函式的輸出繫結，會將資料從 HTTP 要求寫入至佇列中的訊息。

大部分的繫結都需要函式用來存取繫結服務的預存連接字串。為了方便進行此連線，您可以使用您以函式應用程式建立的儲存體帳戶。此帳戶的連線已儲存在名為 AzureWebJobsStorage 的應用程式設定中。

必要條件

在開始這篇文章之前，請先完成 Java 快速入門第 1 部分中的步驟。

下載函式應用程式設定

您已經在 Azure 中建立函數應用程式以及必要的儲存體帳戶。此帳戶的連接字串會安全地儲存在 Azure 的應用程式設定中。在本文中，您會將訊息寫入至相同帳戶中的儲存體佇列。在本機執行函式時若要連線至儲存體帳戶，您必須將應用程式設定下載到 local.settings.json 檔案。

從專案的根目錄，執行下列 Azure Functions Core Tools 命令以將設定下載至 local.settings.json，並將 <APP_NAME> 取代為上一篇文章中的函式應用程式名稱：

func azure functionapp fetch-app-settings <APP_NAME>

您可能需要登入您的 Azure 帳戶。

重要

此命令會以 Azure 中函式應用程式的值覆寫任何現有的設定。

local.settings.json 檔案中包含秘密，因此絕不可發行，且應從原始檔控制中排除。

您需要值 AzureWebJobsStorage，這是儲存體帳戶的連接字串。您將使用此連線來確認輸出繫結會如預期般運作。

啟用延伸模組搭售方案

安裝繫結擴充功能最簡單的方式是啟用擴充功能套件組合。當您啟用套件組合時，系統會自動安裝一組預先定義的擴充功能套件。

若要啟用擴充功能套件組合，請開啟 host.json 檔案，並更新其內容以符合下列程式碼：

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.*, 4.0.0)"
    }
}

您現在可以將儲存體輸出繫結新增至您的專案。

新增輸出繫結

在 Java 專案中，繫結會被定義為函式方法上的繫結註釋。系統接著會根據這些註釋自動產生 function.json 檔案。

瀏覽至 src/main/java 底下您的函式程式碼位置，開啟 Function java 專案檔案，然後將下列參數新增至 run 方法定義：

@QueueOutput(name = "msg", queueName = "outqueue", connection = "AzureWebJobsStorage") OutputBinding<String> msg

msg 參數是 OutputBinding<T> 類型，表示字串的集合。這些字串以訊息方式寫入，以在函數完成時輸出繫結。在此情況下，輸出是名為 outqueue 的儲存體佇列。儲存體帳戶的連接字串是由 connection 方法設定。您會傳遞包含儲存體帳戶連接字串的應用程式設定，而非連接字串本身。

run 方法定義現在必須如下列範例所示︰

@FunctionName("HttpTrigger-Java")
public HttpResponseMessage run(
        @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION)  
        HttpRequestMessage<Optional<String>> request, 
        @QueueOutput(name = "msg", queueName = "outqueue", connection = "AzureWebJobsStorage") 
        OutputBinding<String> msg, final ExecutionContext context) {
    ...
}

新增會使用輸出繫結的程式碼

現在，您可以使用新的 msg 參數，從您的函式程式碼寫入輸出繫結。在成功回應之前新增下列一行程式碼，以將 name 的值新增至 msg 輸出繫結。

msg.setValue(name);

當您使用輸出繫結時，無須使用 Azure 儲存體 SDK 程式碼來進行驗證、取得佇列參考或寫入資料。 Functions 執行階段和佇列輸出繫結會為您進行這些工作。

您的 run 方法現在看起來必須如下列範例所示：

public HttpResponseMessage run(
        @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) 
        HttpRequestMessage<Optional<String>> request, 
        @QueueOutput(name = "msg", queueName = "outqueue", 
        connection = "AzureWebJobsStorage") OutputBinding<String> msg, 
        final ExecutionContext context) {
    context.getLogger().info("Java HTTP trigger processed a request.");

    // Parse query parameter
    String query = request.getQueryParameters().get("name");
    String name = request.getBody().orElse(query);

    if (name == null) {
        return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
        .body("Please pass a name on the query string or in the request body").build();
    } else {
        // Write the name to the message queue. 
        msg.setValue(name);

        return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();
    }
}

更新測試

因為原型也會建立一組測試，所以您需要更新這些測試，以處理 run 方法簽章中的新 msg 參數。

瀏覽至 src/test/java 底下的測試程式碼位置，開啟 Function.java 專案檔，並以下列程式碼取代 //Invoke 下的程式碼行：

@SuppressWarnings("unchecked")
final OutputBinding<String> msg = (OutputBinding<String>)mock(OutputBinding.class);
final HttpResponseMessage ret = new Function().run(req, msg, context);

您現在已準備好在本機試用新的輸出繫結。

在本機執行函式

如同以往，使用下列命令在本機建置專案及啟動 Functions 執行階段：

Maven
Gradle (英文)

mvn clean package 
mvn azure-functions:run

gradle jar --info
gradle azureFunctionsRun

注意

由於您已啟用 host.json 中的擴充功能套件組合，因此儲存體繫結擴充功能已在啟動期間下載並安裝，連同其他 Microsoft 繫結擴充功能。

如同以往，在新的終端視窗中使用 cURL 從命令列觸發函式：

curl -w "\n" http://localhost:7071/api/HttpTrigger-Java --data AzureFunctions

這次，輸出繫結也會在您的儲存體帳戶中建立名為 outqueue 的佇列，並新增具有這個相同字串的訊息。

接下來，您可以使用 Azure CLI 來檢視新的佇列，並確認已新增一則訊息。您也可以使用 Microsoft Azure 儲存體總管或在 Azure 入口網站中檢視您的佇列。

設定儲存體帳戶連線

開啟 local.settings.json 檔案並複製 AzureWebJobsStorage 的值，這是儲存體帳戶的連接字串。請使用下列 Bash 命令，將 AZURE_STORAGE_CONNECTION_STRING 環境變數設為此連接字串：

AZURE_STORAGE_CONNECTION_STRING="<STORAGE_CONNECTION_STRING>"

在 AZURE_STORAGE_CONNECTION_STRING 環境變數中設定連接字串時，您將可直接存取您的儲存體帳戶，而不需要每次都提供驗證。

查詢儲存體佇列

您可以使用 az storage queue list 命令檢視您帳戶中的儲存體佇列，如下列範例所示：

az storage queue list --output tsv

此命令的輸出會包含名為 outqueue 的佇列，這是函式執行時所建立的佇列。

接著，請使用 az storage message peek 命令檢視此佇列中的訊息，如下列範例所示：

echo `echo $(az storage message peek --queue-name outqueue -o tsv --query '[].{Message:content}') | base64 --decode`

傳回的字串應該會與您傳送用來測試函式的訊息相同。

注意

上述範例解碼了 base64 傳回的字串。這是因為佇列儲存體繫結會以 base64 字串的形式寫入和讀取自 Azure 儲存體。

重新部署專案

若要更新已發佈的應用程式，請再次執行下列命令：

Maven
Gradle (英文)

mvn azure-functions:deploy

gradle azureFunctionsDeploy

同樣地，您可以使用 cURL 來測試已部署的函式。如同以往，將 POST 要求本文中的 AzureFunctions 值傳遞至 URL，如下列範例所示：

curl -w "\n" https://fabrikam-functions-20190929094703749.azurewebsites.net/api/HttpTrigger-Java?code=zYRohsTwBlZ68YF.... --data AzureFunctions

您可以再次檢查儲存體佇列訊息，以確認輸出繫結會如預期般在佇列中產生新訊息。

清除資源

此集合中的其他快速入門會以本快速入門為基礎。如果您打算繼續進行後續的快速入門或教學課程，請勿清除在此快速入門中建立的資源。如果您不打算繼續，請使用下列命令來刪除本快速入門中建立的所有資源：

az group delete --name myResourceGroup

出現提示時選取 y。

下一步

您已更新 HTTP 觸發的函式，以將資料寫入至儲存體佇列。若要深入了解如何使用 Java 開發 Azure Functions，請參閱 Azure Functions Java 開發人員指南和 Azure Functions 觸發程序和繫結。如需 Python 中完整函式專案的範例，請參閱 Java 函式範例。

接下來，您應為函式應用程式啟用 Application Insights 監視：

啟用 Application Insights 整合

共用方式為