Guida per sviluppatori Java per Funzioni di AzureAzure Functions Java developer guide

Il runtime di funzioni di Azure supporta 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). Questa guida contiene informazioni preoccupare delle complessità della scrittura di funzioni di Azure con Java.This guide contains information about the intricacies of writing Azure Functions with Java.

Una funzione Java è un public metodo decorato con l'annotazione @FunctionName.A Java function is a public method, decorated with the annotation @FunctionName. Questo metodo definisce la voce per una funzione Java e deve essere univoco in un pacchetto specifico.This method defines the entry for a Java function, and must be unique in a particular package.

Questo articolo presuppone che siano già state lette le informazioni di riferimento per sviluppatori su Funzioni di Azure.This article assumes that you have already read the Azure Functions developer reference. È necessario completare anche l'avvio rapido di funzioni per creare la prima funzione usando Visual Studio Code oppure Maven.You should also complete the Functions quickstart to create your first function, by using Visual Studio Code or Maven.

Modello di programmazioneProgramming model

I concetti di trigger e binding sono fondamentali in Funzioni di Azure.The concepts of triggers and bindings are fundamental to Azure Functions. I trigger avviano l'esecuzione del codice,Triggers start the execution of your code. mentre i binding consentono la trasmissione dei dati e la restituzione dei dati da una funzione, senza dover scrivere codice personalizzato per l'accesso ai dati.Bindings give you a way to pass data to and return data from a function, without having to write custom data access code.

Struttura di cartelleFolder structure

Ecco la struttura di cartelle di un progetto Java di funzioni di Azure: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

È possibile usare un oggetto condiviso host. JSON file per configurare l'app per le funzioni.You can use a shared host.json file to configure the function app. Ogni funzione ha il proprio file di codice (con estensione java) e il proprio file di configurazione delle associazioni (function.json).Each function has its own code file (.java) and binding configuration file (function.json).

È possibile inserire più funzioni in un progetto.You can put more than one function in a project. Evitare di inserire le funzioni in file con estensione jar separati.Avoid putting your functions into separate jars. Il FunctionApp nella destinazione di directory è ciò che viene distribuito all'app di funzione in Azure.The FunctionApp in the target directory is what gets deployed to your function app in Azure.

Trigger e annotazioniTriggers and annotations

Le funzioni vengono richiamate da un trigger, ad esempio una richiesta HTTP, un timer o un aggiornamento dati.Functions are invoked by a trigger, such as an HTTP request, a timer, or an update to data. La funzione deve elaborare tale trigger e altri input, per produrre uno o più output.Your function needs to process that trigger, and any other inputs, to produce one or more outputs.

Usare le annotazioni Java incluse nel pacchetto com.microsoft.azure.functions.annotation.* per associare input e output ai metodi dell'utente.Use the Java annotations included in the com.microsoft.azure.functions.annotation.* package to bind input and outputs to your methods. Per altre informazioni, vedere la documentazione di riferimento Java.For more information, see the Java reference docs.

Importante

È necessario configurare un account di archiviazione di Azure nel Local per eseguire localmente l'archiviazione Blob di Azure, archiviazione code di Azure o i trigger di archiviazione tabelle di Azure.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.

Esempio:Example:

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

Ecco il corrispondente generata function.json per il azure-funzioni-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à del runtime JDK e supportoJDK runtime availability and support

Per lo sviluppo locale di App per le funzioni Java, scaricare e usare la Azul Zulu Enterprise per Azure Java 8 JDK dal Azul Systems.For local development of Java function apps, download and use the Azul Zulu Enterprise for Azure Java 8 JDKs from Azul Systems. Funzioni di Azure usa il runtime di Java 8 JDK di Azul quando l'app per le funzioni viene distribuita nel cloud.Azure Functions uses the Azul Java 8 JDK runtime when you deploy your function apps to the cloud.

Supporto di Azure per i problemi con il JDK e la funzione è disponibile con le app una piano di supporto completo.Azure support for issues with the JDKs and function apps is available with a qualified support plan.

Personalizzare JVMCustomize JVM

Funzioni consente di personalizzare la macchina virtuale Java (JVM) usata per eseguire le funzioni Java.Functions lets you customize the Java virtual machine (JVM) used to run your Java functions. Il le opzioni di JVM seguenti vengono utilizzati per impostazione predefinita:The following JVM options are used by default:

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

È possibile fornire argomenti aggiuntivi in un'impostazione dell'app denominata JAVA_OPTS.You can provide additional arguments in an app setting named JAVA_OPTS. È possibile aggiungere le impostazioni dell'app per le app per le funzioni distribuite in Azure nel portale di Azure o il comando di Azure.You can add app settings to your function app deployed to Azure in the Azure portal or the Azure CLI.

Portale di AzureAzure portal

Nel portale di Azure, utilizzare il scheda delle impostazioni dell'applicazione per aggiungere il JAVA_OPTS impostazione.In the Azure portal, use the Application Settings tab to add the JAVA_OPTS setting.

Interfaccia della riga di comando di AzureAzure CLI

È possibile usare la az functionapp config appsettings set comando per impostare JAVA_OPTS, come illustrato nell'esempio seguente: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"

Questo esempio abilita modalità headless.This example enables headless mode. Sostituire <APP_NAME> con il nome dell'app per le funzioni e <RESOURCE_GROUP> con il gruppo di risorse.Replace <APP_NAME> with the name of your function app, and <RESOURCE_GROUP> with the resource group.

Avviso

Nel piano a consumo, è necessario aggiungere il WEBSITE_USE_PLACEHOLDER impostazione con un valore di 0.In the Consumption plan, you must add the WEBSITE_USE_PLACEHOLDER setting with a value of 0.
Questa impostazione di aumentare i tempi di avvio a freddo per funzioni Java.This setting does increase the cold start times for Java functions.

Librerie di terze partiThird-party libraries

Funzioni di Azure supporta l'uso di librerie di terze parti.Azure Functions supports the use of third-party libraries. Per impostazione predefinita, tutte le dipendenze specificate nel progetto pom.xml file sono inclusi automaticamente durante il mvn package obiettivo.By default, all dependencies specified in your project pom.xml file are automatically bundled during the mvn package goal. Inserire le librerie non specificate come dipendenze del file pom.xml in una directory lib nella directory radice della funzione.For libraries not specified as dependencies in the pom.xml file, place them in a lib directory in the function's root directory. Dipendenze inserite nel lib directory vengono aggiunti al caricatore di classe di sistema in fase di esecuzione.Dependencies placed in the lib directory are added to the system class loader at runtime.

Il com.microsoft.azure.functions:azure-functions-java-library dipendenza sono fornita sul classpath per impostazione predefinita e non deve essere incluso nel lib directory.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. È inoltre azure-funzioni-java-worker aggiunge le dipendenze elencate qui al classpath.Also, azure-functions-java-worker adds dependencies listed here to the classpath.

Supporto dei tipi di datiData type support

È possibile usare oggetti Java precedenti normali (Pojo), tipi definiti in azure-functions-java-library, o tipi di dati primitivi, ad esempio String e Integer per l'associazione di input o le associazioni di output.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

Per la conversione dei dati di input in POJO, azure-funzioni-java-worker Usa le gson libreria.For converting input data to POJO, azure-functions-java-worker uses the gson library. I tipi POJO usati come input delle funzioni devono essere public.POJO types used as inputs to functions should be public.

Dati binariBinary data

Eseguire l'associazione di input / output al binari byte[], impostando il dataType campo il file Function. JSON a 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");
    }

Se si prevede che i valori null, usare Optional<T>.If you expect null values, use Optional<T>.

AssociazioniBindings

I binding di input e output forniscono una modalità dichiarativa per connettersi ai dati dall'interno del codice.Input and output bindings provide a declarative way to connect to data from within your code. Una funzione può avere più binding di input e output.A function can have multiple input and output bindings.

Esempio di associazione di inputInput 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;
        }
    }
}

Si richiama questa funzione con una richiesta HTTP.You invoke this function with an HTTP request.

  • Payload della richiesta HTTP viene passato come un String dell'argomento inputReq.HTTP request payload is passed as a String for the argument inputReq.
  • Una voce viene recuperata dall'archiviazione tabelle e viene passata come TestInputData nell'argomento inputData.One entry is retrieved from Table storage, and is passed as TestInputData to the argument inputData.

Per ricevere un batch di input, è possibile associare a String[], POJO[], List<String>, o 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;
}

Questa funzione viene attivata ogni volta che sono disponibili nuovi dati nell'hub eventi configurato.This function gets triggered whenever there is new data in the configured event hub. Poiché il cardinality è impostata su MANY, la funzione riceve un batch di messaggi dall'hub eventi.Because the cardinality is set to MANY, the function receives a batch of messages from the event hub. EventData evento dell'hub viene convertito in un TestEventData per l'esecuzione della funzione.EventData from event hub gets converted to TestEventData for the function execution.

Esempio di associazione di outputOutput binding example

È possibile associare un'associazione di output per il valore restituito usando $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;
    }
}

Se sono presenti più associazioni di output, usare il valore restituito per una sola di tali associazioni.If there are multiple output bindings, use the return value for only one of them.

Per inviare più valori di output, usare il tipo OutputBinding<T> definito nel pacchetto 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;
    }

Si richiama questa funzione in una HttpRequest.You invoke this function on an HttpRequest. Scrive più valori in archiviazione di Accodamento.It writes multiple values to Queue storage.

HttpRequestMessage e HttpResponseMessageHttpRequestMessage and HttpResponseMessage

Questi vengono definiti azure-functions-java-library.These are defined in azure-functions-java-library. Si tratta di tipi di helper per lavorare con le funzioni HttpTrigger.They are helper types to work with HttpTrigger functions.

Tipo specializzatoSpecialized type DestinazioneTarget Utilizzo tipicoTypical usage
HttpRequestMessage<T> Trigger HTTPHTTP Trigger Ottiene (metodo), le intestazioni o queryGets method, headers, or queries
HttpResponseMessage Associazione di output HTTPHTTP Output Binding Restituisce lo stato diverso da 200Returns status other than 200

MetadataMetadata

Alcuni trigger inviano metadati dei trigger insieme ai dati di input.Few triggers send trigger metadata along with input data. È possibile utilizzare l'annotazione @BindingName da associare a metadati dei trigger.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);
    }
}

Nell'esempio precedente, il queryValue è associato al parametro di stringa di query name nell'URL della richiesta 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. Ecco un altro esempio, che mostra come associare a Id dai metadati del trigger della coda.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);
    }

Nota

Il nome fornito nell'annotazione deve corrispondere alla proprietà dei metadati.The name provided in the annotation needs to match the metadata property.

Contesto di esecuzioneExecution context

ExecutionContext, definito nel azure-functions-java-library, contiene i metodi helper per comunicare con il runtime di funzioni.ExecutionContext, defined in the azure-functions-java-library, contains helper methods to communicate with the functions runtime.

LoggerLogger

Uso getLogger, definita in ExecutionContext, scrivere i log dal codice della funzione.Use getLogger, defined in ExecutionContext, to write logs from function code.

Esempio: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);
    }
}

Visualizzazione dei log e della tracciaView logs and trace

È possibile usare il comando di Azure per la registrazione di stderr e stdout Java flusso, nonché altri la registrazione delle applicazioni.You can use the Azure CLI to stream Java stdout and stderr logging, as well as other application logging.

Di seguito viene illustrato come configurare l'app di funzione per scrivere la registrazione delle applicazioni tramite la CLI di Azure: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

Per trasmettere l'output di registrazione per le app per le funzioni usando il comando di Azure, aprire un nuovo prompt dei comandi, Bash o del terminale e immettere il comando seguente: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

Il della parte finale del log di az webapp comando ha opzioni da applicare un filtro output utilizzando il --provider opzione.The az webapp log tail command has options to filter output by using the --provider option.

Per scaricare i file di log come un unico file ZIP con la CLI di Azure, aprire un nuovo prompt dei comandi, Bash o del terminale e immettere il comando seguente: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

È necessario aver abilitato la registrazione nel portale di Azure o il comando di Azure prima di eseguire questo comando del sistema di file.You must have enabled file system logging in the Azure portal or the Azure CLI before running this command.

Variabili di ambienteEnvironment variables

In Funzioni, le impostazioni dell'app, come le stringhe di connessione al servizio, vengono esposte come variabili di ambiente durante l'esecuzione.In Functions, app settings, such as service connection strings, are exposed as environment variables during execution. È possibile accedere a queste impostazioni usando, System.getenv("AzureWebJobsStorage").You can access these settings by using, System.getenv("AzureWebJobsStorage").

Ad esempio, è possibile aggiungere AppSetting, con il nome testAppSetting e il valore testAppSettingValue:For example, you can add AppSetting, with the name testAppSetting and the value testAppSettingValue:


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

Passaggi successiviNext steps

Per altre informazioni sullo sviluppo Java di funzioni di Azure, vedere le risorse seguenti:For more information about Azure Functions Java development, see the following resources: