使用 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 2022。 務必在安裝期間選取 [Azure 開發] 工作負載。
作用中的 Azure 訂用帳戶,請在開始前建立免費帳戶。
建立程式代碼專案
Visual Studio 中的 Azure Functions 專案範本會建立可發行至 Azure 中函式應用程式的專案。 您也會從支援 OpenAPI 定義檔(先前稱為 Swagger 檔案)產生的範本建立 HTTP 觸發函式。
在 Visual Studio 功能表中,選取 [檔案] > [新增] > [專案]。
在 [建立新專案] 的搜尋方塊中輸入函式,選擇 [Azure Functions] 範本,然後選取 [下一步]。
在 [設定您的新專案] 中,輸入專案的 [專案名稱] (像是
TurbineRepair
),然後選取 [建立]。針對 [建立新的 Azure Functions 應用程式設定],針對 Functions 背景工作選取下列其中一個選項,其中您選擇的選項取決於您選擇的程式模型:
.NET 8.0 隔離式 (長期支援):您的 C# 函式會在隔離的背景工作模型中執行,這是建議的。 如需詳細資訊,請參閱隔離的背景 工作模型指南。
針對其餘選項,請使用下表中的值:
設定 值 Description 函式範本 Empty 這會建立沒有觸發程式的專案,這可讓您在稍後新增此專案時,更能控制 HTTP 觸發函式的名稱。 將 Azurite 用於執行階段儲存體帳戶 (AzureWebJobsStorage) Selected 您可以使用模擬器進行 HTTP 觸發程序函式的本機開發。 因為 Azure 中的函數應用程式需要儲存體帳戶,所以當您將專案發佈至 Azure 時,就會指派或建立一個儲存體帳戶。 授權等級 Function 在 Azure 中執行時,用戶端必須在存取端點時提供金鑰。 如需詳細資訊,請參閱授權層級。 選取 [建立] 以建立函式專案。
接下來,您會安裝適用於 Azure Functions 的 OpenAPI 擴充功能來更新專案,以啟用應用程式中 API 端點的可探索性。
安裝 OpenAPI 擴充功能
若要安裝 OpenAPI 擴充功能:
從 [工具] 功能表中,選取 [NuGet 套件管理員]> [套件管理員主控台]。
在控制台中,執行下列 Install-Package 命令來安裝 OpenAPI 擴充功能:
NuGet\Install-Package Microsoft.Azure.Functions.Worker.Extensions.OpenApi -Version 1.5.1
您可能需要根據您的 .NET 版本來更新 特定版本。
現在,您可以新增 HTTP 端點函式。
新增 HTTP 端點函式
在 C# 類別庫中,函式所使用的系結是藉由在程式碼中套用屬性來定義。 若要使用 HTTP 觸發程式建立函式:
在 [方案總管] 中,於專案節點按一下滑鼠右鍵,然後選取 [新增] > [新增 Azure Function]。
輸入 類別Turbine.cs ,然後選取 [ 新增]。
選擇 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; }
}
}
}
此函式程式碼會傳回 Yes
或 No
的訊息,指出緊急修復是否符合成本效益。 此外也會傳回渦輪機所代表的收益機會,與修復渦輪機的成本。
在本機執行並驗證 API
當您執行函式時,OpenAPI 端點可讓您輕鬆地使用所產生的頁面在本機試用函式。 您不需要在本機執行時提供函式存取金鑰。
按 F5 開始專案。 當 Functions 執行階段在本機開始時,輸出中會顯示一組 OpenAPI 和 Swagger 端點,以及函式端點。
在您的瀏覽器中,開啟 RenderSwaggerUI 端點,其看起來應該像
http://localhost:7071/api/swagger/ui
。 頁面會根據您的 OpenAPI 定義進行轉譯。選取 [POST]>[立即試用],輸入
hours
和capacity
的值作為查詢參數,或在 JSON 要求本文中輸入值,然後選取 [執行]。當您針對
hours
輸入 6 之類的整數值和針對capacity
輸入 2500 之類的值時,您會收到類似下列範例的 JSON 回應:
現在,您有一個函式,可判斷緊急修復是否符合成本效益。 接下來,您會將專案和 API 定義發佈至 Azure。
將專案發佈至 Azure
您的 Azure 訂用帳戶中必須具有函式應用程式,才可以發佈您的專案。 Visual Studio 發佈會在您第一次發佈專案時,建立函式應用程式。 其也可以建立與函式應用程式整合的 API 管理執行個體,以公開 TurbineRepair API。
在 [方案總管] 中,以滑鼠右鍵按一下專案,選取 [發佈],接著在 [目標] 中選取 [Azure],然後選取 [下一步]。
針對 [特定目標],選擇 [Azure 函式應用程式 (Windows)],以建立在 Windows 上執行的函式應用程式,然後選取 [下一步]。
在 [函式執行個體] 中,選擇 [建立新的 Azure 函式...]。
使用下表中的指定值建立新的執行個體:
設定 值 描述 名稱 全域唯一的名稱 用以唯一識別新函式應用程式的名稱。 接受此名稱或輸入新的名稱。 有效字元: a-z
、0-9
和-
。訂用帳戶 您的訂用帳戶 要使用的 Azure 訂用帳戶。 接受此訂用帳戶,或從下拉式清單中選取一個新的訂用帳戶。 資源群組 資源群組的名稱 要在其中建立函式應用程式的資源群組。 從下拉式清單中選取現有的資源群組,或選擇 [新增] 來建立新的資源群組。 方案類型 耗用 當您將專案發佈至在取用方案中執行的函式應用程式時,您只需支付您的函式應用程式執行費用。 其他主控方案會產生較高的成本。 地點 服務的位置 在區域中選擇 位置,此位置應靠近您或靠近函式會存取的其他服務。 Azure 儲存體 一般用途的儲存體帳戶 Functions 執行階段需要 Azure 儲存體帳戶。 選取 [新增] 以設定一般用途的儲存體帳戶。 您也可以選擇符合儲存體帳戶需求的現有帳戶。 選取 [建立],以在 Azure 中建立函數應用程式及其相關資源。 資源的建立狀態會顯示在視窗左下方。
回到 [函式執行個體],確定已勾選 [從套件檔案執行]。 您的函式應用程式會使用已啟用從套件執行模式的 Zip 部署來部署。 這是函式專案的建議部署方法,因為其可提高效能。
選取 [下一步],然後在 [API 管理] 頁面中,也要選擇 [+ 建立 API 管理 API]。
使用下表中的值,在 API 管理中建立 API:
設定 值 Description API 名稱 TurbineRepair API 的名稱。 訂用帳戶名稱 您的訂用帳戶 要使用的 Azure 訂用帳戶。 接受此訂用帳戶,或從下拉式清單中選取一個新的訂用帳戶。 資源群組 資源群組的名稱 從下拉式清單中選取與函式應用程式相同的資源群組。 API 管理服務 新增執行個體 選取 [新增] 以在無伺服器層的相同位置中建立新的 API 管理 實例。 選取 [ 確定 ] 以建立實例。 選取 [建立] 以從函式整合透過 TurbineRepair API 建立 API 管理執行個體。
選取 [完成 ],然後在發行配置檔建立程式完成之後,選取 [ 關閉]。
確認 [發佈] 頁面現在顯示 [準備發佈],然後選取 [發佈] 將包含專案檔的套件部署到 Azure 中的新函式應用程式。
部署完成之後,[發佈] 索引標籤中會顯示 Azure 中函式應用程式的根 URL。
取得函式存取金鑰
在 [發佈] 索引標籤中,選取 [裝載] 旁的省略符號 (...),然後選取 [在 Azure 入口網站中開啟]。 您建立的函式應用程式會在預設瀏覽器的 Azure 入口網站中開啟。
在 [概觀] 頁面上的 [函式] 下,選取 >[渦輪機],然後選取 [函式密鑰]。
在 [函式金鑰] 底下,選取預設密鑰旁的 [複製到剪貼簿] 圖示。 您現在可以設定您在 API 管理 中複製的金鑰,以便存取函式端點。
設定 API 管理
在函式應用程式頁面中,展開 [API],然後選取 [API 管理]。
如果函式應用程式尚未連線到新的 API 管理 實例,請在 [API 管理] 下選取它,選取 [Azure Functions 上的 API>OpenAPI 檔],確定已核取 [匯入函式],然後選取 [連結 API]。 請確定只 選取 [TurbineRepair ] 進行匯入,然後 選取 [選取]。
選取頁面頂端的 [移至 API 管理],然後在 API 管理 實例中展開 [API]。
在 [API>所有 API] 底下,選取 [Azure Functions>POST 執行上的 OpenAPI 檔],然後在 [輸入處理] 底下選取 [新增原則>設定查詢參數]。
在 [新增處理] 下方的 [設定查詢參數] 中,針對 [名稱] 輸入
code
,選取 [+值],貼上所複製的函式金鑰,然後選取 [儲存]。 API 管理會在將呼叫傳遞至函式端點時包含函式金鑰。
現在已設定函式密鑰,您可以呼叫 turbine
API 端點,以確認它在 Azure 中裝載時是否正常運作。
確認 Azure 中的 API
在 API 中,選取 [測試] 索引標籤,然後選取 [POST 執行],在 [要求本文]>[未經處理] 中輸入下列程式碼,然後選取 [傳送]:
{ "hours": "6", "capacity": "2500" }
如同以往,您也可以提供與查詢參數相同的值。
選取 [傳送],然後檢視 HTTP 回應,以確認從 API 傳回相同的結果。
下載 OpenAPI 定義
如果您的 API 如預期般運作,您可以從 API 管理 下載新裝載 API 的 OpenAPI 定義。
-
- 在 [API] 底下,選取 [Azure Functions 上的 OpenAPI 文件]、選取省略符號 (...),然後選取 [匯出]。
選擇 API 匯出的方法,包括各種格式的 OpenAPI 檔案。 您也可以將 API 從 Azure API 管理匯出至 Power Platform。
清除資源
在上述步驟中,您已建立資源群組中的 Azure 資源。 如果您預期未來不需要這些資源,則可以藉由刪除資源群組予以刪除。
從 Azure 入口網站功能表或 [首頁] 頁面,選取 [資源群組]。 然後,在 [資源群組] 頁面上,選取您建立的群組。
在 [myResourceGroup] 頁面上,確定所列出的資源是您想要刪除的項目。
選取 [刪除資源群組],在文字方塊中輸入您的群組名稱以便確認,然後選取 [刪除]。
下一步
您已使用 Visual Studio 2022 建立可自我記錄的函式,因為 OpenAPI 擴充功能並與 API 管理 整合。 現在可以在入口網站的 API 管理中精修定義。 您也可以深入了解 API 管理。