Créer votre première fonction durable dans Java

Article
06/01/2023

Durable Functions est une extension d’Azure Functions qui vous permet d’écrire des fonctions avec état dans un environnement serverless. L’extension gère l’état, les points de contrôle et les redémarrages à votre place.

Dans ce guide de démarrage rapide, vous allez apprendre à créer et à tester une application Durable Functions « Hello World » dans Java. L’application Durable Functions la plus simple contient les trois fonctions suivantes :

La fonction d’orchestrateur : elle décrit un workflow qui orchestre d’autres fonctions.
La fonction d’activité : appelée par la fonction d’orchestrateur, elle effectue un travail et retourne éventuellement une valeur.
La fonction de client : une fonction Azure normale qui démarre une fonction d’orchestrateur. Cet exemple utilise une fonction déclenchée via HTTP.

Ce guide de démarrage rapide vous montre comment créer cette application « Hello World », ce que vous pouvez faire de différentes manières. Utilisez le sélecteur ci-dessus pour choisir votre approche préférée.

Prérequis

Pour suivre ce didacticiel, vous avez besoin des éléments suivants :

Java Developer Kit (JDK) version 8 ou plus récente.
Apache Maven version 3.0 ou plus récente.
Dernières version d’Azure Functions Core Tools.
- Pour Azure Functions 4.x, Core Tools v4.0.4915 ou plus récent est nécessaire.
Un compte Stockage Azure, qui nécessite que vous ayez un abonnement Azure.

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit Azure avant de commencer.

Ajouter les dépendances et plug-ins requis à votre projet

Ajoutez ce qui suit à votre 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>

Ajouter les fichiers JSON nécessaires

Ajoutez un fichier host.json à votre répertoire de projet. Celui-ci doit se présenter comme suit :

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

Notes

Il est important de noter que seul le bundle d’extension Azure Functions v4 a actuellement la prise en charge nécessaire pour Durable Functions pour Java. Durable Functions pour Java n’est pas pris en charge dans v3 et les offres groupées d’extensions précoces. Pour plus d’informations sur les offres groupées d’extensions, consultez la documentation relative aux offres groupées d’extensions.

Durable Functions a besoin d’un fournisseur de stockage pour stocker l’état d’exécution. Ajoutez un fichier local.settings.json à votre répertoire de projet pour configurer le fournisseur de stockage. Pour utiliser Stockage Azure comme fournisseur, définissez la valeur de AzureWebJobsStorage sur la chaîne de connexion de votre compte Stockage Azure :

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

Créer vos fonctions

L’exemple de code ci-dessous montre un exemple simple de chacune d’entre elles :

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

Créer un projet local avec la commande Maven

Exécutez la commande suivante pour générer un projet avec les fonctions de base d’une application 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"

Suivez les invites et fournissez les informations suivantes :

Prompt	Valeur
groupId	`com.function`
artifactId	`myDurableFunction`
version	`1.0-SNAPSHOT`
package	`com.function`
O	Appuyez sur entrée pour confirmer

Vous disposez maintenant d’un projet local généré avec les trois fonctions nécessaires pour une application Durable Functions de base.

Vérifiez que vous avez com.microsoft:durabletask-azure-functions comme dépendance dans votre pom.xml.

Configurer le fournisseur de stockage back-end

Durable Functions a besoin d’un fournisseur de stockage pour stocker l’état d’exécution. Vous pouvez configurer l’utilisation de Stockage Azure en tant que fournisseur de stockage dans local.settings.json en fournissant la chaîne de connexion de votre compte Stockage Azure comme valeur à AzureWebJobsStorage :

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

Créer votre projet local

Dans Visual Studio Code, appuyez sur F1 (ou Ctrl/Cmd+Maj+P) pour ouvrir la palette de commandes. Dans la palette de commandes, recherchez et sélectionnez Azure Functions: Create New Project....
Désignez un emplacement de dossier vide pour votre projet et choisissez Sélectionner.

Suivez les invites et fournissez les informations suivantes :

Prompt	Valeur
Sélectionner une langue	Choisissez `Java`.
Sélectionner une version de Java	Choisissez `Java 8` ou plus récent, la version de Java sur laquelle vos fonctions s’exécutent dans Azure. Choisissez une version de Java que vous avez vérifiée localement.
Fournir un ID de groupe	`com.function`.
Fournir un ID d’artefact	`myDurableFunction`.
Fournir une version	`1.0-SNAPSHOT`.
Fournir un nom de package	`com.function`.
Fournir un nom d’application	`myDurableFunction`.
Sélectionner l’outil de génération pour le projet Java	Choisissez `Maven`.
Sélectionner la façon dont vous souhaitez ouvrir votre projet	Choisissez `Open in new window`.

Vous disposez maintenant d’un projet avec un exemple de fonction HTTP. Vous pouvez supprimer cette fonction si vous le souhaitez, car nous ajouterons les fonctions de base d’une application Durable Functions à l’étape suivante.

Ajouter des fonctions au projet

Dans la palette de commandes, recherchez et sélectionnez Azure Functions: Create Function....
Sélectionnez Change template filter sur All.
Suivez les invites et fournissez les informations suivantes :

Prompt Valeur

Sélectionner un modèle pour votre fonction DurableFunctionsOrchestration

Fournir un nom de package com.function

Fournir un nom de fonction DurableFunctionsOrchestrator
Choisissez Select storage account dans la fenêtre contextuelle vous demandant de configurer les informations du compte de stockage et suivez les invites.

Prompt	Valeur
Sélectionner un modèle pour votre fonction	DurableFunctionsOrchestration
Fournir un nom de package	`com.function`
Fournir un nom de fonction	`DurableFunctionsOrchestrator`

Les trois fonctions de base d’une application Durable Functions doivent maintenant être générées.

Configurer pom.xml et host.json

Ajoutez la dépendance suivante à votre pom.xml :

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

Ajoutez la propriété extensions à votre host.json :

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

Tester la fonction en local

Azure Functions Core Tools vous permet d’exécuter un projet Azure Functions sur votre ordinateur de développement local.

Notes

Durable Functions pour Java nécessite Azure Functions Core Tools v4.0.4915 ou plus récent. Vous pouvez voir la version installée en exécutant la commande func --version à partir du terminal.

Si vous utilisez Visual Studio Code, ouvrez une nouvelle fenêtre de terminal et exécutez les commandes suivantes pour générer le projet :
```
mvn clean package
```
Exécutez ensuite la fonction durable :
```
mvn azure-functions:run
```
Dans le panneau Terminal, copiez le point de terminaison de l’URL de votre fonction déclenchée via HTTP.

À l’aide d’un outil tel que Postman ou cURL, envoyez une requête HTTP POST au point de terminaison de l’URL. Vous devez obtenir une réponse similaire à ce qui suit :

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

La réponse est le résultat initial provenant de la fonction HTTP, qui vous indique que l’orchestration durable a bien été démarrée. Il ne s’agit pas encore du résultat final de l’orchestration. La réponse contient plusieurs URL utiles. Pour le moment, demandons l’état de l’orchestration.

Copiez la valeur de l’URL pour statusQueryGetUri, collez-la dans la barre d’adresse du navigateur, puis exécutez la requête. Vous pouvez également continuer à utiliser Postman ou cURL pour émettre la requête GET.

La requête interroge l’instance d’orchestration pour obtenir l’état. Une fois l’exécution de l’instance terminée, vous devez recevoir une réponse comprenant les sorties ou résultats de la fonction durable. Voici comment il se présente :
```
{
    "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"
}
```

Créer votre première fonction durable dans Java

Prérequis

Ajouter les dépendances et plug-ins requis à votre projet

Ajouter les fichiers JSON nécessaires

Créer vos fonctions

Créer un projet local avec la commande Maven

Configurer le fournisseur de stockage back-end

Créer votre projet local

Ajouter des fonctions au projet

Configurer pom.xml et host.json

Tester la fonction en local

Ressources supplémentaires