Avvio rapido: Creare un'app Java Durable Functions

Usare Durable Functions, una funzionalità di Funzioni di Azure, per scrivere funzioni con stato in un ambiente serverless. Durable Functions gestisce lo stato, i checkpoint e i riavvii nell'applicazione.

In questa guida di avvio rapido si crea e si testa un'app Durable Functions in Java.

Un'app di base Durable Functions ha tre funzioni:

  • Funzione dell'agente di orchestrazione (Cities): flusso di lavoro che orchestra altre funzioni.
  • Funzione attività (Capitalize): funzione che l'agente di orchestrazione chiama per eseguire il lavoro e restituire un valore.
  • Funzione client (StartOrchestration): funzione attivata da HTTP che avvia l'agente di orchestrazione.

Questa guida introduttiva offre tre percorsi di installazione. Usare il selettore nella parte superiore della pagina per scegliere l'approccio preferito:

  • Installazione manuale: creare ogni file manualmente per il controllo completo sulla struttura del progetto.
  • Comando Maven: usare un archetipo Maven per configurare il progetto in un solo comando.
  • Visual Studio Code: utilizzare l'estensione Funzioni di Azure di VS Code per generare il progetto tramite un'interfaccia utente guidata.

Prerequisiti

Per completare questo avvio rapido, avrai bisogno di:

  • Java Developer Kit versione 8 o successiva installata.

  • Apache Maven, versione 3.0 o successiva installata.

  • La versione più recente di Funzioni di Azure Core Tools.

    Per Funzioni di Azure 4.x, è necessario Core Tools versione 4.0.4915 o successiva.

  • Strumento di test HTTP che protegge i dati. Per altre informazioni, vedere strumenti di test HTTP.

  • Visual Studio Code con l'estensione Funzioni di Azure installata (necessaria solo per il percorso di installazione Visual Studio Code).

  • Una sottoscrizione di Azure. Per usare Durable Functions, è necessario disporre di un account Archiviazione di Azure.

Se non si ha un account Azure, creare un account gratuito prima di iniziare.

Aggiungere le dipendenze e i plug-in necessari al progetto

Aggiungere il codice seguente al file pom.xml . Prima di copiarlo, sostituire your-unique-app-name con un nome di app per le funzioni univoco globale. Modificare region, javaVersione resourceGroup in modo che corrisponda all'ambiente in uso.

<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>

Aggiungere i file JSON necessari

Aggiungere un file host.json alla directory del progetto. Dovrebbe risultare simile all'esempio seguente:

{
  "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)"
  }
}

Annotazioni

Durable Functions per Java richiede il bundle di estensione v4. I bundle precedenti non sono supportati. Per altre informazioni, vedere la documentazione relativa ai bundle di estensioni.

Durable Functions richiede un provider di archiviazione per archiviare lo stato di runtime. Aggiungere un file local.settings.json alla directory del progetto per configurare il provider di archiviazione. Per usare Archiviazione di Azure come provider, impostare il valore di AzureWebJobsStorage sulla stringa di connessione dell'account di Archiviazione di Azure:

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

Importante

Il filelocal.settings.json può contenere segreti. Verificare di aggiungerla al file .gitignore per evitare di eseguirne il commit nel controllo di origine.

Creare l'agente di orchestrazione, l'attività e le funzioni client di Durable Functions

Il codice di esempio seguente illustra un esempio di base di ogni tipo di funzione:

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

Creare un progetto Durable Functions locale usando il comando Maven

Eseguire il comando seguente per generare un progetto contenente le funzioni di base di un'app Durable Functions:

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

Alle richieste, inserire le informazioni seguenti:

Rapido Action
groupId Immettere com.function.
artifactId Immettere myDurableFunction.
version Selezionare 1.0-SNAPSHOT.
pacchetto Immettere com.function.
Y Immettere Y e selezionare Invio per confermare.

È ora disponibile un progetto locale con le tre funzioni incluse in un'app Durable Functions di base. L'archetipo include com.microsoft:durabletask-azure-functions automaticamente come dipendenza nel file pom.xml .

Configurare il provider di archiviazione back-end per Durable Functions

Durable Functions richiede un provider di archiviazione per archiviare lo stato di runtime. È possibile impostare Archiviazione di Azure come provider di archiviazione in local.settings.json. Usare la stringa di connessione dell'account di archiviazione di Azure come valore per AzureWebJobsStorage come nell'esempio seguente:

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

Importante

Il filelocal.settings.json può contenere segreti. Verificare di aggiungerla al file .gitignore per evitare di eseguirne il commit nel controllo di origine.

Creare il progetto locale

  1. In Visual Studio Code selezionare F1 (o premere CTRL/CMD+MAIUSC+P) per aprire il riquadro comandi. Al prompt (>), immettere e quindi selezionare Funzioni di Azure: Create New Project.

    Screenshot del comando Crea Nuovo Progetto di Funzioni di Azure nella palette comandi di Visual Studio Code.

  2. Seleziona Sfoglia. Nella finestra di dialogo Seleziona cartella passare alla cartella da usare per il progetto, quindi scegliere Seleziona.

  3. Alle richieste, inserire le informazioni seguenti:

    Rapido Action
    Selezionare un linguaggio di programmazione Selezionare Java.
    Selezionare una versione di Java Selezionare Java 8 o versione successiva. Selezionare la versione Java in cui vengono eseguite le funzioni in Azure e una verificata in locale.
    Specificare un ID gruppo Immettere com.function.
    Specificare un ID artefatto Immettere myDurableFunction.
    Specificare una versione Immettere 1.0-SNAPSHOT.
    Specificare un nome di pacchetto Immettere com.function.
    Specificare un nome di app Immettere myDurableFunction.
    Selezionare lo strumento di compilazione per Java progetto Selezionare Maven.
    Selezionare come si vuole aprire il progetto Selezionare Apri in nuova finestra.

È ora disponibile un progetto con una funzione HTTP di esempio. È possibile rimuovere la funzione HTTP generata, perché si aggiunge il Durable Functions nel passaggio successivo.

Aggiungere funzioni al progetto

  1. Nel riquadro comandi immettere e quindi selezionare Funzioni di Azure: Crea funzione.

  2. Per Modifica filtro modello, selezionare Tutti.

  3. Alle richieste, inserire le informazioni seguenti:

    Rapido Action
    Selezionare un modello per la funzione Selezionare DurableFunctionsOrchestration.
    Specificare un nome di pacchetto Immettere com.function.
    Specificare un nome di funzione Immettere DurableFunctionsOrchestrator.

  4. Nella finestra di dialogo scegliere Selezionare l'account di archiviazione per configurare un account di archiviazione quindi seguire le istruzioni.

Ora dovrebbero essere presenti le tre funzioni di base generate per un'app Durable Functions.

Configurare pom.xml e host.json per Durable Functions

Aggiungere la dipendenza seguente al file pom.xml:

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

Aggiungere la extensions proprietà al file host.json . Se il file ha già altre proprietà, unire il extensions blocco nel codice JSON esistente:

{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "JavaTestHub"
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  }
}

Testare la funzione in locale

Funzioni di Azure Core Tools offre la possibilità di eseguire un progetto Funzioni di Azure nel computer di sviluppo locale.

  1. Se si usa Visual Studio Code, aprire una nuova finestra del terminale ed eseguire i comandi seguenti per compilare il progetto:

    mvn clean package

    Eseguire quindi la funzione durevole:

    mvn azure-functions:run

  2. Nel pannello Terminale copiare l'endpoint dell'URL della funzione attivata da HTTP.

    Screenshot dell'output del terminale che mostra l'URL dell'endpoint HTTP per il runtime locale di Funzioni di Azure.

  3. Usare lo strumento di test HTTP per inviare una richiesta HTTP POST all'endpoint URL.

    La risposta dovrebbe essere simile all'esempio seguente:

    {
    "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..."
}

    La risposta è il risultato iniziale della funzione HTTP. Informa che l'orchestrazione durevole è stata avviata correttamente. Non visualizza ancora il risultato finale dell'orchestrazione. La risposta include alcuni URL utili. Per il momento eseguire una query relativa allo stato dell'orchestrazione.

  4. Copiare il valore dell'URL per statusQueryGetUri, incollarlo nella barra degli indirizzi del browser ed eseguire la richiesta. In alternativa, è possibile continuare a usare lo strumento di test HTTP per inviare la richiesta GET.

    La richiesta esegue una query per determinare lo stato dell'istanza di orchestrazione. Si noterà che l'istanza è stata completata e che include gli output o i risultati della funzione durevole, come in questo esempio:

    {
    "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"
}
  • Last updated on