Guia de início rápido: criar uma API Web escalável usando o Azure Functions

Neste quickstart, utilizas as ferramentas de linha de comandos do Azure Developer para construir uma API web escalável com endpoints de funções que respondem a pedidos HTTP. Depois de testar o código localmente, você o implanta em um novo aplicativo de função sem servidor criado em execução em um plano de Consumo Flex no Azure Functions.

A origem do projeto usa a CLI do Desenvolvedor do Azure (azd) para simplificar a implantação de seu código no Azure. Essa implantação segue as práticas recomendadas atuais para implantações seguras e escaláveis do Azure Functions.

Por padrão, o plano Flex Consumption segue um modelo de faturação 'pague pelo que usar', o que significa que completar este início rápido implica um pequeno custo de alguns cêntimos de dólar ou menos na sua Conta Azure.

Prerequisites

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.

• CLI do Azure para Desenvolvedores

• Ferramentas principais do Azure Functions

• SDK do .NET 8.0

• Emulador de armazenamento Azurite

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

• 20Node.js

• PowerShell 7.2

• SDK do .NET 6.0

• Python 3.11

• Emulador de armazenamento Azurite

• Uma ferramenta de teste HTTP segura para enviar solicitações com cargas úteis JSON para seus pontos de extremidade de função. Este artigo usa curlo .

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 terminal local ou prompt de comando, execute este azd init comando em uma pasta vazia:

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

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

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

   cd http
   

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

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

   Esse arquivo é necessário quando executado localmente.

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

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

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

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

   cd http
   

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

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

   Esse arquivo é necessário quando executado localmente.

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

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

   Este comando extrai os arquivos de projeto do repositório de modelos e inicializa o projeto na pasta raiz. O -e sinalizador define um nome para o ambiente atual. No azd, o ambiente mantém um contexto de implantação exclusivo para seu aplicativo e você pode definir mais de um. Ele 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 contém esses dados JSON:

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

   Esse arquivo é necessário quando executado localmente.

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

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

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

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

   cd src
   

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

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

   Esse arquivo é necessário quando executado localmente.

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

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

   Este comando extrai os arquivos de projeto do repositório de modelos e inicializa o projeto na pasta raiz. O -e sinalizador define um nome para o ambiente atual. No 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 crias no Azure.

2. Crie um arquivo chamado local.settings.json na pasta raiz que contém esses dados JSON:

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

   Esse arquivo é necessário quando executado localmente.

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

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

   Este comando extrai os arquivos de projeto do repositório de modelos e inicializa o projeto na pasta raiz. O -e sinalizador define um nome para o ambiente atual. No 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 crias no Azure.

2. Crie um arquivo chamado local.settings.json na pasta raiz que contém esses dados JSON:

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

   Esse arquivo é necessário quando executado 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 sua distribuição Linux, execute o seguinte comando:

sudo apt-get install python3-venv

Janelas (bash)

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

Janelas (cmd)

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

Executar no seu ambiente local

1. Execute este comando a partir da pasta da sua aplicação num terminal ou linha de comandos:

   func start
   

   mvn clean package
   mvn azure-functions:run
   

   npm install
   func start  
   

   npm install
   npm start  
   

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

   Note

   Como a autorização da chave de acesso não é aplicada quando se executa localmente, o URL da função devolvido não inclui o valor da chave de acesso e não precisa dele para chamar a sua função.

2. No seu navegador, vá ao httpget endpoint, que deve parecer este URL:

   http://localhost:7071/api/httpget

3. A partir de um novo terminal ou janela de prompt de comando, execute este curl comando para enviar uma solicitação POST com uma carga JSON para o httppost ponto de extremidade:

   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ê dados de carga JSON do testdata.json arquivo de projeto. Você pode encontrar exemplos de ambas as test.http solicitações HTTP no arquivo de projeto.

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

5. Execute deactivate para desligar o ambiente virtual.

Rever 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 function.json ficheiro define a httpget função:

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

Este run.ps1 arquivo 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 function.json ficheiro define a httppost função:

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

Este run.ps1 arquivo 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 revisar o projeto de modelo completo aqui.

Você pode revisar o projeto de modelo completo aqui.

Você pode revisar o projeto de modelo completo aqui.

Você pode revisar o projeto de modelo completo aqui.

Você pode revisar o projeto de modelo completo aqui.

Você pode revisar o projeto de modelo completo aqui.

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

Implementar no Azure

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

Tip

O projeto inclui um conjunto de ficheiros Bicep (na pasta infra) que azd são usados para criar uma implementação segura num plano de consumo Flex, alinhado com as melhores práticas.

1. Execute este comando para criar azd os recursos necessários do Azure no Azure e implantar seu projeto de código no novo aplicativo de função:

   azd up
   

   A pasta raiz contém o arquivo de azure.yaml definição exigido pelo azd.

   Se já ainda não tiver iniciado sessão, ser-lhe-á solicitado que se autentique com a sua conta Azure.

2. Quando solicitado, forneça estes parâmetros de implantação necessários:

   Parameter	Description
   Subscrição do Azure	Subscrição na qual os seus recursos sã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. Apenas as regiões que atualmente suportam o plano Flex Consumption são mostradas.
   vnetEnabled	Escolha Falso. Quando definido para Verdadeiro , a implementação cria a sua aplicação de funções numa nova rede virtual.

   O azd up comando utiliza as tuas respostas a estes prompts com os ficheiros de configuração do Bicep para completar estas tarefas de implementação:

   • Crie e configure estes recursos necessários do Azure (equivalentes a azd provision):

     • Plano Flex Consumption e aplicação funcional
     • Armazenamento do Azure (obrigatório) e Application Insights (recomendado)
     • Políticas e funções de acesso para a 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 de forma segura tanto a function app como os outros recursos Azure

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

   Depois que o comando for concluído com êxito, você verá links para os recursos criados.

Invoque a função no Azure

Agora podes invocar os endpoints das tuas funções no Azure fazendo pedidos HTTP para os seus URLs usando a tua ferramenta de teste HTTP ou a partir do navegador (para pedidos GET). Quando suas funções são executadas no Azure, a autorização de chave de acesso é imposta e você deve fornecer uma chave de acesso de função com sua solicitação.

Podes usar as Core Tools para obter os endpoints URL das tuas funções a correr no Azure.

1. No terminal local ou prompt de comando, execute estes comandos para obter os valores de ponto de extremidade 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 azd env get-value comando obtém o nome do aplicativo de função do ambiente local. Quando usa a opção --show-keys com func azure functionapp list-functions, o endereço Invoke URL: devolvido para cada endpoint inclui uma chave de acesso ao nível da função.

2. Como antes, use sua ferramenta de teste HTTP para validar essas URLs em seu aplicativo de função em execução no Azure.

Reimplantar seu código

Executa o azd up comando tantas vezes quanto precisares tanto para provisionar os teus recursos Azure como para implementar atualizações de código na tua aplicação de funções.

Note

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

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

Clean up resources (Limpar recursos)

Quando terminar de trabalhar com a sua function app e recursos relacionados, use este comando para eliminar a function app e os seus recursos relacionados do Azure e evitar custos adicionais:

azd down --no-prompt

Note

A --no-prompt opção 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
• CLI do desenvolvedor do Azure (azd)
• Referência AZD
• Referência das Ferramentas Principais do Azure Functions
• Criar código e testar as Funções do Azure localmente