Azure Functions 및 API Management 통합을 사용하여 Visual Studio에서 서버리스 API 만들기

아티클
08/08/2024

REST API는 종종 OpenAPI 정의(이전의 Swagger) 파일을 사용하여 설명합니다. 이 파일에는 API의 작업과 API에 대한 요청 및 응답 데이터를 구성하는 방법에 대한 정보가 포함되어 있습니다.

이 자습서에서는 다음을 하는 방법을 알아볼 수 있습니다.

Visual Studio에서 코드 프로젝트 만들기
OpenAPI 확장 설치
OpenAPI 정의를 포함하는 HTTP 트리거 엔드포인트 추가
기본 제공 OpenAPI 기능을 사용하여 함수 API를 로컬로 테스트
Azure에서 함수 앱에 프로젝트 게시
API Management 통합 사용
OpenAPI 정의 파일 다운로드

사용자가 만든 서버리스 함수는 윈드 터빈의 응급 복구가 비용 효율적인지 여부를 확인할 수 있는 API를 제공합니다. 사용 계층에서 함수 앱과 API Management 인스턴스를 모두 만들므로 이 자습서를 완료하는 데 드는 비용은 최소화됩니다.

필수 조건

Visual Studio 2022. 설치하는 동안 Azure 개발 워크로드를 선택했는지 확인합니다.
활성 Azure 구독, 시작하기 전에 체험 계정을 만드세요.

코드 프로젝트 만들기

Visual Studio의 Azure Functions 프로젝트 템플릿은 Azure에서 함수 앱에 게시할 수 있는 프로젝트를 만듭니다. 또한 OpenAPI 정의 파일(이전의 Swagger 파일) 생성을 지원하는 템플릿에서 HTTP 트리거 함수를 만듭니다.

Visual Studio 메뉴에서 파일>새로 만들기>프로젝트를 차례로 선택합니다.
새 프로젝트 만들기에서 검색 상자에 함수를 입력하고, Azure Functions 템플릿을 선택한 다음, 다음을 선택합니다.
새 프로젝트 구성에서 TurbineRepair와 같이 프로젝트에 대한 프로젝트 이름을 입력한 다음, 만들기를 선택합니다.
새 Azure Functions 애플리케이션 설정 만들기의 경우 Functions 작업자에 대해 다음 옵션 중 하나를 선택합니다. 여기서 선택하는 옵션은 선택한 프로세스 모델에 따라 달라집니다.
- 격리된 작업자 모델
- In Process
.NET 8.0 격리(장기 지원): C# 함수는 격리된 작업자 모델에서 실행되는 것이 좋습니다. 자세한 내용은 격리된 작업자 모델 가이드를 참조하세요.

Important

In Process 모델에 대한 지원은 2026년 11월 10일에 종료됩니다. 전체 지원을 위해 앱을 격리된 작업자 모델로 마이그레이션하는 것이 좋습니다.

.NET 8.0(장기 지원): C# 함수는 사용 중지될 In-process 모델에서 실행됩니다. 자세한 내용은 In-Process 모델 가이드를 참조하세요.

나머지 옵션의 경우 다음 표의 값을 사용합니다.

설정	값	설명
함수 템플릿	Empty	이렇게 하면 트리거 없이 프로젝트가 만들어지며, 나중에 추가할 때 HTTP 트리거 함수의 이름을 더 잘 제어할 수 있습니다.
런타임 스토리지 계정(AzureWebJobsStorage)에 Azurite 사용	Selected	HTTP 트리거 함수의 로컬 개발에 에뮬레이터를 사용할 수 있습니다. Azure의 함수 앱에는 스토리지 계정이 필요하기 때문에 Azure에 프로젝트를 게시할 때 할당되거나 생성됩니다.
권한 부여 수준	Function	Azure에서 실행하는 경우 클라이언트는 엔드포인트에 액세스할 때 키를 제공해야 합니다. 자세한 내용은 권한 부여 수준을 참조하세요.

만들기를 선택하여 함수 프로젝트를 만듭니다.

다음으로, 앱에서 API 엔드포인트를 검색할 수 있도록 하는 Azure Functions용 OpenAPI 확장을 설치하여 프로젝트를 업데이트합니다.

OpenAPI 확장 설치

OpenAPI 확장을 설치하려면 다음을 수행합니다.

도구 메뉴에서 NuGet 패키지 관리자>패키지 관리자 콘솔을 선택합니다.
콘솔에서 다음 Install-Package 명령을 실행하여 OpenAPI 확장을 설치합니다.
- 격리된 작업자 모델
- In Process 모델
```
NuGet\Install-Package Microsoft.Azure.Functions.Worker.Extensions.OpenApi -Version 1.5.1
```
.NET 버전에 따라 특정 버전을 업데이트해야 할 수 있습니다.
```
NuGet\Install-Package Microsoft.Azure.WebJobs.Extensions.OpenApi -Version 1.5.1
```
.NET 버전에 따라 특정 버전을 업데이트해야 할 수 있습니다.

이제 HTTP 엔드포인트 함수를 추가할 수 있습니다.

HTTP 엔드포인트 함수 추가

C# 클래스 라이브러리에서 함수에서 사용하는 바인딩은 코드에 특성을 적용하여 정의됩니다. HTTP 트리거를 사용하여 함수를 만들려면 다음을 수행합니다.

솔루션 탐색기에서 프로젝트 노드를 마우스 오른쪽 단추로 클릭하고 추가>새 Azure 함수를 차례로 선택합니다.
클래스에 대한 Turbine.cs 입력한 다음 추가를 선택합니다.
Http 트리거 템플릿을 선택하고 권한 부여 수준을 함수로 설정한 다음 추가를 선택합니다. http 트리거를 사용하여 새 함수 엔드포인트를 정의하는 Turbine.cs 코드 파일이 프로젝트에 추가됩니다.

이제 HTTP 트리거 템플릿 코드를 OpenAPI를 사용하여 엔드포인트를 정의하는 특성과 함께 터빈 함수 엔드포인트를 구현하는 코드로 바꿀 수 있습니다.

함수 코드 업데이트

이 함수는 두 개의 매개 변수를 사용하는 HTTP 트리거를 사용합니다.

매개 변수 이름	설명
시간	터빈을 복구하는 데 예상되는 시간(최대 1시간)입니다.
capacity	터빈 용량(킬로와트)

그런 다음, 함수는 복구 비용과 터빈이 24시간 내에 가져올 수 있는 수익을 계산합니다. 매개 변수는 쿼리 문자열 또는 POST 요청의 페이로드에서 제공됩니다.

Turbine.cs 프로젝트 파일에서 HTTP 트리거 템플릿에서 생성된 클래스의 내용을 프로세스 모델에 따라 달라지는 다음 코드로 바꿉니다.

격리된 작업자 모델
In Process 모델

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; }
        }
    }
}

using System;
using System.IO;
using System.Net;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
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;

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

        [FunctionName("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 (ActionResult)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 게시에서 함수 앱을 만듭니다. TurbineRepair API를 노출하기 위해 함수 앱과 통합되는 API Management 인스턴스를 만들 수도 있습니다.

솔루션 탐색기에서 프로젝트를 마우스 오른쪽 단추로 클릭하고 게시를 선택하고 대상에서 Azure를 선택한 다음, 다음을 선택합니다.
특정 대상의 경우 Windows에서 실행되는 함수 앱을 만드는 Azure 함수 앱(Windows)을 선택 후, 다음을 선택합니다.
함수 인스턴스에서 + 새 Azure 함수 만들기...를 선택합니다.

다음 표에 지정된 값을 사용하여 새 인스턴스를 만듭니다.

설정	값	설명
이름	전역적으로 고유한 이름	새 함수 앱을 고유하게 식별하는 이름입니다. 이 이름을 수락하거나 새 이름을 입력합니다. 유효한 문자는 `a-z`, `0-9` 및 `-`입니다.
구독	구독	사용할 Azure 구독입니다. 이 구독을 수락하거나 드롭다운 목록에서 새 구독을 선택합니다.
리소스 그룹	리소스 그룹의 이름	함수 앱을 만들 리소스 그룹입니다. 드롭다운 목록에서 기존 리소스 그룹을 선택하거나 새로 만들기를 선택하여 새 리소스 그룹을 만듭니다.
계획 유형	Consumption	프로젝트를 사용량 요금제에서 실행되는 함수 앱에 게시하는 경우 함수 앱의 실행에 대한 비용만 지불합니다. 다른 호스팅 계획에는 비용이 더 많이 듭니다.
위치	서비스의 위치	사용자 또는 함수가 액세스하는 기타 서비스에 가까운 지역의 위치를 선택합니다.
Azure Storage	범용 스토리지 계정	Functions 런타임에는 Azure Storage 계정이 필요합니다. 새로 만들기를 선택하여 범용 스토리지 계정을 구성합니다. 스토리지 계정 요구 사항을 충족하는 기존 계정을 선택할 수도 있습니다.

스토리지를 사용하여 Azure에서 새 함수 앱 만들기

만들기를 선택하여 Azure에서 함수 앱 및 관련된 리소스를 만듭니다. 리소스 만들기 상태는 창의 왼쪽 하단에 표시됩니다.
함수 인스턴스로 돌아가서 패키지 파일에서 실행이 선택되어 있는지 확인합니다. Run-From-Package 모드를 사용하도록 설정된 상태에서 Zip 배포를 사용하여 함수 앱이 배포됩니다. 이 배포 방법은 성능이 향상되므로 함수 프로젝트에 권장됩니다.
다음을 선택하고 API Management 페이지에서 + API Management API 만들기를 선택합니다.

다음 표의 값을 사용하여 API Management에서 API를 만듭니다.

설정	값	설명
API 이름	TurbineRepair	API의 이름입니다.
구독 이름	구독	사용할 Azure 구독입니다. 이 구독을 수락하거나 드롭다운 목록에서 새 구독을 선택합니다.
리소스 그룹	리소스 그룹의 이름	드롭다운 목록에서 함수 앱과 동일한 리소스 그룹을 선택합니다.
API Management 서비스	새 인스턴스	새로 만들기를 선택하여 서버리스 계층의 동일한 위치에 새 API Management 인스턴스를 만듭니다. 확인을 선택하여 인스턴스를 만듭니다.

API를 사용하여 API Management 인스턴스 만들기

함수 통합에서 TurbineRepair API로 API Management 인스턴스를 만들려면 만들기를 선택합니다.
마침을 선택하고 게시 프로필 만들기 프로세스가 완료된 후 닫기를 선택합니다.
게시 페이지에 게시할 준비가 되었는지 확인한 다음 게시를 선택하여 프로젝트 파일이 포함된 패키지를 Azure의 새 함수 앱에 배포합니다.

배포가 완료되면 Azure에서 함수 앱의 루트 URL이 게시 탭에 표시됩니다.

함수 액세스 키 가져오기

게시 탭에서 호스팅 옆에 있는 줄임표(...)를 선택하고 Azure Portal에서 열기를 선택합니다. 만들어진 함수 앱이 기본 브라우저의 Azure Portal에서 열립니다.
개요 페이지의 함수에서 터빈을 선택한> 다음, 함수 키를 선택합니다.
함수 키에서 기본 키 옆에 있는 클립보드로 복사 아이콘을 선택합니다. 이제 함수 엔드포인트에 액세스할 수 있도록 API Management에서 복사한 이 키를 설정할 수 있습니다.

API Management 구성

함수 앱 페이지에서 API를 확장하고 API Management를 선택합니다.
함수 앱이 새 API Management 인스턴스에 아직 연결되지 않은 경우 API Management에서 함수를 선택하고, Azure Functions에서 API>OpenAPI 문서를 선택하고, 함수 가져오기가 선택되어 있는지 확인하고, 링크 API를 선택합니다. Import에 대해 TurbineRepair만 선택되었는지 확인한 다음, 선택합니다.
페이지 맨 위에 있는 API Management로 이동을 선택하고 API Management 인스턴스에서 API를 확장합니다.
API>모든 API에서 Azure Functions>POST Run에서 OpenAPI 문서를 선택한 다음, 인바운드 처리에서 정책>집합 쿼리 매개 변수 추가를 선택합니다.
인바운드 처리 아래의 쿼리 매개 변수 설정에서 이름에 code를 입력하고, +값을 선택하고, 복사한 함수 키를 붙여넣고, 저장을 선택합니다. API Management에서 호출을 함수 엔드포인트에 전달하는 경우 함수 키가 포함됩니다.

이제 함수 키가 설정되었으므로 API 엔드포인트를 turbine 호출하여 Azure에서 호스트할 때 작동하는지 확인할 수 있습니다.

Azure에서 API 확인

API에서 테스트 탭, POST 실행을 차례로 선택하고, 요청 본문>원시에 다음 코드를 입력하고, 보내기를 선택합니다.
```
{
    "hours": "6",
    "capacity": "2500"
}
```
이전과 마찬가지로 쿼리 매개 변수와 동일한 값을 제공할 수도 있습니다.
보내기를 선택한 다음 HTTP 응답을 확인하여 API에서 동일한 결과가 반환되는지 확인합니다.

OpenAPI 정의 다운로드

API가 예상대로 작동하는 경우 API Management에서 호스트된 새 API에 대한 OpenAPI 정의를 다운로드할 수 있습니다.

1. API에서 Azure Functions에 대한 OpenAPI 문서를 선택하고, 줄임표(...)를 선택하고, 내보내기를 선택합니다.
다양한 형식의 OpenAPI 파일을 포함하여 API 내보내기 방법을 선택합니다. Azure API Management에서 Power Platform으로 API를 내보낼 수도 있습니다.

리소스 정리

이전 단계에서는 리소스 그룹에서 Azure 리소스를 만들었습니다. 나중에 이러한 리소스가 필요하지 않은 경우에 리소스 그룹을 삭제하여 삭제할 수 있습니다.

Azure Portal 메뉴 또는 홈 페이지에서 리소스 그룹을 선택합니다. 그런 다음 리소스 그룹 페이지에서 만든 그룹을 선택합니다.

myResourceGroup 페이지에서 나열된 리소스가 삭제하려는 리소스인지 확인합니다.

리소스 그룹 삭제를 선택하고, 텍스트 상자에서 그룹 이름을 입력하여 확인한 다음, 삭제를 선택합니다.

다음 단계

Visual Studio 2022를 사용하여 OpenAPI 확장으로 인해 자체 문서화되고 API Management와 통합된 함수를 만들었습니다. 이제 포털의 API Management에서 정의를 구체화할 수 있습니다. 또한 API Management에 대해 자세히 알아볼 수 있습니다.

API Management에서 OpenAPI 정의 편집

다음을 통해 공유