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

Статья
06/01/2023

Интерфейсы REST API часто описываются с использованием определения OpenAPI. Данный файл содержит информацию об операциях в API и о том, как должны быть структурированы данные запроса и ответа для API.

В этом руководстве вы узнаете, как:

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

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

Примечание

Интеграция OpenAPI и Управление API, описанная в этой статье, в настоящее время поддерживается только для внутрипроцессных функций библиотеки классов C#. Изолированный рабочий процесс Вместо этого функции библиотеки классов C# и все другие языковые среды выполнения должны использовать azure Управление API интеграции с портала.

Предварительные требования

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

Создание проекта Функций Azure

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

В строке меню Visual Studio выберите Файл>Создать>Проект.
В разделе Создать новый проект введите в поле поиска слово функции, выберите шаблон Функции Azure, а затем нажмите кнопку Далее.
В разделе Настроить новый проект введите Название проекта для своего проекта, например TurbineRepair, после чего выберите Создать.

Для параметров в области Создание нового приложения Функций Azure используйте значения, указанные в таблице ниже.

Параметр	Значение	Описание
Рабочая роль Функций	.NET 6	Это значение создает проект функции, который выполняется внутри процесса в среде выполнения Функции Azure версии 4.x, которая требуется для создания файлов OpenAPI.
Function template (Шаблон функции)	Триггер HTTP с OpenAPI	Данное значение создает функцию, запускаемую HTTP-запросом, с возможностью создания файла определения OpenAPI.
Использование Azurite для учетной записи хранения среды выполнения (AzureWebJobsStorage)	Selected	Вы можете использовать эмулятор для локальной разработки функций триггеров HTTP. Поскольку для приложения-функции в Azure требуется учетная запись хранения, она назначается или создается при публикации проекта в Azure.
Уровень авторизации	Функция	При работе в Azure клиенты должны предоставить ключ при доступе к конечной точке. Дополнительную информацию о ключах и авторизации см. в разделе функциональные клавиши доступа.

Параметр проекта Функций Azure

Выберите Создать, чтобы создать проект функции и функцию триггера HTTP с поддержкой OpenAPI.

Visual Studio создает проект и класс с именем Function1, который содержит шаблонный код для типа функции триггера HTTP. После этого вы замените данный код шаблона функции своим собственным настроенным кодом.

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

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

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

Затем функция вычисляет, сколько стоит ремонт и какой доход турбина может получить за 24 часа. Параметры предоставляются либо в строке запроса, либо в полезных данных запроса POST.

В файле проекта Function1.cs замените содержимое созданного кода библиотеки классов следующим кодом:

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 Turbines
    {
        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 в браузере по умолчанию.
В разделе Функции выберите Функции>TurbineRepair, затем выберите Функциональные клавиши.
В разделе Функциональные клавиши выберите по умолчанию и скопируйте значение. Теперь вы можете установить данный ключ в API Management, чтобы он мог получить доступ к конечной точке функции.

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

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

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

Проверка API в Azure

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

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

Если ваш API работает правильно, можно скачать определение OpenAPI.

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

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

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

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

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

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

Дальнейшие действия

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

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