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 関数は、入力を処理し出力を生成するステートレスなクラス メソッドである必要があります。Your Azure function should be a stateless class method that processes input and produces output. インスタンス メソッドを記述できますが、開発する関数は、クラスのインスタンス フィールドに依存することはできません。Although you can write instance methods, your function must not depend on any instance fields of the class. すべての関数のメソッドには、public アクセス修飾子が必要です。All function methods must have a public access modifier.

1 つのプロジェクトに複数の関数を含めることができます。You can put more than one function in a project. 複数の jar に関数を分けることは避けてください。Avoid putting your functions into separate jars.

トリガーと注釈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 リファレンス ドキュメントと、Azure Functions のバインド リファレンス ドキュメント (HTTP トリガー用など) を参照してください。Sample code using the annotations is available in the Java reference docs for each annotation and in the Azure Functions binding reference documentation, such as the one for HTTP triggers.

トリガーの入力と出力は、注釈を使用せずに、関数用の function.json で定義することもできます。Trigger inputs and outputs can also be defined in the function.json for your function instead of through annotations. この方法で注釈の代わりに function.json を使用することはお勧めしません。Using function.json instead of annotations in this way is not recommended.

重要

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 using annotations:

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

注釈なしで記述された同じ関数:The same function written without annotations:

package com.example;

public class MyClass {
    public static String echo(String in) {
        return in;
    }
}

対応する function.json:with the corresponding function.json:

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

サードパーティ製ライブラリ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.

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

入力データと出力データでは、ネイティブ型、Java 型をカスタマイズした型、azure-functions-java-library パッケージに定義された特別な Azure 型を含む Java の任意のデータ型を使用できます。You can use any data types in Java for the input and output data, including native types; customized Java types and specialized Azure types defined in azure-functions-java-library package. Azure Functions ランタイムが、受信した入力をコードで要求された型に変換します。The Azure Functions runtime attempts convert the input received into the type requested by your code.

文字列Strings

関数のメソッドに渡された値は、関数の対応する入力パラメーターの型が String 型の場合は、文字列にキャストされます。Values passed into function methods will be cast to Strings if the corresponding input parameter type for the function is of type String.

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

JSON でフォーマットされる文字列は、関数の入力シグネチャが特定の Java 型を予期している場合は、その Java 型にキャストされます。Strings formatted with JSON will be cast to Java types if the input signature of the function expects that Java type. この変換によって、JSON で渡し、Java 型を使用できるようになります。This conversion allows you to pass in JSON and work with Java types.

関数への入力として使用される POJO 型は、それが使用される関数のメソッドと同じ public アクセス修飾子を持っている必要があります。POJO types used as inputs to functions must the same public access modifier as the function methods they are being used in. POJO クラスのフィールドで public を宣言する必要はありません。You don't have to declare POJO class fields public. たとえば、JSON 文字列 { "x": 3 } は、次の POJO 型に変換できます。For example, a JSON string { "x": 3 } is able to be converted to the following POJO type:

public class MyData {
    private int x;
}

バイナリ データBinary data

バイナリ データは、Azure 関数コードでは byte[] と表わされます。Binary data is represented as a byte[] in your Azure functions code. バイナリの入力または出力を関数にバインドするには、function.json の dataType フィールドを binary に設定します。Bind binary inputs or outputs to your functions by setting the dataType field in your function.json to binary:

 {
  "scriptFile": "azure-functions-example.jar",
  "entryPoint": "com.example.MyClass.echo",
  "bindings": [
    {
      "type": "blob",
      "name": "content",
      "direction": "in",
      "dataType": "binary",
      "path": "container/myfile.bin",
      "connection": "ExampleStorageAccount"
    },
  ]
}

その後、開発する関数コード内でそれを使用します。Then use it in your function code:

// Class definition and imports are omitted here
public static String echoLength(byte[] content) {
}

空の入力値は関数の引数として null になる可能性がありますが、空の可能性がある値を処理するには Optional<T> を使用することをお勧めします。Empty input values could be null as your functions argument, but a recommended way to deal with potential empty values is to use Optional<T>.

関数のメソッドのオーバー ロードFunction method overloading

関数のメソッドは、名前は同じだが型は異なるものでオーバーロードできます。You are allowed to overload function methods with the same name but with different types. たとえば、1 つクラスに String echo(String s)String echo(MyType s) の両方を含めることができます。For example, you can have both String echo(String s) and String echo(MyType s) in a class. Azure Functions では、入力の型 (HTTP 入力の場合、MIME の型 text/plainString になりますが、application/jsonMyType を表します) に基づいて呼び出すメソッドが決定されます。Azure Functions decides which method to invoke based on the input type (for HTTP input, MIME type text/plain leads to String while application/json represents MyType).

入力Inputs

Azure Functions では、入力は、トリガー入力と追加入力という 2 つのカテゴリに分けられます。Input are divided into two categories in Azure Functions: one is the trigger input and the other is the additional input. function.json ではこれらは同じではありませんが、Java コードでは同じように使用されます。Although they are different in function.json, the usage is identical in Java code. 次のコード スニペットを例として使用します。Let's take the following code snippet as an example:

package com.example;

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

public class MyClass {
    @FunctionName("echo")
    public static String echo(
        @HttpTrigger(name = "req", methods = { "put" }, authLevel = AuthorizationLevel.ANONYMOUS, route = "items/{id}") String in,
        @TableInput(name = "item", tableName = "items", partitionKey = "Example", rowKey = "{id}", connection = "AzureWebJobsStorage") MyObject obj
    ) {
        return "Hello, " + in + " and " + obj.getKey() + ".";
    }

    public static class MyObject {
        public String getKey() { return this.RowKey; }
        private String RowKey;
    }
}

この関数がトリガーされると、HTTP 要求は String in によって関数に渡されます。When this function is triggered, the HTTP request is passed to the function by String in. エントリは、ルート URL の ID に基づいて Azure Table Storage から取得され、関数の本体で obj として使用されます。An entry will be retrieved from the Azure Table Storage based on the ID in the route URL and made avaialble as obj in the function body.

出力Outputs

出力は、戻り値または出力パラメーターの両方で表現できます。Outputs can be expressed both in return value or output parameters. 出力が 1 つのみの場合は、戻り値を使用することをお勧めします。If there is only one output, you are recommended to use the return value. 複数の出力では、出力パラメーターを使用する必要があります。For multiple outputs, you have to use output parameters.

戻り値は最も単純な出力形式であり、任意の型の値を返すと、Azure Functions ランタイムが実際の型に戻すことを試行します (HTTP 応答など)。Return value is the simplest form of output, you just return the value of any type, and Azure Functions runtime will try to marshal it back to the actual type (such as an HTTP response). 戻り値の出力を定義するには、関数メソッドに出力の注釈を適用できます (注釈の name プロパティは $return にする必要があります)。You could apply any output annotations to the function method (the name property of the annotation has to be $return) to define the return value output.

複数の出力値を生成するには、azure-functions-java-library パッケージに定義されている OutputBinding<T> 型を使用します。To produce multiple output values, use OutputBinding<T> type defined in the azure-functions-java-library package. HTTP 応答と、キューへのメッセージのプッシュも行う必要がある場合は、次のようなコードを記述できます。If you need to make an HTTP response and push a message to a queue as well, you can write something like:

たとえば、BLOB コンテンツのコピー関数は、次のコードのように定義することができます。For example, a blob content copying function could be defined as the following code. @StorageAccount の注釈は、@BlobTrigger@BlobOutput 両方の接続プロパティの重復を防ぐためにここで使用されます。@StorageAccount annotation is used here to prevent the duplicating of the connection property for both @BlobTrigger and @BlobOutput.

package com.example;

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

public class MyClass {
    @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;
    }
}

OutputBinding<byte[]> を使用して (パラメーターの) バイナリ出力値を作成します。戻り値の場合は、単に byte[] を使用します。Use OutputBinding<byte[]> to make a binary output value (for parameters); for return values, just use byte[].

特殊な型Specialized Types

場合によっては、関数で入力と出力を細かく制御する必要があります。Sometimes a function must have detailed control over inputs and outputs. azure-functions-java-core パッケージには、要求情報を操作し、HTTP トリガーの戻り値の状態を調整するための特殊な型が用意されています。Specialized types in the azure-functions-java-core package are provided for you to manipulate request information and tailor the return status of an HTTP trigger:

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

注意

@BindingName 注釈を使用して、HTTP ヘッダーとクエリを取得することもできます。You can also use @BindingName annotation to get HTTP headers and queries. たとえば、@BindingName("name") String query は、HTTP 要求ヘッダーとクエリを反復処理し、その値をメソッドに渡します。For example, @BindingName("name") String query iterates the HTTP request headers and queries and pass that value to the method. たとえば、要求 URL が http://example.org/api/echo?name=test の場合、query"test" になります。For example, query will be "test" if the request URL is http://example.org/api/echo?name=test.

MetadataMetadata

メタデータは、HTTP ヘッダー、HTTP クエリ、トリガー メタデータ などのさまざまなソースから取得されます。Metadata comes from different sources, like HTTP headers, HTTP queries, and trigger metadata. @BindingName 注釈をメタデータ名と一緒に使用して値を取得します。Use the @BindingName annotation together with the metadata name to get the value.

たとえば、次のコード スニペットの queryValue は、要求された URL が http://{example.host}/api/metadata?name=test である場合 "test" になります。For example, the queryValue in the following code snippet will be "test" if the requested URL is http://{example.host}/api/metadata?name=test.

package com.example;

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


public class MyClass {
    @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);
    }
}

実行コンテキストExecution context

Azure Functions 実行環境との対話は、azure-functions-java-library パッケージに定義された ExecutionContext オブジェクト経由で行います。Interact with Azure Functions execution environment via the ExecutionContext object defined in the azure-functions-java-library package. 開発するコード内で呼び出し情報と関数の実行時の情報を使用するには、ExecutionContext オブジェクトを使用します。Use the ExecutionContext object to use invocation information and functions runtime information in your code.

カスタムのログ記録Custom logging

ExecutionContext オブジェクトを介して Functions ランタイム ロガーにアクセスできます。Access to the Functions runtime logger is available through the ExecutionContext object. このロガーは、Azure モニターに関連付けられているため、関数の実行中に発生した警告とエラーのフラグを設定できます。This logger is tied to the Azure monitor and allows you to flag warnings and errors encountered during function execution.

次のコード例は、受信した要求の本文が空の場合に警告メッセージをログに記録します。The following example code logs a warning message when the request body received is empty.


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 の標準出力とエラー ログ、その他の各種アプリケーション ログは、Azure CLI を使用してストリーム配信することができます。You can use the Azure CLI to stream Java standard out and error logging as well as other application logging. まず、Azure CLI を使って、アプリケーション ログを出力するための構成を関数アプリケーションに対して行います。First, 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

セキュリティ上の理由から、キーやトークンなどの秘密情報はソース コードから保護してください。Keep secret information such as keys or tokens out of your source code for security reasons. 関数コードのキーとトークンは、環境変数から読み込んで使用します。Use keys and tokens in your function code by reading them from environment variables.

Azure Functions をローカルに実行する場合に環境変数を設定するには、これらの変数を local.settings.json ファイルに追加することができます。To set environment variables when running Azure Functions locally, you may choose to add these variables to the local.settings.json file. このファイルが関数プロジェクトのルートディレクトリに存在しない場合は、作成することができます。If one is not present in the root directory of your function project, you can create one. このファイルは次のようになります。Here is what the file should look like:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "AzureWebJobsDashboard": ""
  }
}

values マップ内の各キー/値のマッピングは、System.getenv("<keyname>") を呼び出すことによってアクセスできる環境変数として実行時に使用可能になります (たとえば、System.getenv("AzureWebJobsStorage"))。Each key / value mapping in the values map will be made available at runtime as an environment variable, accessible by calling System.getenv("<keyname>"), for example, System.getenv("AzureWebJobsStorage"). キー/値のペアの追加は認められており、そのような手法が推奨されています。Adding additional key / value pairs is accepted and recommended practice.

注意

この方法を実行する場合は、local.settings.json ファイルをリポジトリの無視ファイルに追加して、それがコミットされないようにします。If this approach is taken, be sure to add the local.settings.json file to your repository ignore file, so that it is not committed.

これで、コードがこれらの環境変数に依存するようになったので、Azure portal にサインインして関数アプリ設定で同じキー/値のペアを設定することにより、コードがローカルでテストする場合と Azure にデプロイされた場合とで同等に機能するようになります。With your code now depending on these environment variables, you can sign in to the Azure portal to set the same key / value pairs in your function app settings, so that your code functions equivalently when testing locally and when deployed to Azure.

次の手順Next steps

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