Início rápido: criar uma função Java no Azure da linha de comando

Neste artigo, você usará ferramentas de linha de comando para criar uma função do Java que responde a solicitações HTTP. Após testar o código localmente, implante-o no ambiente sem servidor do Azure Functions.

Se o Maven não for a ferramenta de desenvolvimento que você prefere, confira nossos tutoriais semelhantes para desenvolvedores Java:

A realização deste início rápido gera um pequeno custo de alguns centavos de dólar ou menos em sua conta do Azure.

Configurar o ambiente local

Antes de começar, você deverá ter o seguinte:

Instalação das ferramentas básicas do Azure Functions

A maneira recomendada de instalar o Core Tools depende do sistema operacional do computador de desenvolvimento local.

As etapas a seguir usam um instalador do Windows (MSI) para instalar o Core Tools v4.x. Para obter mais informações sobre outros instaladores baseados em pacote, confira o arquivo leiame do Core Tools.

Baixe e execute o instalador do Core Tools, com base em sua versão do Windows:

Se você usou anteriormente o instalador do Windows (MSI) para instalar o Core Tools no Windows, desinstale a versão antiga em Adicionar ou Remover Programas antes de instalar a versão mais recente.

Criar um projeto de função local

No Azure Functions, um projeto de função é um contêiner para uma ou mais funções individuais que respondem, cada uma, a um gatilho específico. Todas as funções em um projeto compartilham as configurações locais e de hospedagem. Nesta seção, você cria um projeto de função que contém apenas uma função.

  1. Em uma pasta vazia, execute o seguinte comando para gerar o projeto do Functions a partir de um arquétipo Maven.

    mvn archetype:generate -DarchetypeGroupId=com.microsoft.azure -DarchetypeArtifactId=azure-functions-archetype -DjavaVersion=8
    

    Importante

    • Use -DjavaVersion=11 se desejar que as funções sejam executadas no Java 11. Para saber mais, confira Versões Java.
    • A variável de ambiente JAVA_HOME precisa ser definida como a localização de instalação da versão correta do JDK para concluir este artigo.
  2. O Maven solicita os valores necessários para concluir a geração do projeto na implantação.
    Forneça os seguintes valores quando solicitado:

    Prompt Valor Descrição
    groupId com.fabrikam Um valor que identifica exclusivamente o projeto em todos os projetos, seguindo as regras de nomenclatura do pacote para Java.
    artifactId fabrikam-functions Um valor que é o nome do jar, sem um número de versão.
    version 1.0-SNAPSHOT Escolha o valor padrão.
    package com.fabrikam Um valor que é o pacote Java para o código de função gerado. Use o padrão.
  3. Digite Y ou pressione Enter para confirmar.

    O Maven cria os arquivos de projeto em uma nova pasta com o nome artifactId, que, neste exemplo, é fabrikam-functions.

  4. Navegue até a pasta do projeto:

    cd fabrikam-functions
    

    Essa pasta contém vários arquivos do projeto, incluindo arquivos de configuração chamados local.settings.json e host.json. Como local.settings.json pode conter segredos baixados do Azure, o arquivo é excluído do controle do código-fonte por padrão no arquivo .gitignore.

(Opcional) Examinar o conteúdo do arquivo

Se preferir, você poderá ir diretamente para Executar a função localmente e examinar o conteúdo do arquivo mais tarde.

Function.java

O Function.java contém um método run que recebe dados de solicitação na variável request, que é uma HttpRequestMessage decorada com a anotação HttpTrigger, que define o comportamento do gatilho.

package com.fabrikam;

import com.microsoft.azure.functions.ExecutionContext;
import com.microsoft.azure.functions.HttpMethod;
import com.microsoft.azure.functions.HttpRequestMessage;
import com.microsoft.azure.functions.HttpResponseMessage;
import com.microsoft.azure.functions.HttpStatus;
import com.microsoft.azure.functions.annotation.AuthorizationLevel;
import com.microsoft.azure.functions.annotation.FunctionName;
import com.microsoft.azure.functions.annotation.HttpTrigger;

import java.util.Optional;

/**
 * Azure Functions with HTTP Trigger.
 */
public class Function {
    /**
     * This function listens at endpoint "/api/HttpExample". Two ways to invoke it using "curl" command in bash:
     * 1. curl -d "HTTP Body" {your host}/api/HttpExample
     * 2. curl "{your host}/api/HttpExample?name=HTTP%20Query"
     */
    @FunctionName("HttpExample")
    public HttpResponseMessage run(
            @HttpTrigger(
                name = "req",
                methods = {HttpMethod.GET, HttpMethod.POST},
                authLevel = AuthorizationLevel.ANONYMOUS)
                HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {
        context.getLogger().info("Java HTTP trigger processed a request.");

        // Parse query parameter
        final String query = request.getQueryParameters().get("name");
        final String name = request.getBody().orElse(query);

        if (name == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST).body("Please pass a name on the query string or in the request body").build();
        } else {
            return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();
        }
    }
}

A mensagem de resposta é gerada pela API HttpResponseMessage.Builder.

pom.xml

As configurações dos recursos do Azure criados para hospedar seu aplicativo são definidas no elemento configuration do plug-in com uma groupId igual a com.microsoft.azure no arquivo pom.xml gerado. Por exemplo, o elemento de configuração abaixo instrui uma implantação baseada em Maven para criar um aplicativo de funções no grupo de recursos java-functions-group na região westus. O próprio aplicativo de funções é executado no Windows hospedado no plano java-functions-app-service-plan, que, por padrão, é um plano de Consumo sem servidor.

<plugin>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>azure-functions-maven-plugin</artifactId>
    <version>${azure.functions.maven.plugin.version}</version>
    <configuration>
        <!-- function app name -->
        <appName>${functionAppName}</appName>
        <!-- function app resource group -->
        <resourceGroup>java-functions-group</resourceGroup>
        <!-- function app service plan name -->
        <appServicePlanName>java-functions-app-service-plan</appServicePlanName>
        <!-- function app region-->
        <!-- refers https://github.com/microsoft/azure-maven-plugins/wiki/Azure-Functions:-Configuration-Details#supported-regions for all valid values -->
        <region>westus</region>
        <!-- function pricingTier, default to be consumption if not specified -->
        <!-- refers https://github.com/microsoft/azure-maven-plugins/wiki/Azure-Functions:-Configuration-Details#supported-pricing-tiers for all valid values -->
        <!-- <pricingTier></pricingTier> -->
        <!-- Whether to disable application insights, default is false -->
        <!-- refers https://github.com/microsoft/azure-maven-plugins/wiki/Azure-Functions:-Configuration-Details for all valid configurations for application insights-->
        <!-- <disableAppInsights></disableAppInsights> -->
        <runtime>
            <!-- runtime os, could be windows, linux or docker-->
            <os>windows</os>
            <javaVersion>8</javaVersion>
        </runtime>
        <appSettings>
            <property>
                <name>FUNCTIONS_EXTENSION_VERSION</name>
                <value>~4</value>
            </property>
        </appSettings>
    </configuration>
    <executions>
        <execution>
            <id>package-functions</id>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Você pode alterar essas configurações para controlar como os recursos são criados no Azure, por exemplo, alterando runtime.os de windows para linux antes da implantação inicial. Para obter uma lista completa das configurações compatíveis com o plug-in do Maven, confira os detalhes da configuração.

FunctionTest.java

O arquétipo também gera um teste de unidade para sua função. Ao alterar sua função para adicionar associações ou adicionar novas funções ao projeto, você também precisará modificar os testes no arquivo FunctionTest.java.

Executar a função localmente

  1. Execute sua função iniciando o host de runtime do Azure Functions local da pasta LocalFunctionProj:

    mvn clean package
    mvn azure-functions:run
    

    Perto do fim da saída, devem aparecer as seguintes linhas:

     ...
    
     Now listening on: http://0.0.0.0:7071
     Application started. Press Ctrl+C to shut down.
    
     Http Functions:
    
             HttpExample: [GET,POST] http://localhost:7071/api/HttpExample
     ...
    
     

    Observação

    Se HttpExample não aparece conforme mostrado acima, é provável que você tenha iniciado o host fora da pasta raiz do projeto. Nesse caso, use Ctrl+C para parar o host, navegue até a pasta raiz do projeto e execute o comando anterior novamente.

  2. Copie a URL da função HttpExample dessa saída para um navegador e acrescente a cadeia de caracteres de consulta ?name=<YOUR_NAME>, fazendo com que a URL completa seja http://localhost:7071/api/HttpExample?name=Functions. O navegador exibirá uma mensagem que retorna o valor da cadeia de consulta. O terminal em que você iniciou seu projeto também mostra a saída do log conforme você faz solicitações.

  3. Quando você concluir, use Ctrl+C e escolha y para interromper o host de funções.

Implantar o projeto de funções no Azure

Um aplicativo de funções e os recursos relacionados são criados no Azure quando você implanta o projeto de funções pela primeira vez. As configurações dos recursos do Azure criados para hospedar seu aplicativo são definidas no arquivo pom.xml. Neste artigo, você aceitará os padrões.

Dica

Para criar um aplicativo de funções para execução no Linux em vez do Windows, altere o elemento runtime.os no arquivo pom.xml de windows para linux. A execução do Linux em um plano de consumo é compatível com essas regiões. Você não pode ter aplicativos que são executados no Linux e aplicativos que são executados no Windows no mesmo grupo de recursos.

  1. Para fazer a implantação, entre na sua assinatura do Azure usando a CLI do Azure ou o Azure PowerShell.

    az login
    

    O comando az login conecta você à conta do Azure.

  2. Use o comando a seguir para implantar o projeto em um novo aplicativo de funções.

    mvn azure-functions:deploy
    

    Isso cria os seguintes recursos no Azure:

    • Grupo de recursos. Nomeado como java-functions-group.
    • Conta de armazenamento. Necessária para o Functions. O nome é gerado aleatoriamente de acordo com os requisitos de nome da conta de armazenamento.
    • Plano de hospedagem. Hospedagem sem servidor para o aplicativo de funções na região westus. O nome é java-functions-app-service-plan.
    • Aplicativo de funções. Um aplicativo de funções é a unidade de implantação e execução para suas funções. O nome é gerado aleatoriamente com base no artifactId, anexado a um número gerado aleatoriamente.

    A implantação empacota os arquivos de projeto e implanta-os no novo aplicativo de funções usando implantação zip. O código é executado no pacote de implantação no Azure.

Importante

A conta de armazenamento é usada para armazenar dados importantes do aplicativo, às vezes incluindo o próprio código do aplicativo. Você deve limitar o acesso de outros aplicativos e usuários à conta de armazenamento.

Invocar a função no Azure

Como a função usa um gatilho HTTP, você a invoca fazendo uma solicitação HTTP para sua URL no navegador ou usando uma ferramenta como curl.

Copie a URL de Invocação completa mostrada na saída do comando de publicação na barra de endereços de um navegador, acrescentando o parâmetro de consulta ?name=Functions. O navegador deverá exibir uma saída semelhante à que foi exibida quando você executou a função localmente.

The output of the function run on Azure in a browser

Execute o seguinte comando para ver os logs de streaming quase em tempo real:

func azure functionapp logstream <APP_NAME> 

Em uma janela de terminal separada ou no navegador, chame a função remota novamente. Um log detalhado da execução da função no Azure é mostrado no terminal.

Limpar recursos

Se você prosseguir para a próxima etapa e adicionar uma associação de saída da fila do Armazenamento do Azure, mantenha todos os recursos, pois você se baseará no que já fez.

Caso contrário, use o comando a seguir para excluir o grupo de recursos e todos os recursos contidos nele para evitar custos adicionais.

az group delete --name java-functions-group

Próximas etapas