Краткое руководство. Создание масштабируемого веб-API с помощью Функций Azure

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

Источник проекта использует интерфейс командной строки разработчика Azure (azd), чтобы упростить развертывание кода в Azure. Это развертывание следует текущим рекомендациям по безопасным и масштабируемым Функции Azure развертываниям.

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

Prerequisites

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .

• Интерфейс командной строки разработчика Azure

• Основные инструменты Функций Azure

• Пакет SDK для .NET 8.0

• Эмулятор хранилища Azurite

• Пакет разработчиков Java 17
  • Если вы используете другую поддерживаемую версию Java, необходимо обновить файл pom.xml проекта.
  • Переменная JAVA_HOME среды должна быть задана в расположении установки правильной версии пакета средств разработки Java (JDK).
• Apache Maven 3.8.x

• Node.js 20

• PowerShell 7.2

• Пакет SDK для .NET 6.0

• Python 3.11

• Эмулятор хранилища Azurite

• Безопасное средство тестирования HTTP для отправки запросов с полезными данными JSON в конечные точки функции. Для этой статьи используется curl.

Инициализация проекта

azd init Используйте команду для создания локального проекта кода Функций Azure из шаблона.

1. В локальном терминале или командной строке выполните следующую azd init команду в пустой папке:

   azd init --template functions-quickstart-dotnet-azd -e httpendpoint-dotnet
   

   Эта команда извлекает файлы проекта из репозитория шаблонов и инициализирует проект в текущей папке. Флаг -e задает имя текущей среды. В azd среде поддерживается уникальный контекст развертывания для вашего приложения, и вы можете определить более одного контекста. Он также используется в имени группы ресурсов, создаваемой в Azure.

2. Выполните следующую команду, чтобы перейти к папке http приложения:

   cd http
   

3. Создайте файл с именемlocal.settings.json в папке http , содержащей эти данные JSON:

   {
       "IsEncrypted": false,
       "Values": {
           "AzureWebJobsStorage": "UseDevelopmentStorage=true",
           "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"
       }
   }
   

   Этот файл требуется при локальном запуске.

1. В локальном терминале или командной строке выполните следующую azd init команду в пустой папке:

   azd init --template azure-functions-java-flex-consumption-azd -e httpendpoint-java 
   

   Эта команда извлекает файлы проекта из репозитория шаблонов и инициализирует проект в текущей папке. Флаг -e задает имя текущей среды. В azd среде поддерживается уникальный контекст развертывания для вашего приложения, и вы можете определить более одного контекста. Он также используется в имени группы ресурсов, создаваемой в Azure.

2. Выполните следующую команду, чтобы перейти к папке http приложения:

   cd http
   

3. Создайте файл с именемlocal.settings.json в папке http , содержащей эти данные JSON:

   {
       "IsEncrypted": false,
       "Values": {
           "AzureWebJobsStorage": "UseDevelopmentStorage=true",
           "FUNCTIONS_WORKER_RUNTIME": "java"
       }
   }
   

   Этот файл требуется при локальном запуске.

1. В локальном терминале или командной строке выполните следующую azd init команду в пустой папке:

   azd init --template functions-quickstart-javascript-azd -e httpendpoint-js
   

   Эта команда извлекает файлы проекта из репозитория шаблонов и инициализирует проект в корневой папке. Флаг -e задает имя текущей среды. В azd среде поддерживается уникальный контекст развертывания для вашего приложения, и вы можете определить более одного контекста. Он также используется в имени группы ресурсов, создаваемой в Azure.

2. Создайте файл с именемlocal.settings.json в корневой папке, содержащей эти данные JSON:

   {
       "IsEncrypted": false,
       "Values": {
           "AzureWebJobsStorage": "UseDevelopmentStorage=true",
           "FUNCTIONS_WORKER_RUNTIME": "node"
       }
   }
   

   Этот файл требуется при локальном запуске.

1. В локальном терминале или командной строке выполните следующую azd init команду в пустой папке:

   azd init --template functions-quickstart-powershell-azd -e httpendpoint-ps
   

   Эта команда извлекает файлы проекта из репозитория шаблонов и инициализирует проект в корневой папке. Флаг -e задает имя текущей среды. В azd среде поддерживается уникальный контекст развертывания для вашего приложения, и вы можете определить более одного контекста. Он также используется в имени группы ресурсов, создаваемой в Azure.

2. Выполните следующую команду, чтобы перейти к папке src приложения:

   cd src
   

3. Создайте файл с именемlocal.settings.json в папке src , содержащей эти данные JSON:

   {
       "IsEncrypted": false,
       "Values": {
           "AzureWebJobsStorage": "UseDevelopmentStorage=true",
           "FUNCTIONS_WORKER_RUNTIME": "powershell",
           "FUNCTIONS_WORKER_RUNTIME_VERSION": "7.2"
       }
   }
   

   Этот файл требуется при локальном запуске.

1. В локальном терминале или командной строке выполните следующую azd init команду в пустой папке:

   azd init --template functions-quickstart-typescript-azd -e httpendpoint-ts
   

   Эта команда извлекает файлы проекта из репозитория шаблонов и инициализирует проект в корневой папке. Флаг -e задает имя текущей среды. В azd среде поддерживается уникальный контекст развертывания для вашего приложения, и вы можете определить более одного контекста. Имя среды также используется в имени группы ресурсов, создаваемой в Azure.

2. Создайте файл с именемlocal.settings.json в корневой папке, содержащей эти данные JSON:

   {
       "IsEncrypted": false,
       "Values": {
           "AzureWebJobsStorage": "UseDevelopmentStorage=true",
           "FUNCTIONS_WORKER_RUNTIME": "node"
       }
   }
   

   Этот файл требуется при локальном запуске.

1. В локальном терминале или командной строке выполните следующую azd init команду в пустой папке:

   azd init --template functions-quickstart-python-http-azd -e httpendpoint-py
   

   Эта команда извлекает файлы проекта из репозитория шаблонов и инициализирует проект в корневой папке. Флаг -e задает имя текущей среды. В azd среде поддерживается уникальный контекст развертывания для вашего приложения, и вы можете определить более одного контекста. Имя среды также используется в имени группы ресурсов, создаваемой в Azure.

2. Создайте файл с именемlocal.settings.json в корневой папке, содержащей эти данные JSON:

   {
       "IsEncrypted": false,
       "Values": {
           "AzureWebJobsStorage": "UseDevelopmentStorage=true",
           "FUNCTIONS_WORKER_RUNTIME": "python"
       }
   }
   

   Этот файл требуется при локальном запуске.

Создание и активация виртуальной среды

В корневой папке выполните следующие команды, чтобы создать и активировать виртуальную среду с именем .venv:

Linux/macOS

python3 -m venv .venv
source .venv/bin/activate

Если Python не устанавливает пакет venv в дистрибутиве Linux, выполните следующую команду:

sudo apt-get install python3-venv

Windows (bash)

py -m venv .venv
source .venv/scripts/activate

Windows (Cmd)

py -m venv .venv
.venv\scripts\activate

Запуск в локальной среде

1. Выполните следующую команду из папки приложения в терминале или командной строке:

   func start
   

   mvn clean package
   mvn azure-functions:run
   

   npm install
   func start  
   

   npm install
   npm start  
   

   Когда узел функций запускается в локальной папке проекта, он записывает конечные точки URL-адреса активируемых функций HTTP в выходные данные терминала.

   Note

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

2. В браузере перейдите к конечной точке httpget , которая должна выглядеть следующим образом:

   http://localhost:7071/api/httpget

3. В новом окне терминала или командной строки выполните следующую curl команду, чтобы отправить запрос POST с полезными данными JSON в httppost конечную точку:

   curl -i http://localhost:7071/api/httppost -H "Content-Type: text/json" -d @testdata.json
   

   curl -i http://localhost:7071/api/httppost -H "Content-Type: text/json" -d "@src/functions/testdata.json"
   

   Эта команда считывает полезные данные JSON из testdata.json файла проекта. Примеры обоих HTTP-запросов можно найти в test.http файле проекта.

4. По завершении нажмите клавиши CTRL+C в окне терминала, чтобы остановить func.exe процесс узла.

5. Выполните команду deactivate , чтобы завершить работу виртуальной среды.

Просмотр кода (необязательно)

Вы можете просмотреть код, определяющий две конечные точки функции триггера HTTP:

httpget

       [Function("httpget")]
       public IActionResult Run([HttpTrigger(AuthorizationLevel.Function, "get")]
         HttpRequest req,
         string name)
       {
           var returnValue = string.IsNullOrEmpty(name)
               ? "Hello, World."
               : $"Hello, {name}.";

           _logger.LogInformation($"C# HTTP trigger function processed a request for {returnValue}.");

           return new OkObjectResult(returnValue);
       }

@FunctionName("httpget")
public HttpResponseMessage run(
        @HttpTrigger(
            name = "req",
            methods = {HttpMethod.GET},
            authLevel = AuthorizationLevel.FUNCTION)
            HttpRequestMessage<Optional<String>> request,
        final ExecutionContext context) {
    context.getLogger().info("Java HTTP trigger processed a request.");

    // Parse query parameter
    String name = Optional.ofNullable(request.getQueryParameters().get("name")).orElse("World");

    return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();
}

const { app } = require('@azure/functions');

app.http('httpget', {
    methods: ['GET'],
    authLevel: 'function',
    handler: async (request, context) => {
        context.log(`Http function processed request for url "${request.url}"`);

        const name = request.query.get('name') || await request.text() || 'world';

        return { body: `Hello, ${name}!` };
    }
});

import { app, HttpRequest, HttpResponseInit, InvocationContext } from "@azure/functions";

export async function httpGetFunction(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    context.log(`Http function processed request for url "${request.url}"`);

    const name = request.query.get('name') || await request.text() || 'world';

    return { body: `Hello, ${name}!` };
};

app.http('httpget', {
    methods: ['GET'],
    authLevel: 'function',
    handler: httpGetFunction
});

Этот function.json файл определяет функцию httpget :

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get"
      ],
      "route": "httpget"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    }
  ]
}

Этот run.ps1 файл реализует код функции:

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters
$name = $Request.Query.name

$body = "This HTTP triggered function executed successfully. Pass a name in the query string for a personalized response."

if ($name) {
    $body = "Hello, $name. This HTTP triggered function executed successfully."
}

# Associate values to output bindings by calling 'Push-OutputBinding'.
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [HttpStatusCode]::OK
    Body = $body
})

@app.route(route="httpget", methods=["GET"])
def http_get(req: func.HttpRequest) -> func.HttpResponse:
    name = req.params.get("name", "World")

    logging.info(f"Processing GET request. Name: {name}")

    return func.HttpResponse(f"Hello, {name}!")

httppost

[Function("httppost")]
public IActionResult Run([HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req,
    [FromBody] Person person)
{
    _logger.LogInformation($"C# HTTP POST trigger function processed a request for url {req.Body}");

    if (string.IsNullOrEmpty(person.Name) | string.IsNullOrEmpty(person.Age.ToString()) | person.Age == 0)
    {
        _logger.LogInformation("C# HTTP POST trigger function processed a request with no name/age provided.");
        return new BadRequestObjectResult("Please provide both name and age in the request body.");
    }

    var returnValue = $"Hello, {person.Name}! You are {person.Age} years old.";
    
    _logger.LogInformation($"C# HTTP POST trigger function processed a request for {person.Name} who is {person.Age} years old.");
    return new OkObjectResult(returnValue);
}

@FunctionName("httppost")
public HttpResponseMessage runPost(
        @HttpTrigger(
            name = "req",
            methods = {HttpMethod.POST},
            authLevel = AuthorizationLevel.FUNCTION)
            HttpRequestMessage<Optional<String>> request,
        final ExecutionContext context) {
    context.getLogger().info("Java HTTP trigger processed a POST request.");

    // Parse request body
    String name;
    Integer age;
    try {
        ObjectMapper mapper = new ObjectMapper();
        JsonNode jsonNode = mapper.readTree(request.getBody().orElse("{}"));
        name = Optional.ofNullable(jsonNode.get("name")).map(JsonNode::asText).orElse(null);
        age = Optional.ofNullable(jsonNode.get("age")).map(JsonNode::asInt).orElse(null);
        if (name == null || age == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                    .body("Please provide both name and age in the request body.").build();
        }
    } catch (Exception e) {
        context.getLogger().severe("Error parsing request body: " + e.getMessage());
        return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                .body("Error parsing request body").build();
    }

const { app } = require('@azure/functions');

app.http('httppost', {
    methods: ['POST'],
    authLevel: 'function',
    handler: async (request, context) => {
        context.log(`Http function processed request for url "${request.url}"`);

        try {
            const person = await request.json();
            const { name, age } = person;

            if (!name || !age) {
                return {
                    status: 400,
                    body: 'Please provide both name and age in the request body.'
                };
            }

            return {
                status: 200,
                body: `Hello, ${name}! You are ${age} years old.`
            };
        } catch (error) {
            return {
                status: 400,
                body: 'Invalid request body. Please provide a valid JSON object with name and age.'
            };
        }
    }
});

import { app, HttpRequest, HttpResponseInit, InvocationContext } from "@azure/functions";

interface Person {
    name: string;
    age: number;
}

function isPerson(obj: any): obj is Person {
    return typeof obj === 'object' && obj !== null && 
           typeof obj.name === 'string' && 
           typeof obj.age === 'number';
}

export async function httpPostBodyFunction(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    context.log(`Http function processed request for url "${request.url}"`);

        try {
            const data: any  = await request.json();
    
            if (!isPerson(data)) {
                return {
                    status: 400,
                    body: 'Please provide both name and age in the request body.'
                };
            }

            return {
                status: 200,
                body: `Hello, ${data.name}! You are ${data.age} years old.`
            };
        } catch (error) {
            return {
                status: 400,
                body: 'Invalid request body. Please provide a valid JSON object with name and age.'
            };
        }
};

app.http('httppost', {
    methods: ['POST'],
    authLevel: 'function',
    handler: httpPostBodyFunction
});

Этот function.json файл определяет функцию httppost :

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "post"
      ],
      "route": "httppost"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    }
  ]
}

Этот run.ps1 файл реализует код функции:

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with the body of the request.
$name = $Request.Body.name
$age = $Request.Body.age
$status = [HttpStatusCode]::OK

$body = "This HTTP triggered function executed successfully. Pass a name in the request body for a personalized response."

if ( -not ($name -and $age)){
    $body = "Please provide both 'name' and 'age' in the request body."
    $status = [HttpStatusCode]::BadRequest
}
else {
    <# Action when all if and elseif conditions are false #>
    $body = "Hello, ${name}! You are ${age} years old."
}

# Associate values to output bindings by calling 'Push-OutputBinding'.
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = $status
    Body = $body
})

@app.route(route="httppost", methods=["POST"])
def http_post(req: func.HttpRequest) -> func.HttpResponse:
    try:
        req_body = req.get_json()
        name = req_body.get('name')
        age = req_body.get('age')
        
        logging.info(f"Processing POST request. Name: {name}")

        if name and isinstance(name, str) and age and isinstance(age, int):
            return func.HttpResponse(f"Hello, {name}! You are {age} years old!")
        else:
            return func.HttpResponse(
                "Please provide both 'name' and 'age' in the request body.",
                status_code=400
            )
    except ValueError:
        return func.HttpResponse(
            "Invalid JSON in request body",
            status_code=400
        )

Вы можете просмотреть полный проект шаблона здесь.

Вы можете просмотреть полный проект шаблона здесь.

Вы можете просмотреть полный проект шаблона здесь.

Вы можете просмотреть полный проект шаблона здесь.

Вы можете просмотреть полный проект шаблона здесь.

Вы можете просмотреть полный проект шаблона здесь.

После локальной проверки функций пора опубликовать их в Azure.

Развернуть в Azure

Этот проект настроен для azd up развертывания этого проекта в новом приложении-функции в плане потребления Flex в Azure.

Tip

Проект включает набор файлов Bicep (в папке infra), с помощью которых azd создаётся безопасное развертывание в плане потребления Flex, соответствующем рекомендациям лучших практик.

1. Выполните следующую команду, чтобы azd создать необходимые ресурсы Azure в Azure и развернуть проект кода в новом приложении-функции:

   azd up
   

   Корневая папка содержит файл определения, необходимый azure.yamlazd.

   Если вы еще не вошли, вам будет предложено выполнить проверку подлинности с помощью учетной записи Azure.

2. При появлении запроса укажите следующие необходимые параметры развертывания:

   Parameter	Description
   Подписка Azure	Подписка, в которой создаются ресурсы.
   Расположение Azure	Регион Azure, в котором создается группа ресурсов, содержащая новые ресурсы Azure. Отображаются только регионы, поддерживающие план потребления Flex.
   vnetEnabled	Нажмите кнопку False. Если установить True, развертывание создает функциональное приложение в новой виртуальной сети.

   Команда azd up использует ваши ответы на эти запросы вместе с файлами конфигурации Bicep для выполнения следующих задач развертывания:

   • Создайте и настройте эти необходимые ресурсы Azure (эквивалентно azd provision):

     • План потребления и приложение-функция Flex
     • служба хранилища Azure (обязательно) и Application Insights (рекомендуется)
     • Политики и роли доступа для учетной записи
     • Подключения между службами с помощью управляемых удостоверений (вместо хранимых строка подключения)
     • (Параметр) Виртуальная сеть для безопасного запуска приложения-функции и других ресурсов Azure

   • Упаковайте и разверните код в контейнере развертывания (эквивалентно azd deploy). Затем приложение запускается и запускается в развернутом пакете.

   После успешного завершения команды вы увидите ссылки на созданные ресурсы.

Вызов функции в Azure

Теперь вы можете вызывать конечные точки ваших функций в Azure, посылая HTTP-запросы на их URL-адреса с помощью средства тестирования HTTP или из браузера (для запросов GET). Когда функции выполняются в Azure, авторизация ключа доступа применяется, и вам необходимо предоставить ключ доступа к функциям с запросом.

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

1. В локальном терминале или командной строке выполните следующие команды, чтобы получить значения конечной точки URL-адреса:

   bash

   SET APP_NAME=$(azd env get-value AZURE_FUNCTION_NAME)
   func azure functionapp list-functions $APP_NAME --show-keys
   

   Cmd

   for /f "tokens=*" %i in ('azd env get-value AZURE_FUNCTION_NAME') do set APP_NAME=%i
   func azure functionapp list-functions %APP_NAME% --show-keys 
   

   PowerShell

   $APP_NAME = azd env get-value AZURE_FUNCTION_NAME
   func azure functionapp list-functions $APP_NAME --show-keys
   

   Cmd

   for /f "tokens=*" %i in ('azd env get-value AZURE_FUNCTION_NAME') do set APP_NAME=%i
   func azure functionapp list-functions %APP_NAME% --show-keys 
   

   Команда azd env get-value получает имя приложения-функции из локальной среды. При использовании опции --show-keys с func azure functionapp list-functions, возвращаемое значение URL-адреса вызова: для каждой конечной точки включает ключ доступа на уровне функции.

2. Как и раньше, используйте средство тестирования HTTP для проверки этих URL-адресов в приложении-функции, работающем в Azure.

Повторное развертывание кода

Выполните команду azd up столько раз, сколько потребуется, чтобы развернуть обновления кода в функции-приложении и настроить ресурсы Azure.

Note

Развернутые файлы кода всегда перезаписываются последним пакетом развертывания.

Исходные ответы на azd запросы и любые переменные среды, созданные с помощью azd , хранятся локально в именованной среде. azd env get-values Используйте команду, чтобы просмотреть все переменные в среде, которые вы использовали при создании ресурсов Azure.

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

Когда вы закончите работу с приложением-функцией и связанными ресурсами, используйте эту команду, чтобы удалить приложение-функцию и связанные с ним ресурсы из Azure и избежать дополнительных затрат:

azd down --no-prompt

Note

Параметр --no-prompt указывает azd удалить группу ресурсов без подтверждения.

Эта команда не влияет на локальный проект кода.

Связанный контент

• сценарии Функции Azure
• План потребления Flex
• Azure Developer CLI (azd)
• azd reference
• Справочник по основным средствам Функции Azure
• Как программировать и тестировать функции Azure в локальной среде