Создание бессерверных API в Visual Studio с помощью функций Azure и интеграции управления API

Статья
08/08/2024

ИНТЕРФЕЙСы REST API часто описываются с помощью определения OpenAPI (ранее известного как Swagger). Данный файл содержит информацию об операциях в API и о том, как должны быть структурированы данные запроса и ответа для API.

В этом руководстве описано следующее:

Создание проекта кода в Visual Studio
Установка расширения OpenAPI
Добавление конечной точки триггера HTTP, которая включает определения OpenAPI
Выполняйте тестирование API-интерфейсов функций локально, используя встроенную функциональность OpenAPI
Публикация проекта в приложении-функции в Azure
Включение интеграции Управление API
Загрузите файл определения OpenAPI

Созданная вами бессерверная функция предоставляет API, который позволяет определить, является ли аварийный ремонт ветряной турбины экономически эффективным. Так как вы создаете приложение-функцию и экземпляр Управление API на уровне потребления, затраты на выполнение этого руководства минимальны.

Необходимые компоненты

Visual Studio 2022. Убедитесь, что вы выбрали рабочую нагрузку Разработки Azure во время установки.
Имея активную подписку Azure, создайте бесплатную учетную запись перед началом работы.

Создание проекта кода

С помощью шаблона проекта Функций Azure в Visual Studio можно создать проект, а затем опубликовать его в приложении-функции в Azure. Вы также создадите функцию, активируемую HTTP, из шаблона, который поддерживает создание файла определения OpenAPI (ранее — Swagger-файла).

В строке меню Visual Studio выберите Файл>Создать>Проект.
В разделе Создать новый проект введите в поле поиска слово функции, выберите шаблон Функции Azure, а затем нажмите кнопку Далее.
В разделе Настроить новый проект введите Название проекта для своего проекта, например TurbineRepair, после чего выберите Создать.
Для параметра создания нового приложения Функции Azure выберите один из следующих вариантов для рабочей роли "Функции", где выбранный вариант зависит от выбранной модели процесса:
- Изолированная рабочая модель
- Внутрипроцессный процесс
.NET 8.0 Isolated (Long Term Support): функции C# выполняются в изолированной рабочей модели, которая рекомендуется. Дополнительные сведения см. в руководстве по изолированной рабочей модели.

Внимание

Поддержка будет завершена для модели в процессе 10 ноября 2026 г. Настоятельно рекомендуется перенести приложения в изолированную рабочую модель для полной поддержки.

.NET 8.0 (долгосрочная поддержка): функции C# выполняются в модели в процессе, которая будет прекращена. Дополнительные сведения см. в руководстве по модели в процессе.

Для остальных параметров используйте значения в следующей таблице:

Параметр	значение	Описание
Function template (Шаблон функции)	Пусто	При добавлении проекта создается проект без триггера, что позволяет более контролировать имя триггерной функции HTTP.
Использование Azurite для учетной записи хранения среды выполнения (AzureWebJobsStorage)	Выбрано	Вы можете использовать эмулятор для локальной разработки функций триггеров HTTP. Поскольку для приложения-функции в Azure требуется учетная запись хранения, она назначается или создается при публикации проекта в Azure.
Уровень авторизации	Function	При работе в Azure клиенты должны предоставить ключ при доступе к конечной точке. Дополнительные сведения см . на уровне авторизации.

Нажмите кнопку "Создать", чтобы создать проект функции.

Затем вы обновите проект, установив расширение OpenAPI для Функции Azure, что позволяет обнаруживать конечные точки API в приложении.

Установка расширения OpenAPI

Чтобы установить расширение OpenAPI, выполните следующие действия.

В меню Сервис последовательно выберите пункты Диспетчер пакетов NuGet>Консоль диспетчера пакетов.
В консоли выполните следующую команду Install-Package , чтобы установить расширение OpenAPI:
- Изолированная рабочая модель
- Модель внутрипроцессного процесса
```
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, установите уровень авторизации в значение Function, а затем нажмите кнопку "Добавить". Файл кода Turbine.cs добавляется в проект, который определяет новую конечную точку функции с триггером HTTP.

Теперь можно заменить код шаблона триггера HTTP кодом, реализующим конечную точку функции Турбины, а также атрибуты, использующие OpenAPI для определения конечной точки.

Обновление кода функции

Функция использует триггер HTTP, который принимает два параметра:

Наименование параметра	Description
hours	Расчетное время ремонта турбины, с точностью до ближайшего часа.
емкость	производительность турбин (в киловаттах).

Затем функция вычисляет, сколько стоит ремонт и какой доход турбина может получить за 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; }
        }
    }
}

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 для запуска проекта. Когда среда выполнения функций запускается локально, в выходных данных отображается набор конечных точек OpenAPI и Swagger вместе с конечной точкой функции.
В окне браузера откройте конечную точку RenderSwaggerUI, которая должна выглядеть как http://localhost:7071/api/swagger/ui. Страница отображается на основе ваших определений OpenAPI.
Выберите POST>Попробовать, введите значения для hours и capacity в качестве параметров запроса или в теле запроса JSON и выберите Выполнить.
При вводе целых чисел, таких как 6 для hours и 2500 для capacity, вы получаете ответ JSON, который выглядит как в следующем примере:

Теперь у вас есть функция, определяющая экономичность аварийного ремонта. Затем вы публикуете свой проект и определения API в Azure.

Публикация проекта в Azure

Перед публикацией проекта убедитесь, что в вашей подписке Azure есть приложение-функция. Публикация Visual Studio создает приложение-функцию при первой публикации проекта. При этом также можно создать экземпляр управления API, который интегрируется с вашим приложением-функцией, чтобы предоставить API TurbineRepair.

В Обозревателе решений щелкните правой кнопкой мыши проект, выберите Опубликовать, для параметра Целевой объект выберите Azure и щелкните Далее.
Для Конкретной цели выберите Приложение-функцию Azure (Windows), чтобы создать приложение-функцию, работающее в Windows, затем нажмите Далее.
В разделе Экземпляр функции выберите + Создать новую функцию Azure....

Создайте новый экземпляр, используя значения, указанные в следующей таблице.

Параметр	значение	Описание
Имя	Глобально уникальное имя	Имя, которое однозначно идентифицирует новое приложение-функцию. Используйте это имя или введите новое. Допустимые символы: `a-z`, `0-9` и `-`.
Подписка	Ваша подписка	Подписка Azure, которую нужно использовать. Используйте эту подписку или выберите новую из раскрывающегося списка.
Группа ресурсов	Имя группы ресурсов	Группа ресурсов, в которой создается приложение-функция. Выберите существующую группу ресурсов из раскрывающегося списка или нажмите Создать, чтобы создать новую.
Тип плана	Потребление	При публикации проекта в приложении-функции, которое работает в плане потребления, вы платите только за выполнение приложения-функции. Другие планы размещения связаны с дополнительными расходами.
Местонахождение	Расположение службы	Выберите расположение в ближайшем к вам регионе или регионе, ближайшем к другим службам, к которым обращаются ваши функции.
Хранилище Azure	Учетная запись хранения общего назначения	Учетная запись хранения Azure — обязательный ресурс для среды выполнения Функций. Выберите Создать, чтобы настроить учетную запись хранения общего назначения. Можно также использовать существующую учетную запись при условии, что она соответствует требованиям учетной записи хранения.

Создание нового приложения-функции в Azure с хранилищем

Нажмите кнопку Создать, чтобы создать приложение-функцию и связанные с ним ресурсы в Azure. Состояние операции создания отображается в окне внизу слева.
На вкладке Экземпляр Функций установите флажок Запустить из файла пакета. Приложение-функция развертывается с помощью Zip Deploy с включенным режимом Run-From-Package (Выполнение из пакета). Данный метод развертывания рекомендуется для вашего проекта функций, поскольку он обеспечивает лучшую производительность.
Выберите Далее и на странице Управление API также выберите + Создать API управления API.

Создайте API в API Management, используя значения, представленные в следующей таблице:

Параметр	значение	Описание
Название API	TurbineRepair	Имя для API.
Имя подписки	Ваша подписка	Подписка Azure, которую нужно использовать. Используйте эту подписку или выберите новую из раскрывающегося списка.
Группа ресурсов	Имя группы ресурсов	В раскрывающемся списке выберите ту же группу ресурсов, что и ваше приложение-функция.
Служба управления API	Новый экземпляр	Выберите "Создать", чтобы создать новый экземпляр Управление API в том же расположении на бессерверном уровне. Нажмите кнопку "ОК ", чтобы создать экземпляр.

Создание экземпляра управления API с помощью API

Выберите Создать, чтобы создать экземпляр управления API с API TurbineRepair из интеграции функций.
Нажмите кнопку "Готово " и после завершения процесса создания профиля публикации нажмите кнопку "Закрыть".
Убедитесь, что страница "Публикация" теперь говорит "Готово к публикации", а затем выберите "Опубликовать ", чтобы развернуть пакет, содержащий файлы проекта в новом приложении-функции в Azure.

После завершения развертывания корневой URL-адрес приложения-функции в Azure отображается на вкладке Опубликовать.

Получите ключ доступа к функциям

На вкладке Опубликовать выберите многоточие (...) рядом с Хостинг и выберите Открыть на портале Azure. Созданное вами приложение-функция открывается на портале Azure в браузере по умолчанию.
В разделе "Функции" на странице "Обзор" выберите "Турбина", а затем выберите >"Ключи функции".
В разделе "Ключи функции" выберите значок копирования в буфер обмена рядом с ключом по умолчанию. Теперь этот ключ можно скопировать в Управление API, чтобы он смог получить доступ к конечной точке функции.

Настройка управления API

На странице приложения-функции разверните API и выберите Управление API.
Если приложение-функция еще не подключено к новому экземпляру Управление API, выберите его в разделе Управление API, выберите api>OpenAPI Document on Функции Azure, убедитесь, что функции импорта проверены и выберите API ссылок. Убедитесь, что для импорта выбрано только TurbineRepair , а затем выберите.
Выберите "Перейти к Управление API" в верхней части страницы и в экземпляре Управление API разверните API.
В разделе "Все API- интерфейсы" выберите "Документ OpenAPI" в Функции Azure> POST Run, а затем в разделе "Входящий процесс" выберите "Добавить параметры запроса набора политик".>>
В разделе Обработка входящих запросов выберите Установить параметры запроса, введите code в поле Имя, выберите + Значение, вставьте скопированную функциональную клавишу и выберите Сохранить. Служба API Management включает функциональную клавишу, когда она передает вызов в конечную точку функции.

Теперь, когда задан ключ функции, можно вызвать turbine конечную точку API, чтобы убедиться, что она работает при размещении в Azure.

Проверка API в Azure

В API выберите вкладку Test, затем POST Run , введите следующий код в Текст запроса>Raw, и выберите Отправить:
```
{
    "hours": "6",
    "capacity": "2500"
}
```
Как и раньше, вы также можете указать те же значения, что и параметры запроса.
Выберите Отправить, после чего просмотрите HTTP-ответ, чтобы убедиться, что API возвращает те же результаты.

Скачивание определения OpenAPI

Если API работает должным образом, можно скачать определение OpenAPI для новых размещенных API из Управление API.

1. В разделе API выберите Документ OpenAPI для Функций Azure, нажмите на многоточие (...) и выберите Экспорт.
Выберите средства экспорта API, включая файлы OpenAPI в различных форматах. Вы также можете экспортировать API из Azure API Management в Power Platform.

Очистка ресурсов

На предыдущем шаге вы создали ресурсы Azure в группе ресурсов. Если вы считаете, что в будущем эти ресурсы вам не понадобятся, их можно удалить, удалив группу ресурсов.

В меню или на странице Главная портала Azure выберите Группы ресурсов. Затем на странице Группы ресурсов выберите созданную вами группу.

На странице myResourceGroup убедитесь, что перечислены те ресурсы, которые нужно удалить.

Выберите Удалить группу ресурсов, введите имя своей группы в текстовое поле для подтверждения, после чего выберите Удалить.

Следующие шаги

Вы использовали Visual Studio 2022 для создания функции, которая самодокументировалась из-за расширения OpenAPI и интегрирована с Управление API. Теперь вы можете уточнить определение в API Management на портале. См. дополнительные сведения о службе "Управление API".

Изменение определения OpenAPI в службе "Управление API"

Поделиться через