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 are allowed to 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.

トリガーと注釈Triggers and annotations

通常、Azure 関数は、外部トリガーによって呼び出されます。Typically an Azure function is invoked because of an external trigger. 開発する関数は、トリガーとそれに関連付けられている入力を処理し、1 つ以上の出力を生成する必要があります。Your function needs to process that trigger and its associated inputs and produce one or more outputs.

入力と出力をメソッドにバインドするための Java の注釈は、azure-functions-java-core パッケージに含まれています。Java annotations are included in the azure-functions-java-core package to bind input and outputs to your methods. サポートされる入力トリガーと出力バインドの注釈を次の表に示します。The supported input triggers and output binding annotations are included in the following table:

バインドBinding 注釈Annotation
Cosmos DBCosmosDB 該当なしN/A
HTTPHTTP
  • HttpTrigger
  • HttpOutput
Mobile AppsMobile Apps 該当なしN/A
Notification HubsNotification Hubs 該当なしN/A
ストレージ BLOBStorage Blob
  • BlobTrigger
  • BlobInput
  • BlobOutput
ストレージ キューStorage Queue
  • QueueTrigger
  • QueueOutput
ストレージ テーブルStorage Table
  • TableInput
  • TableOutput
TimerTimer
  • TimerTrigger
TwilioTwilio 該当なしN/A

トリガーの入力と出力は、アプリケーション用の function.json に定義することもできます。Trigger inputs and outputs can also be defined in the function.json for your application.

重要

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:

import com.microsoft.azure.serverless.functions.annotation.HttpTrigger;
import com.microsoft.azure.serverless.functions.ExecutionContext;

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"
    }
  ]
}

データ型Data Types

入力データと出力データでは、ネイティブ型、Java 型をカスタマイズした型、azure-functions-java-core パッケージに定義された特別な Azure 型を含む Java のすべての種類のデータ型を使用できます。You are free to use all the 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-core 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 of the function method expects that Java type. この変換によって、自分のコードの中で変換を実装することなく、JSON 入力を関数に渡してコード内で Java 型を操作できます。This conversion allows you to pass JSON inputs into your functions and work with Java types in your code without having to implement the conversion in your own code.

関数への入力として使用される 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) {
}

バイナリ出力をバインドするには、OutputBinding<byte[]> 型を使用します。Use OutputBinding<byte[]> type to make a binary output binding.

関数のメソッドのオーバー ロード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) を設定でき、どちらを呼び出すかは、実際の入力の型を調べることで Azure Functions ランタイムが決定します (HTTP 入力では MIME の種類 text/plainString になり、application/jsonMyType を表します)。For example, you can have both String echo(String s) and String echo(MyType s) in one class, and Azure Functions runtime decides which one to invoke by examine the actual 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.serverless.functions.annotation.BindingName;
import java.util.Optional;

public class MyClass {
    public static String echo(Optional<String> in, @BindingName("item") MyObject obj) {
        return "Hello, " + in.orElse("Azure") + " and " + obj.getKey() + ".";
    }

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

@BindingName 注釈は、function.json に定義されたバインド/トリガーの名前を表す String プロパティを受け入れます。The @BindingName annotation accepts a String property that represents the name of the binding/trigger defined in function.json:

{
  "scriptFile": "azure-functions-example.jar",
  "entryPoint": "com.example.MyClass.echo",
  "bindings": [
    {
      "type": "httpTrigger",
      "name": "req",
      "direction": "in",
      "authLevel": "anonymous",
      "methods": [ "put" ],
      "route": "items/{id}"
    },
    {
      "type": "table",
      "name": "item",
      "direction": "in",
      "tableName": "items",
      "partitionKey": "Example",
      "rowKey": "{id}",
      "connection": "ExampleStorageAccount"
    },
    {
      "type": "http",
      "name": "$return",
      "direction": "out"
    }
  ]
}

したがって、この関数が呼び出されると、HTTP 要求のペイロードは、引数 in に省略可能な String を渡し、引数 obj に Azure Table Storage の MyObject 型を渡します。So when this function is invoked, the HTTP request payload passes an optional String for argument in and an Azure Table Storage MyObject type passed to argument obj. Optional<T> 型を使用して、null にできる関数に入力値を渡して処理します。Use the Optional<T> type to handle inputs into your functions that can be null.

出力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). functions.json では、出力バインドの名前として $return を使用します。In functions.json, you use $return as the name of the output binding.

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

package com.example;

import com.microsoft.azure.serverless.functions.OutputBinding;
import com.microsoft.azure.serverless.functions.annotation.BindingName;

public class MyClass {
    public static String echo(String body, 
    @QueueOutput(queueName = "messages", connection = "AzureWebJobsStorage", name = "queue") OutputBinding<String> queue) {
        String result = "Hello, " + body + ".";
        queue.setValue(result);
        return result;
    }
}

function.json に出力バインドを定義する必要があります。which should define the output binding in function.json:

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

特殊な型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 a 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.serverless.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);
    }
}

Functions の実行コンテキストFunctions execution context

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

ログの記録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.serverless.functions.annotation.HttpTrigger;
import com.microsoft.azure.serverless.functions.ExecutionContext;

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

環境変数Environment variables

セキュリティ上の理由で、ソースコードから機密な情報を取り除くことがしばしば求められます。 It is often desirable to extract out secret information from source code for security reasons. これにより、資格情報を他の開発者に誤って露出することなく、コードをソースコードリポジトリに発行できます。This allows code to be published to source code repos without accidentally providing credentials to other developers. これは、Azure Functions をローカルで実行する場合と、Azure に関数をデプロイする場合の両方で環境変数を使用することによって簡単に実現できます。This can be achieved simply by using environment variables, both when running Azure Functions locally, and when deploying your functions to Azure.

Azure Functions をローカルに実行する場合に環境変数を手早く設定するには、これらの変数を local.settings.json ファイルに追加することができます。To easily 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, feel free to 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 consider whether adding 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 log 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

詳細については、次のリソースを参照してください。For more information, see the following resources: