Início Rápido: Criar uma API Web escalonável usando o Azure Functions

Neste guia de início rápido, você usará as ferramentas de linha de comando do Azure Developer para criar uma API Web escalável com pontos de extremidade de função que respondem a solicitações HTTP. Após testar o código localmente, você o implantará em um novo aplicativo de funções sem servidor que você cria e executa em um plano de Consumo Flex no Azure Functions.

O código-fonte do projeto usa o Azure Developer CLI (azd) para simplificar a implantação do seu código no Azure. Esta implantação segue as melhores práticas atuais para implantações seguras e escaláveis do Azure Functions.

Por padrão, o plano de Consumo Flexível segue um modelo de cobrança pague pelo que usar, o que significa que a conclusão deste início rápido gera um pequeno custo de alguns centavos de dólar ou menos na sua conta do Azure.

Prerequisites

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.

• CLI para Desenvolvedores do Azure

• Ferramentas principais do Azure Functions

• SDK .NET 8.0

• Emulador de armazenamento do Azurite

• Kit do Desenvolvedor Java 17
  • Se você usar outra versão com suporte do Java, será necessário atualizar o arquivo pom.xml do projeto.
  • A JAVA_HOME variável de ambiente deve ser definida como o local de instalação da versão correta do JDK (Java Development Kit).
• Apache Maven 3.8.x

• Node.js 20

• PowerShell 7.2

• SDK DO .NET 6.0

• Python 3.11

• Emulador de armazenamento do Azurite

• Uma ferramenta de teste HTTP segura para enviar solicitações com payloads JSON aos ponto de extremidades da sua função. Este artigo usa curl.

Inicializar o projeto

Use o azd init comando para criar um projeto de código local do Azure Functions a partir de um modelo.

1. No seu terminal ou prompt de comando local, execute esse azd init comando em uma pasta vazia:

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

   Esse comando extrai os arquivos de projeto do repositório de modelos e inicializa o projeto na pasta atual. O sinalizador -e define um nome para o ambiente atual. Em azd, o ambiente mantém um contexto de implantação exclusivo para seu aplicativo e você pode definir mais de um. Ele também é utilizado no nome do grupo de recursos que você cria no Azure.

2. Execute esse comando para navegar até a pasta do http aplicativo:

   cd http
   

3. Crie um arquivo chamado local.settings.json na pasta http que contenha esses dados JSON:

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

   Este arquivo é necessário ao executar localmente.

1. No seu terminal ou prompt de comando local, execute esse azd init comando em uma pasta vazia:

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

   Esse comando extrai os arquivos de projeto do repositório de modelos e inicializa o projeto na pasta atual. O sinalizador -e define um nome para o ambiente atual. Em azd, o ambiente mantém um contexto de implantação exclusivo para seu aplicativo e você pode definir mais de um. Ele também é utilizado no nome do grupo de recursos que você cria no Azure.

2. Execute esse comando para navegar até a pasta do http aplicativo:

   cd http
   

3. Crie um arquivo chamado local.settings.json na pasta http que contenha esses dados JSON:

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

   Este arquivo é necessário ao executar localmente.

1. No seu terminal ou prompt de comando local, execute esse azd init comando em uma pasta vazia:

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

   Esse comando extrai os arquivos de projeto do repositório de modelos e inicializa o projeto na pasta raiz. O sinalizador -e define um nome para o ambiente atual. Em azd, o ambiente mantém um contexto de implantação exclusivo para seu aplicativo e você pode definir mais de um. Ele também é utilizado no nome do grupo de recursos que você cria no Azure.

2. Crie um arquivo chamado local.settings.json na pasta raiz que contenha estes dados JSON:

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

   Este arquivo é necessário ao executar localmente.

1. No seu terminal ou prompt de comando local, execute esse azd init comando em uma pasta vazia:

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

   Esse comando extrai os arquivos de projeto do repositório de modelos e inicializa o projeto na pasta raiz. O sinalizador -e define um nome para o ambiente atual. Em azd, o ambiente mantém um contexto de implantação exclusivo para seu aplicativo e você pode definir mais de um. Ele também é utilizado no nome do grupo de recursos que você cria no Azure.

2. Execute esse comando para navegar até a pasta do src aplicativo:

   cd src
   

3. Crie um arquivo chamado local.settings.json na pasta src que contenha esses dados JSON:

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

   Este arquivo é necessário ao executar localmente.

1. No seu terminal ou prompt de comando local, execute esse azd init comando em uma pasta vazia:

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

   Esse comando extrai os arquivos de projeto do repositório de modelos e inicializa o projeto na pasta raiz. O sinalizador -e define um nome para o ambiente atual. Em azd, o ambiente mantém um contexto de implantação exclusivo para seu aplicativo e você pode definir mais de um. O nome do ambiente também é usado no nome do grupo de recursos que você cria no Azure.

2. Crie um arquivo chamado local.settings.json na pasta raiz que contenha estes dados JSON:

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

   Este arquivo é necessário ao executar localmente.

1. No seu terminal ou prompt de comando local, execute esse azd init comando em uma pasta vazia:

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

   Esse comando extrai os arquivos de projeto do repositório de modelos e inicializa o projeto na pasta raiz. O sinalizador -e define um nome para o ambiente atual. Em azd, o ambiente mantém um contexto de implantação exclusivo para seu aplicativo e você pode definir mais de um. O nome do ambiente também é usado no nome do grupo de recursos que você cria no Azure.

2. Crie um arquivo chamado local.settings.json na pasta raiz que contenha estes dados JSON:

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

   Este arquivo é necessário ao executar localmente.

Criar e ativar um ambiente virtual

Na pasta raiz, execute estes comandos para criar e ativar um ambiente virtual chamado .venv:

Linux/macOS

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

Se o Python não instalar o pacote venv na distribuição do Linux, execute o seguinte comando:

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

Executar no seu ambiente local

1. Execute este comando da pasta do seu aplicativo em um terminal ou prompt de comando:

   func start
   

   mvn clean package
   mvn azure-functions:run
   

   npm install
   func start  
   

   npm install
   npm start  
   

   Quando o host do Functions é iniciado na pasta do projeto local, ele grava os pontos de extremidade de URL das funções disparadas por HTTP na saída do terminal.

   Note

   Como a autorização da chave de acesso não é imposta ao ser executada localmente, a URL da função retornada não inclui o valor da chave de acesso e você não precisa dela para chamar sua função.

2. No seu navegador, acesse o ponto de extremidade httpget, que deve ter a seguinte URL:

   http://localhost:7071/api/httpget

3. De um novo terminal ou janela de prompt de comando, execute este comando curl para enviar uma solicitação POST com um payload JSON para o ponto de extremidade 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"
   

   Este comando lê os dados do payload JSON a partir do arquivo de projeto testdata.json. Você pode encontrar exemplos de ambas as solicitações HTTP no arquivo de projeto test.http.

4. Quando terminar, pressione Ctrl+C na janela do terminal para interromper o processo do host func.exe.

5. Execute deactivate para desligar o ambiente virtual.

Examinar o código (opcional)

Você pode revisar o código que define os dois pontos de extremidade da função de gatilho 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
});

Este arquivo function.json define a função httpget:

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

Este arquivo run.ps1 implementa o código da função:

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

Este arquivo function.json define a função httppost:

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

Este arquivo run.ps1 implementa o código da função:

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
        )

Você pode examinar o projeto de modelo completo aqui.

Você pode examinar o projeto de modelo completo aqui.

Você pode examinar o projeto de modelo completo aqui.

Você pode examinar o projeto de modelo completo aqui.

Você pode examinar o projeto de modelo completo aqui.

Você pode examinar o projeto de modelo completo aqui.

Depois de verificar suas funções localmente, é hora de publicá-las no Azure.

Implantar no Azure

Este projeto está configurado para usar o comando azd up para implantar este projeto em um novo aplicativo de funções em um plano de Consumo Flex no Azure.

Tip

O projeto inclui um conjunto de arquivos Bicep (na pasta infra ) que azd utiliza ​​para criar uma implantação segura em um plano de consumo Flex que segue as melhores práticas.

1. Execute este comando para que azd crie os recursos necessários do Azure no Azure e implante seu projeto de código no novo aplicativo de funções:

   azd up
   

   A pasta raiz contém o arquivo de definição azure.yaml necessário para azd.

   Se você ainda não estiver conectado, será solicitado que você se autentique com sua conta do Azure.

2. Quando solicitado, forneça esses parâmetros de implantação obrigatórios:

   Parameter	Description
   Assinatura do Azure	Assinatura na qual seus recursos serão criados.
   Localização do Azure	Região do Azure na qual criar o grupo de recursos que contém os novos recursos do Azure. Somente regiões que atualmente dão suporte para o plano de Consumo Flex são mostradas.
   vnetEnabled	Escolha False. Quando definido como True , a implantação cria seu aplicativo de funções em uma nova rede virtual.

   O azd up comando usa suas respostas a esses prompts com os arquivos de configuração do Bicep para concluir estas tarefas de implantação:

   • Criar e configurar esses recursos do Azure necessários (equivalente a azd provision):

     • plano de Consumo Flex e aplicativo de funções
     • Armazenamento do Microsoft Azure (obrigatório) e Application Insights (recomendado)
     • Políticas de acesso e funções para sua conta
     • Conexões de serviço a serviço usando identidades gerenciadas (em vez de cadeias de conexão armazenadas)
     • (Opção) Rede virtual para executar com segurança o aplicativo de funções e os outros recursos do Azure

   • Empacotar e implantar seu código para o contêiner de implantação (equivalente a azd deploy). O aplicativo é então iniciado e executa no pacote implantado.

   Após o comando ser concluído com sucesso, você verá links para os recursos que criou.

Invocar a função no Azure

Agora você pode invocar os endpoints de função no Azure enviando solicitações HTTP para suas URLs, usando sua ferramenta de teste HTTP ou a partir do navegador (para solicitações GET). Quando suas funções forem executadas no Azure, a autorização por chave de acesso será aplicada e você deverá fornecer uma chave de acesso da função com sua solicitação.

Você pode usar as Ferramentas do Núcleo para obter os endpoints de URL de suas funções em execução no Azure.

1. No seu terminal ou prompt de comando local, execute estes comandos para obter os valores dos ponto de extremidades de 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 
   

   O comando azd env get-value obtém o nome do seu aplicativo de funções do ambiente local. Ao usar a opção --show-keys com func azure functionapp list-functions, o valor de URL de invocação retornado para cada endpoint inclui uma chave de acesso em nível de função.

2. Como antes, use sua ferramenta de teste HTTP para validar essas URLs no seu aplicativo de funções executando no Azure.

Reimplantar seu código

Execute o azd up comando quantas vezes precisar para provisionar seus recursos do Azure e implantar atualizações de código em seu aplicativo de funções.

Note

Os arquivos de código implantados são sempre sobrescritos pelo pacote de implantação mais recente.

Suas respostas iniciais aos prompts azd e quaisquer variáveis de ambiente geradas por azd são armazenadas localmente no seu ambiente nomeado. Use o azd env get-values comando para examinar todas as variáveis em seu ambiente usadas ao criar recursos do Azure.

Limpar os recursos

Quando terminar de trabalhar com seu aplicativo de funções e recursos relacionados, use este comando para excluir o aplicativo de funções e seus recursos relacionados do Azure e evitar incorrer em custos adicionais:

azd down --no-prompt

Note

A opção --no-prompt instrui azd a excluir seu grupo de recursos sem uma confirmação sua.

Este comando não afeta seu projeto de código local.

Conteúdo relacionado

• Cenários do Azure Functions
• Plano de Consumo Flexível
• CLI do Azure Developer CLI
• referência azd
• referência Azure Functions Core Tools
• Codificar e testar o Azure Functions localmente