Guide des développeurs Java sur Azure FunctionsAzure Functions Java developer guide

Le runtime Azure Functions prend en charge Java SE 8 LTS (zulu8.31.0.2-jre8.0.181-win_x64).The Azure Functions runtime supports Java SE 8 LTS (zulu8.31.0.2-jre8.0.181-win_x64). Ce guide contient des informations sur les complexités de l’écriture de fonctions Azure avec Java.This guide contains information about the intricacies of writing Azure Functions with Java.

Comme c’est le cas pour d’autres langages, une application de fonction peut avoir une ou plusieurs fonctions.As it happens to other languages, a Function App may have one or more functions. Une fonction Java est une méthode public dotée de l’annotation @FunctionName.A Java function is a public method, decorated with the annotation @FunctionName. Cette méthode définit l’entrée d’une fonction Java et doit être unique dans un package particulier.This method defines the entry for a Java function, and must be unique in a particular package. Une application de fonction écrite en Java peut avoir plusieurs classes avec plusieurs méthodes publiques annotées avec @FunctionName.One Function App written in Java may have multiple classes with multiple public methods annotated with @FunctionName.

Cet article suppose que vous ayez déjà lu l’article Informations de référence pour les développeurs sur Azure Functions.This article assumes that you have already read the Azure Functions developer reference. Vous devez également compléter le démarrage rapide de Functions pour créer votre première fonction, à l’aide de Visual Studio Code ou de Maven.You should also complete the Functions quickstart to create your first function, by using Visual Studio Code or Maven.

Modèle de programmationProgramming model

Les concepts de déclencheurs et liaisons sont fondamentaux pour Azure Functions.The concepts of triggers and bindings are fundamental to Azure Functions. Les déclencheurs démarrent l’exécution de votre code.Triggers start the execution of your code. Les liaisons vous permettent de transmettre des données et de retourner des données à partir d’une fonction, sans avoir à écrire du code d’accès aux données personnalisées.Bindings give you a way to pass data to and return data from a function, without having to write custom data access code.

Créer des fonctions JavaCreate Java functions

Pour faciliter la création de fonctions Java, il existe des outils basés sur Maven et des archétypes qui utilisent des modèles Java prédéfinis pour permettre de créer des projets avec un déclencheur de fonction spécifique.To make it easier to create Java functions, there are Maven-based tooling and archetypes that use predefined Java templates to help you create projects with a specific function trigger.

Outils basés sur MavenMaven-based tooling

Les environnements de développement suivants comportent des outils Azure Functions qui permettent de créer des projets de fonctions Java :The following developer environments have Azure Functions tooling that lets you create Java function projects:

Les liens d’articles ci-dessus vous montrent comment créer vos premières fonctions dans l’environnement IDE de votre choix.The article links above show you how to create your first functions using your IDE of choice.

Génération de modèles automatique du projetProject Scaffolding

Si vous préférez le développement en ligne de commande dans le terminal, le moyen le plus simple de définir la structure de projets de fonctions Java consiste à utiliser des archétypes Apache Maven.If you prefer command line development from the Terminal, the simplest way to scaffold Java-based function projects is to use Apache Maven archetypes. Il existe actuellement deux archétypes Functions pour Maven :There are currently two Functions archetypes for Maven:

Le code source de ces archétypes se trouve dans le dépôt GitHub Archétypes Azure Maven.The source code of these archetypes can be found on the Azure Maven Archetypes GitHub repository.

Structure de dossiersFolder structure

Voici la structure de dossiers d’un projet Java Azure Functions :Here is the folder structure of an Azure Functions Java project:

FunctionsProject
 | - src
 | | - main
 | | | - java
 | | | | - FunctionApp
 | | | | | - MyFirstFunction.java
 | | | | | - MySecondFunction.java
 | - target
 | | - azure-functions
 | | | - FunctionApp
 | | | | - FunctionApp.jar
 | | | | - host.json
 | | | | - MyFirstFunction
 | | | | | - function.json
 | | | | - MySecondFunction
 | | | | | - function.json
 | | | | - bin
 | | | | - lib
 | - pom.xml

* Le projet Kotlin semble très similaire, car il est toujours Maven* The Kotlin project looks very similar since it is still Maven

Vous pouvez utiliser un fichier host.json partagé pour configurer l’application de fonction.You can use a shared host.json file to configure the function app. Chaque fonction a son propre fichier de code (.java) et un fichier de configuration de liaison (function.json).Each function has its own code file (.java) and binding configuration file (function.json).

Vous pouvez placer plusieurs fonctions dans un projet.You can put more than one function in a project. Évitez de placer vos fonctions dans des fichiers JAR distincts.Avoid putting your functions into separate jars. L’élément FunctionApp dans le répertoire cible correspond à ce qui est déployé dans votre application de fonction dans Azure.The FunctionApp in the target directory is what gets deployed to your function app in Azure.

Déclencheurs et annotationsTriggers and annotations

Les fonctions sont appelées par un déclencheur, comme une requête HTTP, un minuteur ou une mise à jour des données.Functions are invoked by a trigger, such as an HTTP request, a timer, or an update to data. Votre fonction doit traiter ce déclencheur et toutes les autres entrées, puis produire une ou plusieurs sorties.Your function needs to process that trigger, and any other inputs, to produce one or more outputs.

Utilisez les annotations Java incluses dans le package com.microsoft.azure.functions.annotation.* pour lier des entrées et des sorties à vos méthodes.Use the Java annotations included in the com.microsoft.azure.functions.annotation.* package to bind input and outputs to your methods. Pour plus d’informations, consultez les Docs de référence Java.For more information, see the Java reference docs.

Important

Vous devez configurer un compte de stockage Azure dans votre fichier local.settings.json pour exécuter les déclencheurs de Stockage Blob Azure, Stockage File d’attente Azure et Stockage Table Azure en local.You must configure an Azure Storage account in your local.settings.json to run Azure Blob storage, Azure Queue storage, or Azure Table storage triggers locally.

Exemple :Example:

public class Function {
    public String echo(@HttpTrigger(name = "req", 
      methods = {"post"},  authLevel = AuthorizationLevel.ANONYMOUS) 
        String req, ExecutionContext context) {
        return String.format(req);
    }
}

Voici le fichier function.json correspondant généré par azure-functions-maven-plugin :Here is the generated corresponding function.json by the azure-functions-maven-plugin:

{
  "scriptFile": "azure-functions-example.jar",
  "entryPoint": "com.example.Function.echo",
  "bindings": [
    {
      "type": "httpTrigger",
      "name": "req",
      "direction": "in",
      "authLevel": "anonymous",
      "methods": [ "post" ]
    },
    {
      "type": "http",
      "name": "$return",
      "direction": "out"
    }
  ]
}

Disponibilité et prise en charge du runtime JDKJDK runtime availability and support

Téléchargez et utilisez le JDK Java 8 Azul Zulu Enterprise for Azure à partir d’Azul Systems pour le développement local d’applications de fonction Java.For local development of Java function apps, download and use the Azul Zulu Enterprise for Azure Java 8 JDKs from Azul Systems. Azure Functions utilise le runtime du JDK Java 8 Azul lorsque vous déployez vos applications de fonctions sur le cloud.Azure Functions uses the Azul Java 8 JDK runtime when you deploy your function apps to the cloud.

Le support Azure des problèmes avec les JDK et les applications de fonction est disponible avec dans un plan de support qualifié.Azure support for issues with the JDKs and function apps is available with a qualified support plan.

Personnaliser une machine virtuelle JavaCustomize JVM

Azure Functions vous permet de personnaliser la machine virtuelle Java (JVM) utilisée pour exécuter vos fonctions Java.Functions lets you customize the Java virtual machine (JVM) used to run your Java functions. Les options de machine virtuelle Java suivantes sont utilisées par défaut :The following JVM options are used by default:

  • -XX:+TieredCompilation
  • -XX:TieredStopAtLevel=1
  • -noverify
  • -Djava.net.preferIPv4Stack=true
  • -jar

Vous pouvez fournir des arguments supplémentaires dans le paramètre d’application nommé JAVA_OPTS.You can provide additional arguments in an app setting named JAVA_OPTS. Vous pouvez ajouter des paramètres d’application à votre application de fonction déployée sur Azure dans le portail Azure ou Azure CLI.You can add app settings to your function app deployed to Azure in the Azure portal or the Azure CLI.

Portail AzureAzure portal

Dans le portail Azure, utilisez l’onglet Paramètres d’application pour ajouter le paramètre JAVA_OPTS.In the Azure portal, use the Application Settings tab to add the JAVA_OPTS setting.

Azure CLIAzure CLI

Vous pouvez utiliser la commande az functionapp config appsettings set pour définir JAVA_OPTS, comme le montre l’exemple suivant :You can use the az functionapp config appsettings set command to set JAVA_OPTS, as in the following example:

az functionapp config appsettings set --name <APP_NAME> \
--resource-group <RESOURCE_GROUP> \
--settings "JAVA_OPTS=-Djava.awt.headless=true"

Cet exemple active le mode « headless ».This example enables headless mode. Remplacez également <APP_NAME> par le nom de votre application de fonction, et <RESOURCE_GROUP> par le groupe de ressources.Replace <APP_NAME> with the name of your function app, and <RESOURCE_GROUP> with the resource group.

Avertissement

Dans Plan de consommation, vous devez ajouter le paramètre WEBSITE_USE_PLACEHOLDER avec une valeur de 0.In the Consumption plan, you must add the WEBSITE_USE_PLACEHOLDER setting with a value of 0.
Ce paramètre n’augmente pas les temps de démarrage à froid pour les fonctions Java.This setting does increase the cold start times for Java functions.

Bibliothèques tiercesThird-party libraries

Azure Functions prend en charge l’utilisation de bibliothèques tierces.Azure Functions supports the use of third-party libraries. Par défaut, toutes les dépendances spécifiées dans votre fichier pom.xml de projet sont automatiquement regroupées pendant l’objectif mvn package.By default, all dependencies specified in your project pom.xml file are automatically bundled during the mvn package goal. Pour les bibliothèques qui ne sont pas définies comme des dépendances dans le fichier pom.xml, placez-les dans un répertoire lib du dossier racine de la fonction.For libraries not specified as dependencies in the pom.xml file, place them in a lib directory in the function's root directory. Les dépendances placées dans le répertoire lib sont ajoutées au chargeur de classes système lors de l’exécution.Dependencies placed in the lib directory are added to the system class loader at runtime.

La dépendance com.microsoft.azure.functions:azure-functions-java-library est fournie sur le chemin de classe par défaut et ne doit pas être incluse dans le répertoire lib.The com.microsoft.azure.functions:azure-functions-java-library dependency is provided on the classpath by default, and doesn't need to be included in the lib directory. En outre, azure-fonctions-java-worker ajoute les dépendances listées ici à l’instruction classpath.Also, azure-functions-java-worker adds dependencies listed here to the classpath.

Prise en charge des types de donnéesData type support

Vous pouvez utiliser des objets Plain old Java (POJO), des types définis dans azure-functions-java-library ou des types de données dataTypes primitifs comme chaîne et comme entier à lier à des liaisons d’entrée/de sortie.You can use Plain old Java objects (POJOs), types defined in azure-functions-java-library, or primitive data types such as String and Integer to bind to input or output bindings.

POJOPOJOs

Pour la conversion des données d’entrée en POJO, azure-fonctions-java-worker utilise une bibliothèque gson.For converting input data to POJO, azure-functions-java-worker uses the gson library. Les types POJO utilisés comme entrées de fonctions doivent être public.POJO types used as inputs to functions should be public.

Données binairesBinary data

Liez des entrées et sorties binaires à byte[] en définissant le champ dataType dans votre fichier function.json sur binary :Bind binary inputs or outputs to byte[], by setting the dataType field in your function.json to binary:

   @FunctionName("BlobTrigger")
    @StorageAccount("AzureWebJobsStorage")
     public void blobTrigger(
        @BlobTrigger(name = "content", path = "myblob/{fileName}", dataType = "binary") byte[] content,
        @BindingName("fileName") String fileName,
        final ExecutionContext context
    ) {
        context.getLogger().info("Java Blob trigger function processed a blob.\n Name: " + fileName + "\n Size: " + content.length + " Bytes");
    }

Si vous attendez des valeurs null, utilisez Optional<T>.If you expect null values, use Optional<T>.

LiaisonsBindings

Les liaisons d’entrée et de sortie fournissent un moyen déclaratif de se connecter à des données à partir de votre code.Input and output bindings provide a declarative way to connect to data from within your code. Une fonction peut avoir plusieurs liaisons d’entrée et de sortie.A function can have multiple input and output bindings.

Exemple de liaison d’entréeInput binding example

package com.example;

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

public class Function {
    @FunctionName("echo")
    public static String echo(
        @HttpTrigger(name = "req", methods = { "put" }, authLevel = AuthorizationLevel.ANONYMOUS, route = "items/{id}") String inputReq,
        @TableInput(name = "item", tableName = "items", partitionKey = "Example", rowKey = "{id}", connection = "AzureWebJobsStorage") TestInputData inputData
        @TableOutput(name = "myOutputTable", tableName = "Person", connection = "AzureWebJobsStorage") OutputBinding<Person> testOutputData,
    ) {
        testOutputData.setValue(new Person(httpbody + "Partition", httpbody + "Row", httpbody + "Name"));
        return "Hello, " + inputReq + " and " + inputData.getKey() + ".";
    }

    public static class TestInputData {
        public String getKey() { return this.RowKey; }
        private String RowKey;
    }
    public static class Person {
        public String PartitionKey;
        public String RowKey;
        public String Name;

        public Person(String p, String r, String n) {
            this.PartitionKey = p;
            this.RowKey = r;
            this.Name = n;
        }
    }
}

Vous appelez cette fonction avec une requête HTTP.You invoke this function with an HTTP request.

  • La charge utile de requête HTTP est transmise comme une String pour l’argument inputReq.HTTP request payload is passed as a String for the argument inputReq.
  • Une entrée est récupérée à partir du Stockage Table et est transmise comme TestInputData à l’argument inputData.One entry is retrieved from Table storage, and is passed as TestInputData to the argument inputData.

Pour recevoir un lot d’entrées, vous pouvez lier à String[], POJO[], List<String> ou List<POJO>.To receive a batch of inputs, you can bind to String[], POJO[], List<String>, or List<POJO>.

@FunctionName("ProcessIotMessages")
    public void processIotMessages(
        @EventHubTrigger(name = "message", eventHubName = "%AzureWebJobsEventHubPath%", connection = "AzureWebJobsEventHubSender", cardinality = Cardinality.MANY) List<TestEventData> messages,
        final ExecutionContext context)
    {
        context.getLogger().info("Java Event Hub trigger received messages. Batch size: " + messages.size());
    }
    
    public class TestEventData {
    public String id;
}

Cette fonction est déclenchée chaque fois qu’il existe de nouvelles données dans l’Event Hub configuré.This function gets triggered whenever there is new data in the configured event hub. Comme la cardinality est définie sur MANY, la fonction reçoit un lot de messages du hub d’événements.Because the cardinality is set to MANY, the function receives a batch of messages from the event hub. Les EventData de l’Event Hub sont converties en TestEventData pour l’exécution de la fonction.EventData from event hub gets converted to TestEventData for the function execution.

Exemple de liaison de sortieOutput binding example

Vous pouvez lier une liaison de sortie à la valeur de retour avec $return.You can bind an output binding to the return value by using $return.

package com.example;

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

public class Function {
    @FunctionName("copy")
    @StorageAccount("AzureWebJobsStorage")
    @BlobOutput(name = "$return", path = "samples-output-java/{name}")
    public static String copy(@BlobTrigger(name = "blob", path = "samples-input-java/{name}") String content) {
        return content;
    }
}

S’il existe plusieurs liaisons de sortie, utilisez la valeur de retour pour un seul d’entre eux.If there are multiple output bindings, use the return value for only one of them.

Pour envoyer plusieurs valeurs de sortie, utilisez la OutputBinding<T> définie dans le package azure-functions-java-library.To send multiple output values, use OutputBinding<T> defined in the azure-functions-java-library package.

@FunctionName("QueueOutputPOJOList")
    public HttpResponseMessage QueueOutputPOJOList(@HttpTrigger(name = "req", methods = { HttpMethod.GET,
            HttpMethod.POST }, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            @QueueOutput(name = "itemsOut", queueName = "test-output-java-pojo", connection = "AzureWebJobsStorage") OutputBinding<List<TestData>> itemsOut, 
            final ExecutionContext context) {
        context.getLogger().info("Java HTTP trigger processed a request.");
       
        String query = request.getQueryParameters().get("queueMessageId");
        String queueMessageId = request.getBody().orElse(query);
        itemsOut.setValue(new ArrayList<TestData>());
        if (queueMessageId != null) {
            TestData testData1 = new TestData();
            testData1.id = "msg1"+queueMessageId;
            TestData testData2 = new TestData();
            testData2.id = "msg2"+queueMessageId;

            itemsOut.getValue().add(testData1);
            itemsOut.getValue().add(testData2);

            return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + queueMessageId).build();
        } else {
            return request.createResponseBuilder(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body("Did not find expected items in CosmosDB input list").build();
        }
    }

     public static class TestData {
        public String id;
    }

Vous appelez cette fonction avec une requête HTTP.You invoke this function on an HttpRequest. Elle écrit plusieurs valeurs dans Stockage File d’attente.It writes multiple values to Queue storage.

HttpRequestMessage et HttpResponseMessageHttpRequestMessage and HttpResponseMessage

Elles sont définies dans azure-functions-java-library.These are defined in azure-functions-java-library. Il s’agit de types d’assistance pour utiliser les fonctions HttpTrigger.They are helper types to work with HttpTrigger functions.

Type spécialiséSpecialized type CibleTarget Utilisation classiqueTypical usage
HttpRequestMessage<T> Déclencheur HTTPHTTP Trigger Obtention des requêtes, en-têtes et méthodesGets method, headers, or queries
HttpResponseMessage Liaison de sortie HTTPHTTP Output Binding Renvoi de statut autre que 200Returns status other than 200

MétadonnéesMetadata

Quelques déclencheurs envoient des métadonnées de déclencheur ainsi que des données d’entrée.Few triggers send trigger metadata along with input data. Vous pouvez utiliser une annotation @BindingName à lier à des métadonnées de déclencheur.You can use annotation @BindingName to bind to trigger metadata.

package com.example;

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


public class Function {
    @FunctionName("metadata")
    public static String metadata(
        @HttpTrigger(name = "req", methods = { "get", "post" }, authLevel = AuthorizationLevel.ANONYMOUS) Optional<String> body,
        @BindingName("name") String queryValue
    ) {
        return body.orElse(queryValue);
    }
}

Dans l’exemple précédent, la valeur queryValue est liée au paramètre de chaîne de requête name dans l’URL de requête HTTP http://{example.host}/api/metadata?name=test.In the preceding example, the queryValue is bound to the query string parameter name in the HTTP request URL, http://{example.host}/api/metadata?name=test. Voici un autre exemple de liaison à Id à partir des métadonnées de déclencheur de file d’attente.Here's another example, showing how to bind to Id from queue trigger metadata.

 @FunctionName("QueueTriggerMetadata")
    public void QueueTriggerMetadata(
        @QueueTrigger(name = "message", queueName = "test-input-java-metadata", connection = "AzureWebJobsStorage") String message,@BindingName("Id") String metadataId,
        @QueueOutput(name = "output", queueName = "test-output-java-metadata", connection = "AzureWebJobsStorage") OutputBinding<TestData> output,
        final ExecutionContext context
    ) {
        context.getLogger().info("Java Queue trigger function processed a message: " + message + " with metadaId:" + metadataId );
        TestData testData = new TestData();
        testData.id = metadataId;
        output.setValue(testData);
    }

Notes

Le nom fourni dans l’annotation doit correspondre à la propriété des métadonnées.The name provided in the annotation needs to match the metadata property.

Contexte d’exécutionExecution context

Le contenu ExecutionContext défini dans la bibliothèque azure-functions-java-library contient des méthodes d’assistance pour communiquer avec l’environnement d’exécution des fonctions.ExecutionContext, defined in the azure-functions-java-library, contains helper methods to communicate with the functions runtime.

EnregistreurLogger

Utilisez getLogger, défini dans ExecutionContext, pour écrire des journaux d’activité à partir du code de fonction.Use getLogger, defined in ExecutionContext, to write logs from function code.

Exemple :Example:


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

public class Function {
    public String echo(@HttpTrigger(name = "req", methods = {"post"}, authLevel = AuthorizationLevel.ANONYMOUS) String req, ExecutionContext context) {
        if (req.isEmpty()) {
            context.getLogger().warning("Empty request body received by function " + context.getFunctionName() + " with invocation " + context.getInvocationId());
        }
        return String.format(req);
    }
}

Afficher les journaux d’activité et le suiviView logs and trace

Vous pouvez utiliser Azure CLI pour diffuser en continu la journalisation Java stdout et stderr, ainsi que toute autre journalisation d’application.You can use the Azure CLI to stream Java stdout and stderr logging, as well as other application logging.

Voici comment configurer votre application de fonction pour écrire la journalisation d’application en utilisant Azure CLI :Here's how to configure your function app to write application logging by using the Azure CLI:

az webapp log config --name functionname --resource-group myResourceGroup --application-logging true

Pour obtenir une sortie de journalisation pour votre application de fonction en utilisant Azure CLI, ouvrez une nouvelle session d’invite de commandes, Bash ou Terminal, puis entrez la commande suivante :To stream logging output for your function app by using the Azure CLI, open a new command prompt, Bash, or Terminal session, and enter the following command:

az webapp log tail --name webappname --resource-group myResourceGroup

La commande az webapp log tail permet de filtrer la sortie en utilisant l’option --provider.The az webapp log tail command has options to filter output by using the --provider option.

Pour télécharger les fichiers journaux sous la forme d’un fichier zip unique en utilisant Azure CLI, ouvrez une nouvelle session d’invite de commandes, Bash ou Terminal, puis entrez la commande suivante :To download the log files as a single ZIP file by using the Azure CLI, open a new command prompt, Bash, or Terminal session, and enter the following command:

az webapp log download --resource-group resourcegroupname --name functionappname

Avant d’exécuter cette commande, vous devez avoir activé la journalisation du système de fichiers dans le portail Azure ou dans Azure CLI.You must have enabled file system logging in the Azure portal or the Azure CLI before running this command.

Variables d'environnementEnvironment variables

Dans Functions, les paramètres de l’application, par exemple, les chaînes de connexion de service, sont exposées en tant que variables d’environnement pendant l’exécution.In Functions, app settings, such as service connection strings, are exposed as environment variables during execution. Vous pouvez accéder à ces paramètres avec System.getenv("AzureWebJobsStorage").You can access these settings by using, System.getenv("AzureWebJobsStorage").

L’exemple suivant obtient le paramètre d’application, avec la clé nommée myAppSetting :The following example gets the application setting, with the key named myAppSetting:


public class Function {
    public String echo(@HttpTrigger(name = "req", methods = {"post"}, authLevel = AuthorizationLevel.ANONYMOUS) String req, ExecutionContext context) {
        context.getLogger().info("My app setting value: "+ System.getenv("myAppSetting"));
        return String.format(req);
    }
}

Étapes suivantesNext steps

Pour plus d’informations sur le développement Java Azure Functions, voir les ressources suivantes :For more information about Azure Functions Java development, see the following resources: