příručka pro vývojáře v javě Azure Functions

Tato příručka obsahuje podrobné informace, které vám pomůžou s vývojem Azure Functions pomocí Javy.

Pokud s Azure Functions teprve začínáte, zvažte nejprve čtení jednoho z následujících článků:

Začínáme Koncepty Scénáře/ukázky

Základy funkcí v Javě

Funkce Java je public metoda, zdobená poznámkou @FunctionName. Tato metoda definuje položku pro funkci Java a musí být jedinečná v konkrétním balíčku. Balíček může mít více tříd s více veřejnými metodami anotovanými @FunctionNamepomocí . Jeden balíček se nasadí do aplikace funkcí v Azure. Když běží v Azure, aplikace funkcí poskytuje kontext nasazení, spouštění a správy pro jednotlivé funkce Javy.

Programovací model

Koncepty triggerů a vazeb jsou zásadní pro Azure Functions. Triggery spustí spuštění kódu. Vazby umožňují předávat data a vracet data z funkce, aniž byste museli zapisovat vlastní přístupový kód dat.

Vytváření funkcí v Javě

Aby bylo snazší vytvářet funkce Java, existují nástroje a archetypy Mavenu, které používají předdefinované šablony Java, které vám pomůžou vytvářet projekty s konkrétní aktivační událostí funkce.

Nástroje založené na Mavenu

Následující vývojářská prostředí mají nástroje pro Azure Functions, které umožňují vytvářet projekty funkcí Java:

Výše uvedené odkazy ukazují, jak vytvořit první funkce pomocí zvoleného integrovaného vývojového prostředí (IDE).

Project generování uživatelského rozhraní

Pokud dáváte přednost vývoji příkazového řádku z terminálu, nejjednodušší způsob, jak vygenerovat projekty funkcí založené na Javě, je používat Apache Maven archetypy. Archetyp Java Maven pro Azure Functions se publikuje pod následující groupId:artifactId: com.microsoft.azure:azure-functions-archetype.

Následující příkaz vygeneruje nový projekt funkcí Java pomocí tohoto archetypu:

mvn archetype:generate \
    -DarchetypeGroupId=com.microsoft.azure \
    -DarchetypeArtifactId=azure-functions-archetype

Pokud chcete začít používat tento archetyp, podívejte se na rychlý start v Javě.

Struktura složek

Tady je struktura složek projektu Azure Functions Java:

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

Ke konfiguraci aplikace funkcí můžete použít sdílený soubor host.json . Každá funkce má vlastní soubor kódu (.java) a konfigurační soubor vazby (function.json).

Do projektu můžete umístit více než jednu funkci. Vyhněte se vkládání funkcí do samostatných jar. V FunctionApp cílovém adresáři se nasadí do vaší aplikace funkcí v Azure.

Triggery a poznámky

Funkce jsou vyvolány triggerem, jako je požadavek HTTP, časovač nebo aktualizace dat. Aby vaše funkce vytvořila jeden nebo více výstupů, musí tento trigger zpracovat a všechny další vstupy.

Pomocí poznámek v Javě, které jsou součástí balíčku com.microsoft.azure.functions.not.* k vytvoření vazby vstupu a výstupů k vašim metodám. Další informace najdete v referenční dokumentaci k Javě.

Důležité

V souboru local.settings.json musíte nakonfigurovat účet Azure Storage, aby se spouštěly triggery Azure Blob Storage, Azure Queue Storage nebo Azure Table Storage místně.

Příklad:

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

Tady je vygenerovaný modul function.jsonplug-in azure-functions-maven-plugin:

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

Verze Javy

Verze Javy použitá při vytváření aplikace funkcí, na které se funkce spouští v Azure, je zadána v souboru pom.xml. Archetyp Maven aktuálně generuje pom.xml pro Javu 8, který můžete změnit před publikováním. Verze Java v pom.xml by měla odpovídat verzi, na které jste místně vyvinuli a otestovali aplikaci.

Podporované verze

Následující tabulka uvádí aktuální podporované verze Java pro každou hlavní verzi modulu runtime Functions podle operačního systému:

Verze funkcí Verze Javy (Windows) Verze Javy (Linux)
4.x 11
8
11
8
3.x 11
8
11
8
2.x 8 Není k dispozici

Pokud nezadáte verzi Javy pro vaše nasazení, archetyp Maven se během nasazení do Azure standardně nastaví na Java 8.

Určení verze nasazení

Verzi Javy, na kterou cílí archetyp Maven, můžete řídit pomocí parametru -DjavaVersion . Hodnota tohoto parametru může být buď 8 nebo 11.

Archetyp Maven generuje pom.xml, který cílí na zadanou verzi Javy. Následující prvky v pom.xml označují verzi Javy, která se má použít:

Prvek Hodnota Java 8 Hodnota Java 11 Description
Java.version 1.8 11 Verze Javy, kterou používá modul plug-in maven-compiler-plug.
JavaVersion 8 11 Verze Java hostovaná aplikací funkcí v Azure

Následující příklady ukazují nastavení pro Javu 8 v příslušných částech souboru pom.xml:

Java.version

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <java.version>1.8</java.version>
    <azure.functions.maven.plugin.version>1.6.0</azure.functions.maven.plugin.version>
    <azure.functions.java.library.version>1.3.1</azure.functions.java.library.version>
    <functionAppName>fabrikam-functions-20200718015742191</functionAppName>
    <stagingDirectory>${project.build.directory}/azure-functions/${functionAppName}</stagingDirectory>
</properties>

JavaVersion

<runtime>
    <!-- runtime os, could be windows, linux or docker-->
    <os>windows</os>
    <javaVersion>8</javaVersion>
    <!-- for docker function, please set the following parameters -->
    <!-- <image>[hub-user/]repo-name[:tag]</image> -->
    <!-- <serverId></serverId> -->
    <!-- <registryUrl></registryUrl>  -->
</runtime>

Důležité

Musíte mít správně nastavenou proměnnou prostředí JAVA_HOME na adresář JDK, který se používá při kompilaci kódu pomocí Mavenu. Ujistěte se, že verze sady JDK je alespoň tak vysoká jako Java.version nastavení.

Určení operačního systému nasazení

Maven také umožňuje určit operační systém, na kterém běží vaše aplikace funkcí v Azure. os Pomocí prvku zvolte operační systém.

Prvek Windows Linux Docker
os windows linux docker

Následující příklad ukazuje nastavení operačního systému v runtime části pom.xml souboru:

<runtime>
    <!-- runtime os, could be windows, linux or docker-->
    <os>windows</os>
    <javaVersion>8</javaVersion>
    <!-- for docker function, please set the following parameters -->
    <!-- <image>[hub-user/]repo-name[:tag]</image> -->
    <!-- <serverId></serverId> -->
    <!-- <registryUrl></registryUrl>  -->
</runtime>

Dostupnost a podpora modulu runtime JDK

Microsoft a Adoptium buildy OpenJDK jsou poskytovány a podporovány ve funkcích pro Javu 8 a 11. Tyto binární soubory jsou poskytovány jako beznákladová multiformní distribuce openJDK pro Azure. Obsahují všechny komponenty pro sestavování a spouštění aplikací v Javě SE. Následující tabulka popisuje nové verze Javy, které aplikace Function začnou používat s vydáním platformy Functions z ledna 2022:

Verze Javy Linux Windows
Java 8 1.8.0_302 (Adoptium) 1.8.0_302 (Adoptium)
Java 11 11.0.12 (MSFT) 11.0.12 (MSFT)

Pro místní vývoj nebo testování si můžete zdarma stáhnout build OpenJDK nebo Adoptium Temurin . podpora Azure problémů s sadami JDK a aplikacemi funkcí jsou k dispozici s kvalifikovaným plánem podpory.

Pokud chcete pokračovat v používání binárních souborů Zulu pro Azure ve vaší aplikaci Function, nakonfigurujte aplikaci odpovídajícím způsobem. Binární soubory Azul můžete dál používat pro váš web, ale všechny opravy zabezpečení nebo vylepšení budou dostupné jenom v nových verzích OpenJDK, takže doporučujeme tuto konfiguraci nakonec odebrat, aby vaše aplikace Funkcí používaly nejnovější dostupnou verzi Javy.

Přizpůsobení prostředí JVM

Funkce umožňují přizpůsobit virtuální počítač Java (JVM) používaný ke spouštění funkcí Java. Ve výchozím nastavení se používají následující možnosti prostředí JVM :

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

Do nastavení aplikace s názvem JAVA_OPTSmůžete zadat další argumenty. Nastavení aplikace můžete přidat do aplikace funkcí nasazené do Azure v Azure Portal nebo Azure CLI.

Důležité

V plánu Consumption musíte také přidat nastavení WEBSITE_USE_PLACEHOLDER s hodnotou 0, aby přizpůsobení fungovalo. Toto nastavení zvyšuje dobu studeného spuštění funkcí Java.

portál Azure

V Azure Portal přidejte JAVA_OPTS nastavení pomocí karty Nastavení aplikace.

Azure CLI

Příkaz az functionapp config appsettings set můžete použít k nastavení JAVA_OPTS, jako v následujícím příkladu:

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

Tento příklad umožňuje bezhlavý režim. Nahraďte <APP_NAME> názvem aplikace funkcí a <RESOURCE_GROUP> skupinou prostředků.

Knihovny třetích stran

Azure Functions podporuje použití knihoven třetích stran. Ve výchozím nastavení se všechny závislosti zadané v souboru projektu pom.xml automaticky sbalí během mvn package cíle. U knihoven, které nejsou určené jako závislosti v pom.xml souboru, je umístěte do adresáře v kořenovém lib adresáři funkce. Závislosti umístěné v lib adresáři se přidají do zavaděče tříd systému za běhu.

Závislost com.microsoft.azure.functions:azure-functions-java-library je ve výchozím nastavení poskytována na cestě ke třídě a není nutné ji zahrnout do lib adresáře. Azure-functions-java-worker také přidá závislosti uvedené zde do cesty tříd.

Podpora datových typů

Pomocí jednoduchých starých objektů Java (POJO), typů definovaných v azure-functions-java-librarynebo primitivních datových typech, jako je String a Integer, můžete vytvořit vazbu na vstupní nebo výstupní vazby.

POJOs

Pro převod vstupních dat na POJO používá azure-functions-java-worker knihovnu gson . Typy POJO používané jako vstupy do funkcí by měly být public.

Binární data

Vytvoření vazby binárních vstupů nebo výstupů s byte[]nastavením dataType pole v souboru function.json na 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");
    }

Pokud očekáváte hodnoty null, použijte Optional<T>.

Vazby

Vstupní a výstupní vazby poskytují deklarativní způsob připojení k datům z kódu. Funkce může mít více vstupních a výstupních vazeb.

Příklad vstupní vazby

package com.example;

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

public class Function {
    @FunctionName("echo")
    public static String echo(
        @HttpTrigger(name = "req", methods = { HttpMethod.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;
        }
    }
}

Tuto funkci vyvoláte pomocí požadavku HTTP.

  • Datová část požadavku HTTP se předá jako String argument inputReq.
  • Jedna položka se načte ze služby Table Storage a předá se jako TestInputData argument inputData.

Pokud chcete přijímat dávku vstupů, můžete svázat s String[], POJO[], List<String>nebo 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;
}

Tato funkce se aktivuje vždy, když je v nakonfigurovaném centru událostí nová data. Vzhledem k tomu, že je nastavená cardinality na MANY, funkce obdrží dávku zpráv z centra událostí. EventData z centra událostí se převede na TestEventData provádění funkce.

Příklad výstupní vazby

Výstupní vazbu k návratové hodnotě můžete svázat pomocí $returnpříkazu .

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

Pokud existuje více výstupních vazeb, použijte zpáteční hodnotu pouze pro jednu z nich.

Pokud chcete odeslat více výstupních hodnot, použijte OutputBinding<T> definovaný v azure-functions-java-library balíčku.

@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;
    }

Tuto funkci vyvoláte na httpRequest. Zapisuje do služby Queue Storage více hodnot.

HttpRequestMessage a HttpResponseMessage

Jsou definovány v azure-functions-java-library. Jedná se o pomocné typy pro práci s funkcemi HttpTrigger.

Specializovaný typ Cíl Typické použití
HttpRequestMessage<T> Trigger HTTP Získá metodu, hlavičky nebo dotazy.
HttpResponseMessage Výstupní vazba HTTP Vrátí stav jiný než 200.

Metadata

Několik triggerů odesílá metadata triggeru spolu se vstupními daty. Poznámku můžete použít k vytvoření vazby @BindingName k aktivaci metadat.

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 = { HttpMethod.GET, HttpMethod.POST }, authLevel = AuthorizationLevel.ANONYMOUS) Optional<String> body,
        @BindingName("name") String queryValue
    ) {
        return body.orElse(queryValue);
    }
}

V předchozím příkladu queryValue je vázán na parametr name řetězce dotazu v adrese URL požadavku HTTP , http://{example.host}/api/metadata?name=test. Tady je další příklad, který ukazuje, jak vytvořit vazbu na Id metadata triggeru fronty.

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

Poznámka

Název zadaný v poznámce musí odpovídat vlastnosti metadat.

Kontext spuštění

ExecutionContext, definované v souboru azure-functions-java-library, obsahuje pomocné metody pro komunikaci s modulem runtime funkcí. Další informace najdete v referenčním článku ExecutionContext.

Logger

K zápisu protokolů z kódu funkce použijte getLogger, definovaný v ExecutionContextsouboru.

Příklad:


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

public class Function {
    public String echo(@HttpTrigger(name = "req", methods = {HttpMethod.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);
    }
}

Zobrazení protokolů a trasování

Pomocí Azure CLI můžete streamovat protokolování stdout v Javě a stderr i jiné protokolování aplikací.

Tady je postup konfigurace aplikace funkcí pro zápis protokolování aplikace pomocí Azure CLI:

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

Pokud chcete streamovat výstup protokolování pro vaši aplikaci funkcí pomocí Azure CLI, otevřete nový příkazový řádek, Bash nebo relaci terminálu a zadejte následující příkaz:

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

Příkaz az webapp log tail má možnosti filtrování výstupu pomocí této --provider možnosti.

Pokud chcete stáhnout soubory protokolu jako jeden soubor ZIP pomocí Azure CLI, otevřete nový příkazový řádek, Bash nebo relaci terminálu a zadejte následující příkaz:

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

Před spuštěním tohoto příkazu musíte povolit protokolování systému souborů v Azure Portal nebo Azure CLI.

Proměnné prostředí

Ve službě Functions se nastavení aplikace, jako jsou připojovací řetězce služby, zobrazují během provádění jako proměnné prostředí. K těmto nastavením můžete přistupovat pomocí . System.getenv("AzureWebJobsStorage")

Následující příklad získá nastavení aplikace s klíčem s názvem myAppSetting:


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

Poznámka

Hodnota FUNCTIONS_EXTENSION_VERSION AppSetting by měla být ~2 nebo ~3 pro optimalizované prostředí studeného startu.

Další kroky

Další informace o vývoji Azure Functions Javě najdete v následujících zdrojích informací: