Início Rápido: criar um aplicativo Java de Durable Functions

Artigo
08/23/2024

Use a extensão Durable Functions, um recurso do Azure Functions, para gravar funções com estado em um ambiente sem servidor. A Durable Functions gerencia o estado, os pontos de verificação e as reinicializações no seu aplicativo.

Neste início rápido, você criará e testará um aplicativo de Durable Functions "Olá, Mundo" em Java.

O aplicativo de Durable Functions mais básico tem três funções:

Função orquestradora: um fluxo de trabalho que orquestra outras funções.
Função de atividade: uma função que é chamada pela função orquestradora, executa trabalho e, opcionalmente, retorna um valor.
Função de cliente: uma função regular no Azure que inicia uma função de orquestrador. Esse exemplo usa uma função acionada por HTTP.

Este início rápido descreve diferentes maneiras de criar esse aplicativo "Olá, Mundo". Use o seletor na parte superior da página para definir sua abordagem preferida.

Pré-requisitos

Para concluir este início rápido, você precisa de:

O Java Developer Kit versão 8 ou posterior instalado.
Apache Maven versão 3.0 ou posterior instalado.
A última versão do Azure Functions Core Tools.

Para o Azure Functions 4.x, o Core Tools versão 4.0.4915 ou posterior é necessário.
Uma ferramenta de teste HTTP que mantém seus dados seguros. Para obter mais informações, confira Ferramentas de teste HTTP.
Uma assinatura do Azure. Para utilizar Durable Functions, tem de ter uma conta de Armazenamento do Azure.

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Adicionar as dependências e os plug-ins necessários ao projeto

Adicione o código a seguir ao arquivo pom.xml:

<properties>
  <azure.functions.maven.plugin.version>1.18.0</azure.functions.maven.plugin.version>
  <azure.functions.java.library.version>3.0.0</azure.functions.java.library.version>
  <durabletask.azure.functions>1.0.0</durabletask.azure.functions>
  <functionAppName>your-unique-app-name</functionAppName>
</properties>

<dependencies>
  <dependency>
    <groupId>com.microsoft.azure.functions</groupId>
    <artifactId>azure-functions-java-library</artifactId>
    <version>${azure.functions.java.library.version}</version>
  </dependency>
  <dependency>
    <groupId>com.microsoft</groupId>
    <artifactId>durabletask-azure-functions</artifactId>
    <version>${durabletask.azure.functions}</version>
  </dependency>
</dependencies>

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.8.1</version>
    </plugin>
    <plugin>
      <groupId>com.microsoft.azure</groupId>
      <artifactId>azure-functions-maven-plugin</artifactId>
      <version>${azure.functions.maven.plugin.version}</version>
      <configuration>
        <appName>${functionAppName}</appName>
        <resourceGroup>java-functions-group</resourceGroup>
        <appServicePlanName>java-functions-app-service-plan</appServicePlanName>
        <region>westus</region>
        <runtime>
          <os>windows</os>
          <javaVersion>11</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>
    <plugin>
      <artifactId>maven-clean-plugin</artifactId>
      <version>3.1.0</version>
    </plugin>
  </plugins>
</build>

Adicionar os arquivos JSON necessários

Adicione um arquivo host.json ao seu diretório de projeto. Ela deve ser parecida com o seguinte exemplo:

{
  "version": "2.0",
  "logging": {
    "logLevel": {
      "DurableTask.AzureStorage": "Warning",
      "DurableTask.Core": "Warning"
    }
  },
  "extensions": {
    "durableTask": {
      "hubName": "JavaTestHub"
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  }
}

Observação

É importante observar que apenas o pacote de extensões do Azure Functions v4 tem o suporte necessário atualmente para as Durable Functions para Java. Não há suporte para as Durable Functions para Java em pacotes de extensões da v3 e anterior. Para obter mais informações sobre os pacotes de extensões, confira a documentação dos pacotes de extensões.

As Durable Functions precisam ter um provedor de armazenamento para armazenar o estado de runtime. Adicione um arquivo local.settings.json ao diretório do projeto para configurar o provedor de armazenamento. Para usar o Armazenamento do Azure como provedor, defina o valor de AzureWebJobsStorage como a cadeia de conexão da sua conta do Armazenamento do Azure:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "<your storage account connection string>",
    "FUNCTIONS_WORKER_RUNTIME": "java"
  }
}

Criar suas funções

O código de exemplo a seguir mostra um exemplo básico de cada tipo de função:

import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;
import java.util.*;

import com.microsoft.durabletask.*;
import com.microsoft.durabletask.azurefunctions.DurableActivityTrigger;
import com.microsoft.durabletask.azurefunctions.DurableClientContext;
import com.microsoft.durabletask.azurefunctions.DurableClientInput;
import com.microsoft.durabletask.azurefunctions.DurableOrchestrationTrigger;

public class DurableFunctionsSample {
    /**
     * This HTTP-triggered function starts the orchestration.
     */
    @FunctionName("StartOrchestration")
    public HttpResponseMessage startOrchestration(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
            final ExecutionContext context) {
        context.getLogger().info("Java HTTP trigger processed a request.");

        DurableTaskClient client = durableContext.getClient();
        String instanceId = client.scheduleNewOrchestrationInstance("Cities");
        context.getLogger().info("Created new Java orchestration with instance ID = " + instanceId);
        return durableContext.createCheckStatusResponse(request, instanceId);
    }

    /**
     * This is the orchestrator function, which can schedule activity functions, create durable timers,
     * or wait for external events in a way that's completely fault-tolerant.
     */
    @FunctionName("Cities")
    public String citiesOrchestrator(
            @DurableOrchestrationTrigger(name = "taskOrchestrationContext") TaskOrchestrationContext ctx) {
        String result = "";
        result += ctx.callActivity("Capitalize", "Tokyo", String.class).await() + ", ";
        result += ctx.callActivity("Capitalize", "London", String.class).await() + ", ";
        result += ctx.callActivity("Capitalize", "Seattle", String.class).await() + ", ";
        result += ctx.callActivity("Capitalize", "Austin", String.class).await();
        return result;
    }

    /**
     * This is the activity function that is invoked by the orchestrator function.
     */
    @FunctionName("Capitalize")
    public String capitalize(@DurableActivityTrigger(name = "name") String name, final ExecutionContext context) {
        context.getLogger().info("Capitalizing: " + name);
        return name.toUpperCase();
    }
}

Criar um projeto local usando o comando do Maven

Execute o seguinte comando para gerar um projeto que contém as funções básicas de um aplicativo de Durable Functions:

mvn archetype:generate -DarchetypeGroupId=com.microsoft.azure -DarchetypeArtifactId=azure-functions-archetype -DarchetypeVersion=1.51 -Dtrigger=durablefunctions

mvn archetype:generate "-DarchetypeGroupId=com.microsoft.azure" "-DarchetypeArtifactId=azure-functions-archetype" "-DarchetypeVersion=1.51" "-Dtrigger=durablefunctions"

mvn archetype:generate "-DarchetypeGroupId=com.microsoft.azure" "-DarchetypeArtifactId=azure-functions-archetype" "-DarchetypeVersion=1.51" "-Dtrigger=durablefunctions"

Nos prompts, forneça as informações a seguir:

Prompt	Ação
groupId	Insira com.function.
artifactId	Insira myDurableFunction.
version	Selecione 1.0-SNAPSHOT.
package	Insira com.function.
Y	Insira Y e selecione Enter para confirmar.

Agora você tem um projeto local que tem as três funções que estão em um aplicativo de Durable Functions básico.

Verifique se com.microsoft:durabletask-azure-functions está definido como uma dependência em seu arquivo pom.xml.

Configurar o provedor de armazenamento de back-end

As Durable Functions precisam ter um provedor de armazenamento para armazenar o estado de runtime. Você pode definir o Armazenamento do Microsoft Azure como o provedor de armazenamento em local.settings.json. Use a cadeia de conexão da sua conta de armazenamento do Azure como o valor para AzureWebJobsStorage como neste exemplo:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "<your storage account connection string>",
    "FUNCTIONS_WORKER_RUNTIME": "java"
  }
}

Criar seu projeto local

No Visual Studio Code, selecione F1 (ou selecione Ctrl/Cmd+Shift+P) para abrir a paleta de comandos. No prompt (>), insira e selecione Azure Functions: Criar projeto.
Selecione Procurar. Na caixa de diálogo Selecionar pasta, vá para uma pasta a ser usada em seu projeto e escolha Selecionar.

Nos prompts, forneça as informações a seguir:

Prompt	Ação
Selecionar um idioma	Selecione Java.
Selecione uma versão do Java	Selecione Java 8 ou posterior. Selecione a versão do Java na qual suas funções são executadas no Azure e uma que você verificou localmente.
Forneça uma ID de grupo	Insira com.function.
Forneça uma ID de artefato	Insira myDurableFunction.
Forneça uma versão	Insira 1.0-SNAPSHOT.
Forneça um nome de pacote	Insira com.function.
Forneça um nome de aplicativo	Insira myDurableFunction.
Selecione a ferramenta de build para o projeto Java	Selecione Maven.
Selecione como deseja abrir o projeto	Selecione Abrir em nova janela.

Agora você tem um projeto que tem uma função HTTP de exemplo. Você pode remover essa função se desejar, pois você adicionará as funções básicas de um aplicativo de Durable Functions na próxima etapa.

Adicionar funções ao projeto

Na paleta de comandos, insira e selecione Azure Functions: Criar Função.
Em Alterar filtro de modelo, selecione Todos.

Nos prompts, forneça as informações a seguir:

Prompt	Ação
Selecione um modelo para a função	Selecione DurableFunctionsOrchestration.
Forneça um nome de pacote	Insira com.function.
Forneça um nome de função	Insira DurableFunctionsOrchestrator.

Na caixa de diálogo, escolha Selecionar conta de armazenamento para configurar uma conta de armazenamento e, em seguida, siga os prompts.

Agora você tem as três funções básicas geradas para um aplicativo de Durable Functions.

Configurar o pom.xml e o host.json

Adicione a seguinte dependência ao seu arquivo pom.xml:

<dependency>
  <groupId>com.microsoft</groupId>
  <artifactId>durabletask-azure-functions</artifactId>
  <version>1.0.0</version>
</dependency>

Adicione a propriedade extensions ao arquivo host.json:

"extensions": { "durableTask": { "hubName": "JavaTestHub" }}

Testar a função localmente

O Azure Functions Core Tools oferece a capacidade de executar um projeto do Azure Functions em seu computador de desenvolvimento local.

Observação

A Durable Functions para Java exige o Azure Functions Core Tools versão 4.0.4915 ou posterior. Você pode ver a versão instalada executando o comando func --version no terminal.

Se você estiver usando o Visual Studio Code, abra uma nova janela de terminal e execute os seguintes comandos para criar o projeto:
```
mvn clean package
```
Em seguida, execute a função durável:
```
mvn azure-functions:run
```
No painel do terminal, copie o ponto de extremidade da URL da sua função acionada por HTTP.

Use uma ferramenta de teste HTTP para enviar uma solicitação HTTP POST ao ponto de extremidade da URL.

A resposta será parecida com o exemplo a seguir:

{
    "id": "d1b33a60-333f-4d6e-9ade-17a7020562a9",
    "purgeHistoryDeleteUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d1b33a60-333f-4d6e-9ade-17a7020562a9?code=ACCupah_QfGKo...",
    "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d1b33a60-333f-4d6e-9ade-17a7020562a9/raiseEvent/{eventName}?code=ACCupah_QfGKo...",
    "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d1b33a60-333f-4d6e-9ade-17a7020562a9?code=ACCupah_QfGKo...",
    "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d1b33a60-333f-4d6e-9ade-17a7020562a9/terminate?reason={text}&code=ACCupah_QfGKo..."
}

A resposta é o resultado inicial da função HTTP. Ele permite que você saiba que a orquestração durável foi iniciada com êxito. Ainda não exibe o resultado final da orquestração. A resposta inclui algumas URLs úteis. Por enquanto, consulte o status da orquestração.

Copie o valor do URL para statusQueryGetUri, cole-o na barra de endereço do seu navegador e execute a solicitação. Como alternativa, você pode continuar a usar a ferramenta de teste HTTP para emitir a solicitação GET.

A solicitação consulta a instância de orquestração do status. Você deve ver que a instância foi concluída e inclui as saídas ou resultados do Durable Functions, como neste exemplo:
```
{
    "name": "Cities",
    "instanceId": "d1b33a60-333f-4d6e-9ade-17a7020562a9",
    "runtimeStatus": "Completed",
    "input": null,
    "customStatus": "",
    "output":"TOKYO, LONDON, SEATTLE, AUSTIN",
    "createdTime": "2022-12-12T05:00:02Z",
    "lastUpdatedTime": "2022-12-12T05:00:06Z"
}
```

Compartilhar via

Início Rápido: criar um aplicativo Java de Durable Functions

Pré-requisitos

Adicionar as dependências e os plug-ins necessários ao projeto

Adicionar os arquivos JSON necessários

Criar suas funções

Criar um projeto local usando o comando do Maven

Configurar o provedor de armazenamento de back-end

Criar seu projeto local

Adicionar funções ao projeto

Configurar o pom.xml e o host.json

Testar a função localmente

Comentários

Recursos adicionais