共用方式為


使用 Azure Functions 和 API 管理整合在 Visual Studio 中建立無伺服器 API

REST API 通常會使用 OpenAPI 定義(先前稱為 Swagger)檔案來描述。 此定義包含有關 API 中的作業,以及應如何為 API 建構要求和回應資料的資訊。

在本教學課程中,您會了解如何:

  • 在 Visual Studio 中建立程式碼專案
  • 安裝 OpenAPI 擴充功能
  • 新增 HTTP 觸發程式端點,其中包含 OpenAPI 定義
  • 使用內建 OpenAPI 功能在本機測試函式 API
  • 將專案發佈至 Azure 中的函式應用程式
  • 啟用 API 管理整合
  • 下載 OpenAPI 定義檔案

您所建立的無伺服器函式提供 API,可讓您判斷風力發電機的緊急修復是否符合成本效益。 由於您在取用層中同時建立函式應用程式和 API 管理 實例,因此完成本教學課程的成本最低。

必要條件

建立程式代碼專案

Visual Studio 中的 Azure Functions 專案範本會建立可發行至 Azure 中函式應用程式的專案。 您也會從支援 OpenAPI 定義檔(先前稱為 Swagger 檔案)產生的範本建立 HTTP 觸發函式。

  1. 在 Visual Studio 功能表中,選取 [檔案] > [新增] > [專案]

  2. 在 [建立新專案] 的搜尋方塊中輸入函式,選擇 [Azure Functions] 範本,然後選取 [下一步]

  3. 在 [設定您的新專案] 中,輸入專案的 [專案名稱] (像是 TurbineRepair),然後選取 [建立]

  4. 針對 [建立新的 Azure Functions 應用程式設定],針對 Functions 背景工作選取下列其中一個選項,其中您選擇的選項取決於您選擇的程式模型:

    .NET 8.0 隔離式 (長期支援):您的 C# 函式會在隔離的背景工作模型中執行,這是建議的。 如需詳細資訊,請參閱隔離的背景 工作模型指南

  5. 針對其餘選項,請使用下表中的值:

    設定 Description
    函式範本 Empty 這會建立沒有觸發程式的專案,這可讓您在稍後新增此專案時,更能控制 HTTP 觸發函式的名稱。
    將 Azurite 用於執行階段儲存體帳戶 (AzureWebJobsStorage) Selected 您可以使用模擬器進行 HTTP 觸發程序函式的本機開發。 因為 Azure 中的函數應用程式需要儲存體帳戶,所以當您將專案發佈至 Azure 時,就會指派或建立一個儲存體帳戶。
    授權等級 Function 在 Azure 中執行時,用戶端必須在存取端點時提供金鑰。 如需詳細資訊,請參閱授權層級
  6. 選取 [建立] 以建立函式專案。

接下來,您會安裝適用於 Azure Functions 的 OpenAPI 擴充功能來更新專案,以啟用應用程式中 API 端點的可探索性。

安裝 OpenAPI 擴充功能

若要安裝 OpenAPI 擴充功能:

  1. 從 [工具] 功能表中,選取 [NuGet 套件管理員]> [套件管理員主控台]

  2. 在控制台中,執行下列 Install-Package 命令來安裝 OpenAPI 擴充功能:

    NuGet\Install-Package Microsoft.Azure.Functions.Worker.Extensions.OpenApi -Version 1.5.1
    

    您可能需要根據您的 .NET 版本來更新 特定版本

現在,您可以新增 HTTP 端點函式。

新增 HTTP 端點函式

在 C# 類別庫中,函式所使用的系結是藉由在程式碼中套用屬性來定義。 若要使用 HTTP 觸發程式建立函式:

  1. 在 [方案總管] 中,於專案節點按一下滑鼠右鍵,然後選取 [新增] > [新增 Azure Function]

  2. 輸入 類別Turbine.cs ,然後選取 [ 新增]。

  3. 選擇 Http 觸發程式範本,將 [授權層級] 設定為 [函式],然後選取 [新增]。 Turbine.cs程式代碼檔案會新增至您的專案,以使用 HTTP 觸發程式定義新的函式端點。

現在,您可以將 HTTP 觸發程式範本程式代碼取代為實作 Turbine 函式端點的程式代碼,以及使用 OpenAPI 來定義端點的屬性。

更新函式程式碼

此函式會使用採用兩個參數的 HTTP 觸發程序:

參數名稱 描述
hours 進行渦輪機修復的估計時間,最多到最接近的整個小時。
capacity 渦輪機的容量 (以千瓦為單位)。

然後,此函式會計算修復的費用,以及渦輪機在 24 小時內的收入。 參數是在查詢字串或 POST 要求的承載中提供。

在Turbine.cs項目檔中,以下列程式代碼取代從 HTTP 觸發程式範本產生的類別內容,視您的進程模型而定:

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Enums;
using Microsoft.Extensions.Logging;
using Microsoft.OpenApi.Models;
using Newtonsoft.Json;
using System.Net;

namespace TurbineRepair
{
    public class Turbine
    {
        const double revenuePerkW = 0.12;
        const double technicianCost = 250;
        const double turbineCost = 100;

        private readonly ILogger<Turbine> _logger;

        public Turbine(ILogger<Turbine> logger)
        {
            _logger = logger;
        }

        [Function("TurbineRepair")]
        [OpenApiOperation(operationId: "Run")]
        [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
        [OpenApiRequestBody("application/json", typeof(RequestBodyModel),
            Description = "JSON request body containing { hours, capacity}")]
        [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(string),
            Description = "The OK response message containing a JSON result.")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] HttpRequest req,
            ILogger log)
        {
            // Get request body data.
            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic? data = JsonConvert.DeserializeObject(requestBody);
            int? capacity = data?.capacity;
            int? hours = data?.hours;

            // Return bad request if capacity or hours are not passed in
            if (capacity == null || hours == null)
            {
                return new BadRequestObjectResult("Please pass capacity and hours in the request body");
            }
            // Formulas to calculate revenue and cost
            double? revenueOpportunity = capacity * revenuePerkW * 24;
            double? costToFix = hours * technicianCost + turbineCost;
            string repairTurbine;

            if (revenueOpportunity > costToFix)
            {
                repairTurbine = "Yes";
            }
            else
            {
                repairTurbine = "No";
            };

            return new OkObjectResult(new
            {
                message = repairTurbine,
                revenueOpportunity = "$" + revenueOpportunity,
                costToFix = "$" + costToFix
            });
        }
        public class RequestBodyModel
        {
            public int Hours { get; set; }
            public int Capacity { get; set; }
        }
    }
}

此函式程式碼會傳回 YesNo 的訊息,指出緊急修復是否符合成本效益。 此外也會傳回渦輪機所代表的收益機會,與修復渦輪機的成本。

在本機執行並驗證 API

當您執行函式時,OpenAPI 端點可讓您輕鬆地使用所產生的頁面在本機試用函式。 您不需要在本機執行時提供函式存取金鑰。

  1. 按 F5 開始專案。 當 Functions 執行階段在本機開始時,輸出中會顯示一組 OpenAPI 和 Swagger 端點,以及函式端點。

  2. 在您的瀏覽器中,開啟 RenderSwaggerUI 端點,其看起來應該像 http://localhost:7071/api/swagger/ui。 頁面會根據您的 OpenAPI 定義進行轉譯。

  3. 選取 [POST]>[立即試用],輸入 hourscapacity的值作為查詢參數,或在 JSON 要求本文中輸入值,然後選取 [執行]

    用於測試 TurbineRepair API 的 Swagger UI

  4. 當您針對 hours 輸入 6 之類的整數值和針對 capacity 輸入 2500 之類的值時,您會收到類似下列範例的 JSON 回應:

    來自 TurbineRepair 函式的回應 JSON 資料。

現在,您有一個函式,可判斷緊急修復是否符合成本效益。 接下來,您會將專案和 API 定義發佈至 Azure。

將專案發佈至 Azure

您的 Azure 訂用帳戶中必須具有函式應用程式,才可以發佈您的專案。 Visual Studio 發佈會在您第一次發佈專案時,建立函式應用程式。 其也可以建立與函式應用程式整合的 API 管理執行個體,以公開 TurbineRepair API。

  1. 在 [方案總管] 中,以滑鼠右鍵按一下專案,選取 [發佈],接著在 [目標] 中選取 [Azure],然後選取 [下一步]

  2. 針對 [特定目標],選擇 [Azure 函式應用程式 (Windows)],以建立在 Windows 上執行的函式應用程式,然後選取 [下一步]

  3. 在 [函式執行個體] 中,選擇 [建立新的 Azure 函式...]

    建立新的函式應用程式執行個體

  4. 使用下表中的指定值建立新的執行個體:

    設定 描述
    名稱 全域唯一的名稱 用以唯一識別新函式應用程式的名稱。 接受此名稱或輸入新的名稱。 有效字元:a-z0-9-
    訂用帳戶 您的訂用帳戶 要使用的 Azure 訂用帳戶。 接受此訂用帳戶,或從下拉式清單中選取一個新的訂用帳戶。
    資源群組 資源群組的名稱 要在其中建立函式應用程式的資源群組。 從下拉式清單中選取現有的資源群組,或選擇 [新增] 來建立新的資源群組。
    方案類型 耗用 當您將專案發佈至在取用方案中執行的函式應用程式時,您只需支付您的函式應用程式執行費用。 其他主控方案會產生較高的成本。
    地點 服務的位置 區域中選擇 位置,此位置應靠近您或靠近函式會存取的其他服務。
    Azure 儲存體 一般用途的儲存體帳戶 Functions 執行階段需要 Azure 儲存體帳戶。 選取 [新增] 以設定一般用途的儲存體帳戶。 您也可以選擇符合儲存體帳戶需求的現有帳戶。

    在 Azure 中使用儲存體建立新的函式應用程式

  5. 選取 [建立],以在 Azure 中建立函數應用程式及其相關資源。 資源的建立狀態會顯示在視窗左下方。

  6. 回到 [函式執行個體],確定已勾選 [從套件檔案執行]。 您的函式應用程式會使用已啟用從套件執行模式的 Zip 部署來部署。 這是函式專案的建議部署方法,因為其可提高效能。

  7. 選取 [下一步],然後在 [API 管理] 頁面中,也要選擇 [+ 建立 API 管理 API]

  8. 使用下表中的值,在 API 管理中建立 API

    設定 Description
    API 名稱 TurbineRepair API 的名稱。
    訂用帳戶名稱 您的訂用帳戶 要使用的 Azure 訂用帳戶。 接受此訂用帳戶,或從下拉式清單中選取一個新的訂用帳戶。
    資源群組 資源群組的名稱 從下拉式清單中選取與函式應用程式相同的資源群組。
    API 管理服務 新增執行個體 選取 [新增] 以在無伺服器層的相同位置中建立新的 API 管理 實例。 選取 [ 確定 ] 以建立實例。

    使用 API 建立 APIM 執行個體

  9. 選取 [建立] 以從函式整合透過 TurbineRepair API 建立 API 管理執行個體。

  10. 選取 [完成 ],然後在發行配置檔建立程式完成之後,選取 [ 關閉]。

  11. 確認 [發佈] 頁面現在顯示 [準備發佈],然後選取 [發佈] 將包含專案檔的套件部署到 Azure 中的新函式應用程式。

    部署完成之後,[發佈] 索引標籤中會顯示 Azure 中函式應用程式的根 URL。

取得函式存取金鑰

  1. 在 [發佈] 索引標籤中,選取 [裝載] 旁的省略符號 (...),然後選取 [在 Azure 入口網站中開啟]。 您建立的函式應用程式會在預設瀏覽器的 Azure 入口網站中開啟。

  2. [概觀] 頁面上的 [函式] 下,選取 >[渦輪機],然後選取 [函式密鑰]。

    取得 TurbineRepair 函式的存取金鑰

  3. 在 [函式金鑰] 底下,選取預設密鑰旁的 [複製到剪貼簿] 圖示。 您現在可以設定您在 API 管理 中複製的金鑰,以便存取函式端點。

設定 API 管理

  1. 在函式應用程式頁面中,展開 [API],然後選取 [API 管理]。

  2. 如果函式應用程式尚未連線到新的 API 管理 實例,請在 [API 管理] 下選取它,選取 [Azure Functions 上的 API>OpenAPI 檔],確定已核取 [匯入函式],然後選取 [連結 API]。 請確定只 選取 [TurbineRepair ] 進行匯入,然後 選取 [選取]。

  3. 選取頁面頂端的 [移至 API 管理],然後在 API 管理 實例中展開 [API]。

  4. [API>所有 API] 底下,選取 [Azure Functions>POST 執行上的 OpenAPI 檔],然後在 [輸入處理] 底下選取 [新增原則>設定查詢參數]。

  5. 在 [新增處理] 下方的 [設定查詢參數] 中,針對 [名稱] 輸入 code,選取 [+值],貼上所複製的函式金鑰,然後選取 [儲存]。 API 管理會在將呼叫傳遞至函式端點時包含函式金鑰。

    提供 API 輸入處理規則的函式認證

現在已設定函式密鑰,您可以呼叫 turbine API 端點,以確認它在 Azure 中裝載時是否正常運作。

確認 Azure 中的 API

  1. 在 API 中,選取 [測試] 索引標籤,然後選取 [POST 執行],在 [要求本文]>[未經處理] 中輸入下列程式碼,然後選取 [傳送]

    {
        "hours": "6",
        "capacity": "2500"
    }
    

    APIM API 中的 OpenAPI 測試頁面

    如同以往,您也可以提供與查詢參數相同的值。

  2. 選取 [傳送],然後檢視 HTTP 回應,以確認從 API 傳回相同的結果。

下載 OpenAPI 定義

如果您的 API 如預期般運作,您可以從 API 管理 下載新裝載 API 的 OpenAPI 定義。

    1. 在 [API] 底下,選取 [Azure Functions 上的 OpenAPI 文件]、選取省略符號 (...),然後選取 [匯出]

    下載 OpenAPI 定義

  1. 選擇 API 匯出的方法,包括各種格式的 OpenAPI 檔案。 您也可以將 API 從 Azure API 管理匯出至 Power Platform

清除資源

在上述步驟中,您已建立資源群組中的 Azure 資源。 如果您預期未來不需要這些資源,則可以藉由刪除資源群組予以刪除。

從 Azure 入口網站功能表或 [首頁] 頁面,選取 [資源群組]。 然後,在 [資源群組] 頁面上,選取您建立的群組。

在 [myResourceGroup] 頁面上,確定所列出的資源是您想要刪除的項目。

選取 [刪除資源群組],在文字方塊中輸入您的群組名稱以便確認,然後選取 [刪除]

下一步

您已使用 Visual Studio 2022 建立可自我記錄的函式,因為 OpenAPI 擴充功能並與 API 管理 整合。 現在可以在入口網站的 API 管理中精修定義。 您也可以深入了解 API 管理