Version:

Funqy HTTP binding (standalone)

このガイドでは、Funqyをスタンドアロンサービスとしてデプロイし、HTTPを使ってFunqy関数を呼び出す方法をクイックスタートコードで説明します。

The Funqy HTTP binding is not a replacement for REST over HTTP. Because Funqy needs to be portable across a lot of different protocols and function providers its HTTP binding is very minimalistic and you will lose REST features like linking and the ability to leverage HTTP features like cache-control and conditional GETs. You may want to consider using Quarkus’s Jakarta REST, Spring MVC, or Vert.x Web Reactive Routes support instead, although Funqy will have less overhead than these alternatives (except Vert.x which is still super fast).

前提条件

このガイドを完成させるには、以下が必要です:

約15分
IDE
JDK 17+がインストールされ、 JAVA_HOME が適切に設定されていること
Apache Maven 3.9.16
使用したい場合は、 Quarkus CLI
Funqy の基礎を読む。短時間で読めます!

クイックスタート

git clone https://github.com/quarkusio/quarkus-quickstarts.git で Git リポジトリーをクローンします。または、https://github.com/quarkusio/quarkus-quickstarts/archive/main.zip[アーカイブ] をダウンロードします。

ソリューションは funqy-http-quickstart ディレクトリにあります。

コード

Javaコードを見ると、HTTP固有のAPIがないことがわかります。単純な Java メソッドに @Funq とアノテーションが付けられているだけです。シンプルで、簡単で、わかりやすいです。

Maven 依存関係

Funqy HTTP Function を書くには、 quarkus-funqy-http 依存関係をQuarkus pom.xml ファイルにインクルードするだけでよいです。

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-funqy-http</artifactId>
</dependency>

プロジェクトのビルド

mvn clean quarkus:dev

これにより、Quarkus 開発モードで Function が起動されます。

Funqy HTTP Function の実行

Function を実行するための URL パスは、Function 名です。例えば、Function 名が foo の場合、Function を実行する URL パスは /foo になります。

HTTP POST または GET メソッドを使用して Function を呼び出すことができます。Function の戻り値は、Jackson JSON ライブラリを使用して JSON にマーシャルされます。Jackson アノテーションを使用することができます。Function に入力パラメーターがある場合、POST 呼び出しは入力タイプとして JSON を使用しなければなりません。ここでもJackson はアンマーシャリングに使用されます。

ブラウザで http://localhost:8080/hello を開くことで、 PrimitiveFunctions.java で定義されている hello 関数を呼び出すことが出来ます。

クイックスタート内の他の関数を呼び出すにはHTTP POSTが必要です。 GreetingFunction.java で定義された greet 関数を実行するには、このcurlスクリプトを呼び出します。

curl "http://localhost:8080/greet" \
-X POST \
-H "Content-Type: application/json" \
-d '{"name":"Bill"}'

プリミティブ型は、標準的なJSONマッピングを使用して入力として渡すこともできます。 PrimitiveFunctions.java で定義された toLowerCase 関数を実行するには、次のcurlスクリプトを実行します：

curl "http://localhost:8080/toLowerCase" \
-X POST \
-H "Content-Type: application/json" \
-d '"HELLO WORLD"'

PrimitiveFunctions.java で定義されている double 関数を実行するには、次のcurlスクリプトを実行します：

curl "http://localhost:8080/double" \
-X POST \
-H "Content-Type: application/json" \
-d '2'

GET クエリパラメーターのマッピング

GETリクエストのために、Funqy HTTPバインディングは、Function の入力パラメーターのためのクエリパラメーターマッピングも提供しています。Bean スタイル・クラスと java.util.Map だけが入力パラメーターに使用できます。Bean スタイル・クラスでは、クエリ・パラメーター名は Bean クラスのプロパティーにマッピングされます。以下は、単純な Map の例です。

@Funq
public String hello(Map<String, Integer> map) {
...
}

キー値は、プリミティブ型(char を除く)か String でなければなりません。値は、プリミティブ型 (char を除く)、 String 、 OffsetDateTime 、または複雑な Bean スタイルのクラスを使用できます。上記の例に対して、対応する curl リクエストを以下に示します。

curl "http://localhost:8080/a=1&b=2"

hello Function の map 入力パラメーターは、 a →1, b →2 というキーバリューペアを持ちます。

Bean スタイルクラスを入力パラメーター型として使用することもできます。以下に例を示します。

public class Person {
    String first;
    String last;

    public String getFirst() { return first; }
    public void setFirst(String first) { this.first = first; }
    public String getLast() { return last; }
    public void setLast(String last) { this.last = last; }
}

public class MyFunctions {
    @Funq
    public String greet(Person p) {
       return "Hello " + p.getFirst() + " " + p.getLast();
    }
}

プロパティーの値は、 char 以外の任意のプリミティブ型にすることができます。また、 String や OffsetDateTime も可能です。 OffsetDateTime クエリのパラメーター値は ISO-8601 形式でなければなりません。

HTTP GET とクエリパラメーターを使用して呼び出すことができます。

curl "http://localhost:8080/greet?first=Bill&last=Burke"

上記のリクエストでは、クエリパラメーター名が入力クラスの対応するプロパティーにマッピングされています。

入力クラスは、入れ子になった Bean クラスを持つこともできます。前の例を拡張します。

public class Family {
    private Person dad;
    private Person mom;

    public Person getDad() { return dad; }
    public void setDad(Person dad) { this.dad = dad; }
    public Person getMom() { return mom; }
    public void setMom(Person mom) { this.mom = mom; }
}

public class MyFunctions {
    @Funq
    public String greet(Family family) {
       ...
    }
}

この場合、入れ子になった値のクエリパラメーターは . 表記法を使用します。例えば、以下のようになります。

curl "http://localhost:8080/greet?dad.first=John&dad.last=Smith&mom.first=Martha&mom.last=Smith"

java.util.List と Set もプロパティー値としてサポートされています。例えば

public class Family {
    ...

    List<String> pets;
}

public class MyFunctions {
    @Funq
    public String greet(Family family) {
       ...
    }
}

GETリクエストを実行するためには、 pets クエリパラメーターを複数回リストアップするだけです。

curl "http://localhost:8080/greet?pets=itchy&pets=scratchy"

より複雑な型の場合、 List および Set のメンバーは、クエリパラメーターに識別子を持つ必要があります。例えば、以下のようになります。

public class Family {
    ...

    List<Person> kids;
}

public class MyFunctions {
    @Funq
    public String greet(Family family) {
       ...
    }
}

それぞれの kids クエリーパラメーターは、参照している kid を識別する必要があります。これにより、ランタイムはどのプロパティー値がリストのどのメンバーに属するかを把握することができます。これが curl リクエストです。

curl "http://localhost:8080/greet?kids.1.first=Buffy&kids.2.first=Charlie"

上記のURLでは、リストの対象メンバーを識別するために 1 と 2 という値を使用していますが、任意の一意の文字列を使用することができます。

プロパティーは java.util.Map でもよいです。マップのキーは、任意のプリミティブ型と String が利用できます。例えば、以下のようになります。

public class Family {
    ...

    Map<String, String> address;
}

public class MyFunctions {
    @Funq
    public String greet(Family family) {
       ...
    }
}

対応する呼び出しは次のようになります。

curl "http://localhost:8080/greet?address.state=MA&address.city=Boston"

Map の値が複雑な型であれば、最後に set するプロパティーを追加して表記を続けるだけです。

public class Family {
    ...

    Map<String, Address> addresses;
}

public class MyFunctions {
    @Funq
    public String greet(Family family) {
       ...
    }
}

curl "http://localhost:8080/greet?addresses.home.state=MA&addresses.home.city=Boston"