Azure Functions の Java 開発者向けガイドAzure Functions Java developer guide

注意

Azure Functions 用の Java は現在プレビュー段階です。Java for Azure Functions is currently in preview. 破壊的変更やお知らせを含む重要な更新プログラムを受け取るには、Azure App Service のお知らせのリポジトリをご覧ください。To receive important updates, including breaking changes announcements, watch the Azure App Service announcements repository.

プログラミング モデル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.

入力を処理し、出力を生成するには、関数がステートレス メソッドである必要があります。A function should be a stateless method to process input and produce output. 関数は、クラスのどのインスタンス フィールドにも依存しない必要があります。Your function should not depend on any instance fields of the class. すべての関数メソッドは public である必要があり、注釈 @FunctionName を持つメソッドは一意である必要があります。メソッド名が関数のエントリを定義するためです。All the function methods should be public and method with annotation @FunctionName must be unique as method name defines the entry for a function.

フォルダー構造Folder structure

Azure Functions の Java プロジェクトのフォルダー構造を次に示します。Here is the folder structure of an Azure Function 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

関数アプリの構成に使用できる共有 host.json ファイルがあります。There's a shared host.json file that can be used to configure the function app. 各関数には、独自のコード ファイル (.java) とバインディング構成ファイル (function.json) があります。Each function has its own code file (.java) and binding configuration file (function.json).

1 つのプロジェクトに複数の関数を含めることができます。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

Azure の関数は、HTTP 要求、タイマー、日付の更新などのトリガーで呼び出されます。Azure functions are invoked by a trigger, such as an HTTP request, a timer, or an update to data. 関数はそのトリガーと他の入力を処理して 1 つまたは複数の出力を生成する必要があります。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 Java reference docs.

重要

Azure Storage Blob、Queue、または Table のトリガーをローカルに実行するには、local.settings.json に Azure Storage アカウントを構成する必要があります。You must configure an Azure Storage account in your local.settings.json to run Azure Storage Blob, Queue, or Table 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);
    }
}

azure-functions-maven-plugin によって生成された、対応する function.json を次に示します: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 から Azul Zulu Enterprise for Azure Java 8 JDK をダウンロードして使用します。Download and use the Azul Zulu Enterprise for Azure Java 8 JDKs from Azul Systems for local development of Java function apps. Azure Functions は、関数アプリをクラウドにデプロイするときに Azul Java 8 JDK ランタイムを使用します。Azure Functions uses the Azul Java 8 JDK runtime when you deploy your function apps to the cloud.

JKD および関数アプリに関する問題に対する Azure サポートは、認定サポート プランを通じてご利用いただけます。Azure support for issues with the JDKs and Function apps is available with a qualified support plan.

サードパーティ製ライブラリ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 will be 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 will be 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 does not need to be included in the lib directory. また、ここに示されている依存関係が、azure-functions-java-worker によってクラスパスに追加されます。Also, dependencies listed here are added to the classpath by azure-functions-java-worker.

データ型のサポートData type support

Plain old Java object (POJO)、azure-functions-java-library 内で定義されている型、または文字列や整数などのプリミティブなデータ型を使用して入力/出力バインドにバインドできます。You can use Plain old Java objects (POJOs), types defined in azure-functions-java-library or primitive dataTypes such as String, Integer to bind to input/output bindings.

Plain old Java object (POJO)Plain old Java objects (POJOs)

入力データを POJO に変換する場合、azure-functions-java-worker では gson ライブラリが使用されます。For converting input data to POJO, azure-functions-java-worker uses gson library. 関数への入力として使用される POJO の型は public である必要があります。POJO types used as inputs to functions should be public.

バイナリ データBinary data

バイナリの入力または出力を byte[] にバインドするには、使用する function.json 内の dataType フィールドを 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");
    }

null 値が必要な場合は Optional<T> を使用しますUse Optional<T> for if null values are expected

バインド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.

入力バインディングの例Example Input binding

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 要求を使用して呼び出されます。This function is invoked with an HTTP request.

  • HTTP 要求のペイロードは、引数 inputReqString として渡されますHTTP request payload is passed as a String for the argument inputReq
  • 1 つのエントリが Azure Table Storage から取得され、引数 inputDataTestInputData として渡されます。One entry is retrieved from the Azure Table Storage and is passed as TestInputData to the argument inputData.

入力のバッチを受信するには、String[]POJO[]List<String> または 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. cardinalityMANY に設定されているので、関数はイベント ハブからメッセージのバッチを受信します。As the cardinality is set to MANY, function receives a batch of messages from event hub. イベント ハブからの EventData は関数実行のために TestEventData に変換されます。EventData from event hub gets converted to TestEventData for the function execution.

出力バインディングの例Example Output binding

$return を使用して、出力バインディングを戻り値にバインドすることができますYou can bind an output binding to the return value 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;
    }
}

複数の出力バインディングが存在する場合は、そのうちの 1 つにのみ戻り値を使用します。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 上で呼び出され、複数の値が Azure キューに書き込まれますAbove function is invoked on an HttpRequest and writes multiple values to the Azure Queue

HttpRequestMessage と HttpResponseMessageHttpRequestMessage and HttpResponseMessage

azure-functions-java-library 内で定義されている HttpRequestMessage 型と HttpResponseMessage 型は、HttpTrigger 関数を操作するためのヘルパー型ですHttpRequestMessage and HttpResponseMessage types are defined in azure-functions-java-library are helper types to work with HttpTrigger functions

特殊な型Specialized Type ターゲットTarget 一般的な用途Typical Usage
HttpRequestMessage<T> HTTP トリガーHTTP Trigger メソッド、ヘッダー、またはクエリを取得するGet method, headers, or queries
HttpResponseMessage HTTP 出力のバインドHTTP Output Binding 200 以外の状態を返すReturn status other than 200

MetadataMetadata

いくつかのトリガーでは、入力データと共にトリガー メタデータが送信されます。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);
    }
}

上記の例では、queryValuenameHttp 要求 URLhttp://{example.host}/api/metadata?name=test 内のクエリ文字列パラメーターにバインドされています。In the example above, the queryValue is bound to query string parameter name in the Http request URL http://{example.host}/api/metadata?name=test. キュー トリガー メタデータから Id にバインドする別の例を次に示しますFollowing is another example to binding 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);
    }

注意

注釈に指定されている名前がメタデータ プロパティと一致する必要があります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

ExecutionContext 内で定義されている getLogger を使用して、関数コードからログを書き込みます。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

Java の stdout と stderr ログ、その他の各種アプリケーション ログは、Azure CLI を使用してストリーム配信することができます。You can use the Azure CLI to stream Java stdout and stderr logging as well as other application logging.

Azure CLI を使って、アプリケーション ログを出力するための構成を関数アプリケーションに対して行います。Configure your Function application to write application logging 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 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 using the --provider option.

Azure CLI を使ってログ ファイルを単一の ZIP ファイルとしてダウンロードするには、コマンド プロンプト、Bash、ターミナルのいずれかのセッションを新たに開いて、次のコマンドを入力します。To download the log files as a single ZIP file 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 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 using, System.getenv("AzureWebJobsStorage")

例:Example:

名前が testAppSetting で値が testAppSettingValue のAppSetting を追加しますAdd AppSetting with name testAppSetting and 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);
    }
}

次の手順Next steps

Java による Azure Functions 開発の詳細については、次のリソースを参照してください。For more information about Azure Function Java development, see the following resources: