Azure Functions Java 개발자 가이드Azure Functions Java developer guide

Azure Functions 런타임은 JAVA SE 8 LTS (줄루어 8.31.0.2-jre 8.0.181-win_x64)를 지원 합니다.The Azure Functions runtime supports Java SE 8 LTS (zulu8.31.0.2-jre8.0.181-win_x64). 이 가이드에는 Java를 사용한 Azure Functions 작성에 대 한 복잡 한 정보가 포함 되어 있습니다.This guide contains information about the intricacies of writing Azure Functions with Java.

Java 함수 public 는 주석을 @FunctionName사용 하 여 데코레이팅된 메서드입니다.A Java function is a public method, decorated with the annotation @FunctionName. 이 메서드는 Java 함수의 항목을 정의 하며 특정 패키지에서 고유 해야 합니다.This method defines the entry for a Java function, and must be unique in a particular package.

이 문서에서는 Azure Functions 개발자 참조를 이미 읽었다고 가정합니다.This article assumes that you have already read the Azure Functions developer reference. 또한 함수 퀵 스타트를 완료 하 여 Visual Studio Code 또는 Maven를 사용 하 여 첫 번째 함수를 만들어야 합니다.You should also complete the Functions quickstart to create your first function, by using Visual Studio Code or Maven.

프로그래밍 모델Programming model

트리거 및 바인딩의 개념은 Azure Functions의 기본입니다.The concepts of triggers and bindings are fundamental to Azure Functions. 트리거는 코드 실행을 시작합니다.Triggers start the execution of your code. 바인딩을 사용하면 사용자 지정 데이터 액세스 코드를 작성하지 않고도 데이터를 함수에 전달하고 함수에서 데이터를 반환할 수 있습니다.Bindings give you a way to pass data to and return data from a function, without having to write custom data access code.

폴더 구조Folder structure

Azure Functions Java 프로젝트의 폴더 구조는 다음과 같습니다.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

공유 호스트 json 파일을 사용 하 여 함수 앱을 구성할 수 있습니다.You can use a shared host.json file to configure the function app. 각 함수에는 자체 코드 파일(.java)과 바인딩 구성 파일(function.json)이 있습니다.Each function has its own code file (.java) and binding configuration file (function.json).

하나의 프로젝트에 둘 이상의 함수를 넣을 수 있습니다.You can put more than one function in a project. 함수를 별도의 jar에 넣지 않도록 하세요.Avoid putting your functions into separate jars. 대상 FunctionApp 디렉터리의는 Azure의 함수 앱에 배포 됩니다.The FunctionApp in the target directory is what gets deployed to your function app in Azure.

트리거 및 주석Triggers and annotations

함수는 HTTP 요청, 타이머 또는 데이터 업데이트와 같은 트리거에 의해 호출 됩니다.Functions are invoked by a trigger, such as an HTTP request, a timer, or an update to data. 함수는 하나 이상의 출력을 생성 하기 위해 해당 트리거와 기타 모든 입력을 처리 해야 합니다.Your function needs to process that trigger, and any other inputs, to produce one or more outputs.

com.microsoft.azure.functions.annotation.* 패키지에 포함된 Java 주석을 사용하여 입력 및 출력을 메서드에 바인딩합니다.Use the Java annotations included in the com.microsoft.azure.functions.annotation.* package to bind input and outputs to your methods. 자세한 내용은 Java 참조 문서를 참조 하세요.For more information, see the Java reference docs.

중요

로컬에서 Azure Blob storage, Azure Queue storage 또는 Azure Table storage 트리거를 실행 하려면 로컬. 설정 에서 Azure Storage 계정을 구성 해야 합니다.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.

예제:Example:

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

다음은 function.json azure-maven-플러그 인에 의해 생성 된입니다.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"
    }
  ]
}

JDK 런타임 사용 가능성 및 지원JDK runtime availability and support

Java 함수 앱의 로컬 개발을 위해 Azul Systems에서 Azure Java 8 Jd의 Azul 줄루어 Enterprise 를 다운로드 하 여 사용 합니다.For local development of Java function apps, download and use the Azul Zulu Enterprise for Azure Java 8 JDKs from Azul Systems. Azure Functions는 클라우드에 함수 앱을 배포할 때 Azul Java 8 JDK 런타임을 사용합니다.Azure Functions uses the Azul Java 8 JDK runtime when you deploy your function apps to the cloud.

JDKs 및 함수 앱과 관련 된 문제에 대 한 Azure 지원은 정규화 된 지원 계획을 통해 제공 됩니다.Azure support for issues with the JDKs and function apps is available with a qualified support plan.

JVM 사용자 지정Customize JVM

함수를 사용 하면 Java 함수를 실행 하는 데 사용 되는 JVM (Java virtual machine)을 사용자 지정할 수 있습니다.Functions lets you customize the Java virtual machine (JVM) used to run your Java functions. 기본적으로 사용 되는 JVM 옵션 은 다음과 같습니다.The following JVM options are used by default:

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

이라는 JAVA_OPTS앱 설정에서 추가 인수를 제공할 수 있습니다.You can provide additional arguments in an app setting named JAVA_OPTS. Azure Portal 또는 Azure CLI에서 Azure에 배포 된 함수 앱에 앱 설정을 추가할 수 있습니다.You can add app settings to your function app deployed to Azure in the Azure portal or the Azure CLI.

Azure PortalAzure portal

Azure Portal에서 응용 프로그램 설정 탭 을 사용 JAVA_OPTS 하 여 설정을 추가 합니다.In the Azure portal, use the Application Settings tab to add the JAVA_OPTS setting.

Azure CLIAzure CLI

다음 예제와 같이 az functionapp config appsettings set 명령을 사용 하 JAVA_OPTS여를 설정할 수 있습니다.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"

이 예에서는 헤드리스 모드를 사용 합니다.This example enables headless mode. <APP_NAME> 함수 앱의 이름으로 <RESOURCE_GROUP> ,을 리소스 그룹으로 바꿉니다.Replace <APP_NAME> with the name of your function app, and <RESOURCE_GROUP> with the resource group.

경고

소비 계획에서 값을 WEBSITE_USE_PLACEHOLDER 0사용 하 여 설정을 추가 해야 합니다.In the Consumption plan, you must add the WEBSITE_USE_PLACEHOLDER setting with a value of 0.
이 설정은 Java 함수의 콜드 시작 시간을 증가 시킵니다.This setting does increase the cold start times for Java functions.

타사 라이브러리Third-party libraries

Azure Functions는 타사 라이브러리의 사용을 지원합니다.Azure Functions supports the use of third-party libraries. 기본적으로 프로젝트 pom.xml 파일에 지정 된 모든 종속성은 mvn package 목표 중에 자동으로 번들로 제공 됩니다.By default, all dependencies specified in your project pom.xml file are automatically bundled during the mvn package goal. pom.xml 파일에 종속성으로 지정되지 않은 라이브러리의 경우 함수의 루트 디렉터리에 있는 lib 디렉터리에 배치합니다.For libraries not specified as dependencies in the pom.xml file, place them in a lib directory in the function's root directory. lib 디렉터리에 배치 된 종속성은 런타임에 시스템 클래스 로더에 추가 됩니다.Dependencies placed in the lib directory are added to the system class loader at runtime.

종속성 com.microsoft.azure.functions:azure-functions-java-library 은 기본적으로 클래스 경로에 제공 되며 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. 또한 azure-함수-java worker여기 에 나열 된 종속성을 클래스 경로에 추가 합니다.Also, azure-functions-java-worker adds dependencies listed here to the classpath.

데이터 형식 지원Data type support

일반 old Java 개체 (pojos),에 azure-functions-java-library정의 된 형식 또는 문자열 및 정수와 같은 기본 데이터 형식을 사용 하 여 입력 또는 출력 바인딩에 바인딩할 수 있습니다.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

입력 데이터를 POJO로 변환 하는 경우 azure-함수-java workergson 라이브러리를 사용 합니다.For converting input data to POJO, azure-functions-java-worker uses the gson library. 함수에 대한 입력으로 사용되는 POJO 형식은 public이어야 합니다.POJO types used as inputs to functions should be public.

이진 데이터Binary data

함수의 dataType 필드를로 설정 하 byte[]여에 이진 입력 또는 출력을 바인딩합니다. binaryBind 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");
    }

Null 값이 있는 경우를 사용 Optional<T>합니다.If you expect null values, use Optional<T>.

바인딩Bindings

입력 및 출력 바인딩은 코드 내에서 데이터에 연결하는 선언적 방법을 제공합니다.Input and output bindings provide a declarative way to connect to data from within your code. 함수에는 여러 개의 입력 및 출력 바인딩이 있을 수 있습니다.A function can have multiple input and output bindings.

입력 바인딩 예제Input 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;
        }
    }
}

HTTP 요청을 사용 하 여이 함수를 호출 합니다.You invoke this function with an HTTP request.

  • HTTP 요청 페이로드는 인수 String inputReq에 대 한으로 전달 됩니다.HTTP request payload is passed as a String for the argument inputReq.
  • 테이블 저장소에서 한 항목을 검색 하 고 인수로 TestInputData inputData전달 합니다.One entry is retrieved from Table storage, and is passed as TestInputData to the argument inputData.

입력 일괄 처리를 String[]수신 하려면 List<String>, POJO[], 또는 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;
}

이 함수는 구성된 이벤트 허브에 새 데이터가 있을 때마다 트리거됩니다.This function gets triggered whenever there is new data in the configured event hub. cardinality 가 로MANY설정 되어 있기 때문에 함수는 이벤트 허브에서 메시지 일괄 처리를 수신 합니다.Because the cardinality is set to MANY, the function receives a batch of messages from the event hub. EventData이벤트 허브에서 함수 실행을 TestEventData 위해로 변환 됩니다.EventData from event hub gets converted to TestEventData for the function execution.

출력 바인딩 예제Output binding example

를 사용 $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;
    }
}

여러 개의 출력 바인딩이 있으면 둘 중 하나에 대한 반환 값을 사용합니다.If there are multiple output bindings, use the return value for only one of them.

여러 출력 값을 보내려면 azure-functions-java-library 패키지에 정의된 OutputBinding<T>를 사용합니다.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;
    }

HttpRequest에 대해이 함수를 호출 합니다.You invoke this function on an HttpRequest. 큐 저장소에 여러 값을 기록 합니다.It writes multiple values to Queue storage.

HttpRequestMessage 및 HttpResponseMessageHttpRequestMessage and HttpResponseMessage

이러한 정의는에 azure-functions-java-library정의 되어 있습니다.These are defined in azure-functions-java-library. HttpTrigger 함수를 사용 하는 도우미 형식입니다.They are helper types to work with HttpTrigger functions.

특수 형식Specialized type 대상Target 일반적인 용도Typical usage
HttpRequestMessage<T> HTTP 트리거HTTP Trigger 메서드, 헤더 또는 쿼리를 가져옵니다.Gets method, headers, or queries
HttpResponseMessage HTTP 출력 바인딩HTTP Output Binding 200 이외의 상태를 반환 합니다.Returns status other than 200

메타데이터Metadata

입력 데이터와 함께 트리거 메타데이터를 보내는 트리거는 거의 없습니다.Few triggers send trigger metadata along with input data. 주석을 @BindingName 사용 하 여 트리거 메타 데이터에 바인딩할 수 있습니다.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);
    }
}

앞의 예제에서는 queryValue http 요청 URL http://{example.host}/api/metadata?name=test의 쿼리 문자열 매개 변수에 name 바인딩됩니다.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. 다음은 큐 트리거 메타 데이터에서에 Id 바인딩하는 방법을 보여 주는 다른 예제입니다.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);
    }

참고

주석에 제공 된 이름이 메타 데이터 속성과 일치 해야 합니다.The name provided in the annotation needs to match the metadata property.

실행 컨텍스트Execution context

ExecutionContext에 정의 된에 azure-functions-java-library는 함수 런타임과 통신 하는 도우미 메서드가 포함 되어 있습니다.ExecutionContext, defined in the azure-functions-java-library, contains helper methods to communicate with the functions runtime.

로거Logger

getLogger 에서ExecutionContext정의 된를 사용 하 여 함수 코드에서 로그를 작성 합니다.Use getLogger, defined in ExecutionContext, to write logs from function code.

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

로그 보기 및 추적View logs and trace

Azure CLI를 사용 하 여 Java stdout 및 stderr 로깅 뿐만 아니라 기타 응용 프로그램 로깅을 스트리밍할 수 있습니다.You can use the Azure CLI to stream Java stdout and stderr logging, as well as other application logging.

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

Azure CLI를 사용 하 여 함수 앱에 대 한 로깅 출력을 스트리밍하려면 새 명령 프롬프트, Bash 또는 터미널 세션을 열고 다음 명령을 입력 합니다.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

Az webapp log tail 명령에는 --provider 옵션을 사용 하 여 출력을 필터링 할 수 있는 옵션이 있습니다.The az webapp log tail command has options to filter output by using the --provider option.

Azure CLI를 사용 하 여 로그 파일을 단일 ZIP 파일로 다운로드 하려면 새 명령 프롬프트, Bash 또는 터미널 세션을 열고 다음 명령을 입력 합니다.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

이 명령을 실행 하기 전에 Azure Portal 또는 Azure CLI에서 파일 시스템 로깅을 사용 하도록 설정 해야 합니다.You must have enabled file system logging in the Azure portal or the Azure CLI before running this command.

환경 변수Environment variables

Functions에서 앱 설정(예: 서비스 연결 문자열)은 실행 중에 환경 변수로 노출됩니다.In Functions, app settings, such as service connection strings, are exposed as environment variables during execution. 이러한 설정은,를 System.getenv("AzureWebJobsStorage")사용 하 여 액세스할 수 있습니다.You can access these settings by using, System.getenv("AzureWebJobsStorage").

다음 예제에서는 라는 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);
    }
}

다음 단계Next steps

Java 개발을 Azure Functions 하는 방법에 대 한 자세한 내용은 다음 리소스를 참조 하세요.For more information about Azure Functions Java development, see the following resources: