使用 Visual Studio Code 將 Azure Functions 連線到 Azure Cosmos DB

文章
04/27/2024

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

此文章說明如何使用 Visual Studio Code 將 Azure Cosmos DB 連線至您在上一篇快速入門文章中建立的函式。您新增至此函式的輸出繫結會將來自 HTTP 要求的資料寫入至儲存在 Azure Cosmos DB 容器中的 JSON 文件。

開始之前，您必須完成快速入門：使用 Visual Studio Code 在 Azure 中建立 C# 函式。如果您已在該文章結束時清除資源，請重新執行這些步驟以在 Azure 中重新建立函式應用程式和相關資源。

開始之前，您必須完成快速入門：使用 Visual Studio Code 在 Azure 中建立 JavaScript 函式。如果您已在該文章結束時清除資源，請重新執行這些步驟以在 Azure 中重新建立函式應用程式和相關資源。

注意

本文目前僅支援 Node.js v3 for Functions。

開始之前，您必須完成快速入門：使用 Visual Studio Code 在 Azure 中建立 Python 函式。如果您已在該文章結束時清除資源，請重新執行這些步驟以在 Azure 中重新建立函式應用程式和相關資源。

設定您的環境

開始之前，請務必安裝適用於 Visual Studio Code 的 Azure 資料庫延伸模組。

建立 Azure Cosmos DB 帳戶

現在，您會建立 Azure Cosmos DB 帳戶作為無伺服器帳戶類型。這個以使用量為基礎的模式使得 Azure Cosmos DB 成為無伺服器工作負載的強大選項。

在 Visual Studio Code 中，選取 [檢視]>[命令選擇區...]，然後在命令選擇區搜尋 Azure Databases: Create Server...

提示中會提供下列資訊：

提示	選取項目
選取 Azure 資料庫伺服器	選擇 [核心] （NoSQL）以建立檔案資料庫，您可以使用 SQL 語法或查詢 Copilot （預覽）將自然語言提示轉換成查詢來查詢。深入了解 Azure Cosmos DB。
帳戶名稱	輸入唯一名稱來識別您的 Azure Cosmos DB 帳戶。帳戶名稱只能使用小寫字母、數字和連字號 (-)，且長度必須介於 3 到 31 個字元之間。
選取容量模型	選取 [無伺服器]，以無伺服器模式建立帳戶。
選取新資源的資源群組	選擇您在先前的文章中建立函式應用程式所在的資源群組。
選取新資源的位置	選取用來裝載 Azure Cosmos DB 帳戶的地理位置。使用最接近您或使用者的位置，讓他們能以最快速度存取您的資料。

佈建新帳戶之後，就會在通知區域中顯示一則訊息。

建立 Azure Cosmos DB 資料庫和容器

在 [活動] 列中選取 Azure 圖示，展開 [資源]>[Azure Cosmos DB]，以滑鼠右鍵按一下 (若使用 macOS 則是 Ctrl+選取) 您的帳戶，然後選取 [建立資料庫...]。
提示中會提供下列資訊：

提示選取項目

資料庫名稱 輸入 my-database。

輸入您的集合的識別碼 輸入 my-container。

輸入集合的分割區金鑰 輸入 /id 作為分割區金鑰。
選取 [確定] 以建立容器和資料庫。

提示	選取項目
資料庫名稱	輸入 `my-database`。
輸入您的集合的識別碼	輸入 `my-container`。
輸入集合的分割區金鑰	輸入 `/id` 作為分割區金鑰。

更新函式應用程式的設定

在先前的快速入門文章中，您已在 Azure 中建立函式應用程式。在本文中，您會更新您的應用程式，以將 JSON 文件寫入您已建立的 Azure Cosmos DB 容器。若要連線到您的 Azure Cosmos DB 帳戶，您必須將其連接字串新增至您的應用程式設定。接著，您會將新設定下載到 local.settings.json 檔案，以便在本機執行時連線到您的 Azure Cosmos DB 帳戶。

在 Visual Studio Code 中，以滑鼠右鍵按一下 (macOS 上為 Ctrl + 選取) 您的新 Azure Cosmos DB 帳戶，然後選取 [複製連接字串]。
按 F1 鍵以開啟命令選擇區，然後搜尋並執行命令 Azure Functions: Add New Setting...。

選擇您在先前的文章中所建立的函式應用程式。提示中會提供下列資訊：

提示	選取項目
輸入新的應用程式設定名稱	輸入 `CosmosDbConnectionSetting`。
輸入 "CosmosDbConnectionSetting" 的值	貼上您複製的 Azure Cosmos DB 帳戶連接字串。您也可以將 Microsoft Entra 身分識別設定為替代方案。

這會在 Azure 中的函式應用程式中建立名為 connection CosmosDbConnectionSetting 的應用程式設定。現在，您可以將此設定下載到您的 local.settings.json 檔案。

再次按 F1 鍵以開啟命令選擇區，然後搜尋並執行命令 Azure Functions: Download Remote Settings...。
選擇您在先前的文章中所建立的函式應用程式。選取 [全部皆是] 來覆寫現有的本機設定。

這會將所有設定從 Azure 下載到您的本機專案，包括新的連接字串設定。下載的設定大部分在本機執行時不會使用。

註冊繫結延伸模組

由於您使用 Azure Cosmos DB 輸出繫結，在執行專案之前，必須先安裝對應的繫結延伸模組。

除了 HTTP 和計時器觸發程序以外，繫結皆會以擴充套件的形式實作。在終端機視窗中執行下列 dotnet add package 命令，將 Azure Cosmos DB 延伸模組套件新增至您的專案。

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.CosmosDB

您的專案已設定為使用擴充功能配套，這會自動安裝一組預先定義的擴充功能套件。

系統會在專案根目錄的 host.json 檔案中啟用擴充套件組合，如下所示：

{
  "version": "2.0",
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "excludedTypes": "Request"
      }
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  },
  "concurrency": {
    "dynamicConcurrencyEnabled": true,
    "snapshotPersistenceEnabled": true
  },
  "extensions": {
    "cosmosDB": {
      "connectionMode": "Gateway"
    }
  }
}

您的專案已設定為使用擴充功能配套，這會自動安裝一組預先定義的擴充功能套件。

系統會在專案根目錄的 host.json 檔案中啟用擴充套件組合，如下所示：

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

現在，您可以將 Azure Cosmos DB 輸出繫結新增至您的專案。

新增輸出繫結

在 C# 類別庫專案中，繫結會被定義為函式方法上的繫結屬性。

開啟 HttpExample.cs 專案檔案，並新增下列類別：

public class MultiResponse
{
    [CosmosDBOutput("my-database", "my-container",
        Connection = "CosmosDbConnectionSetting", CreateIfNotExists = true)]
    public MyDocument Document { get; set; }
    public HttpResponseData HttpResponse { get; set; }
}
public class MyDocument {
    public string id { get; set; }
    public string message { get; set; }
}

MyDocument 類別定義會寫入資料庫的物件。儲存體帳戶的連接字串是由 Connection 屬性設定。在此情況下，您可以省略 Connection，因為您已經正在使用預設的儲存體帳戶。

MultiResponse 類別可讓您寫入 Azure Cosmos DB 中指定的集合，並傳回 HTTP 成功訊息。因為您需要傳回 MultiResponse 物件，您也需要更新方法簽章。

特定屬性會指定容器的名稱及其父資料庫的名稱。 Azure Cosmos DB 帳戶的連接字串是由 CosmosDbConnectionSetting 設定。

系結屬性會直接在函式程式代碼中定義。 Azure Cosmos DB 輸出組態描述 Azure Cosmos DB 輸出繫結所需的欄位。

在此 MultiResponse 案例中，您必須將輸出系結新增 extraOutputs 至函式。

app.http('HttpExample', {
  methods: ['GET', 'POST'],
  extraOutputs: [sendToCosmosDb],
  handler: async (request, context) => {

將下列屬性新增至系結組態：

const sendToCosmosDb = output.cosmosDB({
  databaseName: 'my-database',
  containerName: 'my-container',
  createIfNotExists: false,
  connection: 'CosmosDBConnectionString',
});

繫結屬性是直接定義在 function_app.py 檔案中。您可以使用 cosmos_db_output 裝飾項目來新增 Azure Cosmos DB 輸出繫結：

@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", 
    container_name="my-container", connection="CosmosDbConnectionSetting")

在此程式碼中，arg_name 會識別在您的程式碼中參考的繫結參數，database_name 和 container_name 是繫結寫入其中的資料庫和集合名稱，connection 是其中包含 Azure Cosmos DB 帳戶連接字串的應用程式設定名稱，其在 local.settings.json 檔案的 CosmosDbConnectionSetting 設定中。

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

以下列程式碼取代現有的 Run 方法：

[Function("HttpExample")]
public static MultiResponse Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,
    FunctionContext executionContext)
{
    var logger = executionContext.GetLogger("HttpExample");
    logger.LogInformation("C# HTTP trigger function processed a request.");

    var message = "Welcome to Azure Functions!";

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString(message);

    // Return a response to both HTTP trigger and Azure Cosmos DB output binding.
    return new MultiResponse()
    {
         Document = new MyDocument
        {
            id = System.Guid.NewGuid().ToString(),
            message = message
        },
        HttpResponse = response
    };
}

新增使用 extraInputs 的context輸出系結物件將 JSON 檔案傳送至具名輸出系結函式的程式碼。 sendToCosmosDb 在 return 陳述式前面新增此程式碼。

context.extraOutputs.set(sendToCosmosDb, {
  // create a random ID
  id:
    new Date().toISOString() + Math.random().toString().substring(2, 10),
  name: name,
});

此時，您的函式看起來應如下所示：

const { app, output } = require('@azure/functions');

const sendToCosmosDb = output.cosmosDB({
  databaseName: 'my-database',
  containerName: 'my-container',
  createIfNotExists: false,
  connection: 'CosmosDBConnectionString',
});

app.http('HttpExampleToCosmosDB', {
  methods: ['GET', 'POST'],
  extraOutputs: [sendToCosmosDb],
  handler: async (request, context) => {
    try {
      context.log(`Http function processed request for url "${request.url}"`);

      const name = request.query.get('name') || (await request.text());

      if (!name) {
        return { status: 404, body: 'Missing required data' };
      }

      // Output to Database
      context.extraOutputs.set(sendToCosmosDb, {
        // create a random ID
        id:
          new Date().toISOString() + Math.random().toString().substring(2, 10),
        name: name,
      });

      const responseMessage = name
        ? 'Hello, ' +
          name +
          '. This HTTP triggered function executed successfully.'
        : 'This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response.';

      // Return to HTTP client
      return { body: responseMessage };
    } catch (error) {
      context.log(`Error: ${error}`);
      return { status: 500, body: 'Internal Server Error' };
    }
  },
});

此程式碼現在會傳回 MultiResponse 物件，其包含文件和 HTTP 回應。

更新 HttpExample\function_app.py 以符合下列程式碼。將 outputDocument 參數新增至 if name: 陳述式底下的函式定義和 outputDocument.set()：

import azure.functions as func
import logging

app = func.FunctionApp()

@app.function_name(name="HttpTrigger1")
@app.route(route="hello", auth_level=func.AuthLevel.ANONYMOUS)
@app.queue_output(arg_name="msg", queue_name="outqueue", connection="AzureWebJobsStorage")
@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", container_name="my-container", connection="CosmosDbConnectionSetting")
def test_function(req: func.HttpRequest, msg: func.Out[func.QueueMessage],
    outputDocument: func.Out[func.Document]) -> func.HttpResponse:
     logging.info('Python HTTP trigger function processed a request.')
     logging.info('Python Cosmos DB trigger function processed a request.')
     name = req.params.get('name')
     if not name:
        try:
            req_body = req.get_json()
        except ValueError:
            pass
        else:
            name = req_body.get('name')

     if name:
        outputDocument.set(func.Document.from_dict({"id": name}))
        msg.set(name)
        return func.HttpResponse(f"Hello {name}!")
     else:
        return func.HttpResponse(
                    "Please pass a name on the query string or in the request body",
                    status_code=400
                )

文件 {"id": "name"} 是建立在繫結中指定的資料庫集合中。

在本機執行函式

Visual Studio Code 可與 Azure Functions Core 工具整合，讓您能夠先在本機開發電腦上執行此專案，再發佈至 Azure。如果您尚未在本機安裝 Core Tools，系統會在您第一次執行專案時提示您安裝。

若要呼叫您的函式，請按 F5 以啟動函式應用程式專案。 [終端] 面板會顯示核心工具的輸出。您的應用程式會在 [終端] 面板中啟動。您可以查看在本機所執行 HTTP 觸發函式的 URL 端點。

如果您尚未安裝 Core Tools，請在系統提示安裝時選取 [安裝] 來安裝 Core Tools。
如果在 Windows 上執行時遇到問題，請確定 Visual Studio Code 的預設終端機未設定為 WSL Bash。
執行 Core Tools 時，移至 [Azure: Functions] 區域。在 [函式] 下方，展開 [本機專案]>[函式]。以滑鼠右鍵按一下 (Windows) 或 Ctrl - 點擊 (macOS) HttpExample 函式，並選擇 [立即執行函式...]。
在 [輸入要求本文] 中，按下 Enter 向您的函式傳送要求訊息。
當函式在本機執行並傳回回應時，會在 Visual Studio Code 中引發通知。 [終端機] 面板會顯示函數執行的相關資訊於。
按 Ctrl + C 以停止 Core Tools，並中斷偵錯工具的連線。

在本機執行函式

如先前的文章中所示，按一下 F5 可開啟函式應用程式專案和 Core Tools。
執行 Core Tools 後，移至 [Azure: Functions] 區域。在 [函式] 下方，展開 [本機專案]>[函式]。以滑鼠右鍵按一下 HttpExample 函式 (Mac 上為 Ctrl + 按一下)，並選擇 [立即執行函式...]。
在 [輸入要求本文] 中，會看到 { "name": "Azure" } 的要求訊息本文值。請按 Enter 鍵，將此要求訊息傳送至您的函式。
傳回回應後，按一下 Ctrl + C 以停止 Core Tools。

驗證已建立 JSON 文件

在 Azure 入口網站上，回到您的 Azure Cosmos DB 帳戶，然後選取 [資料總管]。
展開您的資料庫和容器，然後選取 [項目] 以列出在您的容器中建立的文件。
驗證輸出繫結已建立新的 JSON 文件。

重新部署並驗證更新的應用程式

在 Visual Studio Code 中，按 F1 開啟命令選擇區。在命令選擇區中，搜尋並選取 Azure Functions: Deploy to function app...。
選擇您在第一篇文章中所建立的函式應用程式。由於您是要將專案部署至相同的應用程式，請選取 [部署] 來關閉關於覆寫檔案的警告。
部署完成之後，您可以再次使用 [立即執行函式...] 功能來觸發 Azure 中的函式。
再次檢查已在 Azure Cosmos DB 容器中建立文件，以驗證輸出繫結再次產生新的 JSON 文件。

清除資源

在 Azure 中，「資源」是指函式應用程式、函式、儲存體帳戶等等。其會分組為「資源群組」，您可以藉由刪除群組來刪除群組中的所有項目。

您已建立資源來完成這些快速入門。您可能必須支付這些資源，取決於您的帳戶狀態和服務定價。如果您不再需要資源，刪除方式如下：

在 Visual Studio Code 中，按 F1 開啟命令選擇區。在命令選擇區中，搜尋並選取 Azure: Open in portal。
選擇您的函數應用程式，並按下 Enter。函式應用程式頁面會在 Azure 入口網站中開啟。
在 [概觀] 索引標籤中，選取 [資源群組] 旁的具名連結。
在 [資源群組] 分頁上，檢閱所含資源的清單，並確認這些是您想要刪除的項目。
選取 [刪除資源群組]，並遵循指示。

刪除需要幾分鐘的時間。完成時，通知會出現幾秒鐘的時間。您也可以選取分頁頂端的鈴鐺圖示以檢視通知。

下一步

您已更新 HTTP 觸發的函式，以將 JSON 文件寫入 Azure Cosmos DB 容器。現在，您可以深入了解如何使用 Visual Studio Code 來開發 Functions：

分享方式：

使用 Visual Studio Code 將 Azure Functions 連線到 Azure Cosmos DB

設定您的環境

建立 Azure Cosmos DB 帳戶

建立 Azure Cosmos DB 資料庫和容器

更新函式應用程式的設定

註冊繫結延伸模組

新增輸出繫結

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

在本機執行函式

在本機執行函式

驗證已建立 JSON 文件

重新部署並驗證更新的應用程式

清除資源

下一步

意見反映

更多資源