バージョン:

Funqy HTTPバインディング (スタンドアロン)

前提条件
クイックスタート
コード
Maven 依存関係
プロジェクトのビルド
Funqy HTTP Function の実行
GET クエリパラメーターのマッピング

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

FunqyのHTTPバインディングはHTTP上のRESTの代わりではありません。Funqyは多くの異なるプロトコルや Function プロバイダに対してポータブルである必要があるので、HTTPバインディングは非常にミニマムで、リンクのようなREST機能やキャッシュコントロールや条件付きGETのようなHTTPを利用する機能を失うことになります。代わりにQuarkusのJakarta REST、Spring MVC、またはVert.x Web Reactive Routesのサポートを使用することを検討すると良いでしょう。しかしながら、Funqy はこれらの選択肢と比べてオーバーヘッドが小さいでしょう(例外として Vert.x はそれでもすごく早いですが)。

前提条件

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

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

クイックスタート

Gitレポジトリをクローンするか git clone https://github.com/quarkusio/quarkus-quickstarts.git 、アーカイブをダウンロードします。

The solution is located in the funqy-http-quickstart directory.

コード

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 はアンマーシャリングに使用されます。

You can invoke the hello function defined in PrimitiveFunctions.java by pointing your browser to http://localhost:8080/hello

Invoking the other functions in the quickstart requires an HTTP POST. To execute the greet function defined in GreetingFunction.java invoke this curl script.

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

Primitive types can also be passed as input using the standard JSON mapping for them. To execute the toLowerCase function defined in PrimitiveFunctions.java invoke this curl script:

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

To execute the double function defined in PrimitiveFunctions.java invoke this curl script:

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"