The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Funqy Google Cloud Functions

このガイドでは、Funqy 関数を Google Cloud Functions にデプロイする方法をクイックスタートコードで説明しています。

この技術は、previewと考えられています。

preview では、下位互換性やエコシステムでの存在は保証されていません。具体的な改善には設定や API の変更が必要になるかもしれませんが、 stable になるための計画は現在進行中です。フィードバックは メーリングリストGitHub の課題管理 で受け付けています。

For a full list of possible statuses, check our FAQ entry.

前提条件

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

Google Cloud にログイン

Login to Google Cloud is necessary for deploying the application. It can be done as follows:

gcloud auth login

クイックスタート

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

このソリューションは funqy-google-cloud-functions-quickstart ディレクトリー にあります。

Maven デプロイメントプロジェクトの作成

quarkus-funqy-google-cloud-functions のエクステンションを持つアプリケーションを作成します。 以下の Maven コマンドを使って作成します。

CLI
quarkus create app org.acme:funqy-google-cloud-functions \
    --extension=funqy-google-cloud-functions \
    --no-code
cd funqy-google-cloud-functions

Gradleプロジェクトを作成するには、 --gradle または --gradle-kotlin-dsl オプションを追加します。

Quarkus CLIのインストール方法については、Quarkus CLIガイドをご参照ください。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:2.11.1.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=funqy-google-cloud-functions \
    -Dextensions="funqy-google-cloud-functions" \
    -DnoCode
cd funqy-google-cloud-functions

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

コード

There is nothing special about the code and more importantly nothing Google Cloud specific. Funqy functions can be deployed to many environments and Google Cloud Functions is one of them.

関数の選択

Google Cloud Functions のデプロイごとにエクスポートできる Funqy 関数は 1 つだけです。プロジェクト内に @Funq でアノテーションされたメソッドが 1 つしかない場合は、心配ありません。プロジェクト内に複数の関数が定義されている場合は、Quarkus application.properties 内で関数を選択する必要があります。

quarkus.funqy.export=greet

あるいは、gcloud cliを使って Google Cloud Function を作成する際に、環境変数 QUARKUS_FUNQY_EXPORT を設定することもできます。

ビルドとデプロイ

Build the project:

CLI
quarkus build
Maven
./mvnw clean package
Gradle
./gradlew build

これでコードがコンパイルされ、パッケージ化されます。

Creating the functions

In this example, we will create two background functions and a cloud events function. Background functions allow you to react to Google Cloud events like PubSub messages, Cloud Storage events, Firestore events, …​ Cloud events functions allow you to react to supported events using the Cloud Events specification.

Quarkus supports Cloud Functions gen 1 and gen 2. For an overview of Cloud Functions gen 2 see this page on the Google Cloud Functions documentation. To use gen 2 you must use gcloud beta command and add the --gen2 parameter.
import javax.inject.Inject;

import io.cloudevents.CloudEvent;
import io.quarkus.funqy.Funq;
import io.quarkus.funqy.gcp.functions.event.PubsubMessage;
import io.quarkus.funqy.gcp.functions.event.StorageEvent;

public class GreetingFunctions {

    @Inject GreetingService service; (1)

    @Funq (2)
    public void helloPubSubWorld(PubsubMessage pubSubEvent) {
        String message = service.hello(pubSubEvent.data);
        System.out.println(pubSubEvent.messageId + " - " + message);
    }

    @Funq (3)
    public void helloGCSWorld(StorageEvent storageEvent) {
        String message = service.hello("world");
        System.out.println(storageEvent.name + " - " + message);
    }

    @Funq (4)
    public void helloCloudEvent(CloudEvent cloudEvent) {
        System.out.println("Receive event Id: " + cloudEvent.getId());
        System.out.println("Receive event Subject: " + cloudEvent.getSubject());
        System.out.println("Receive event Type: " + cloudEvent.getType());
        System.out.println("Receive event Data: " + new String(cloudEvent.getData().toBytes()));
        System.out.println("Be polite, say " + service.hello("world"));
    }
}
関数の戻り値の型は、Mutiny 反応型も可能です。
  1. インジェクションは Cloud Function 関数クラスの中で動作します。

  2. これは、io.quarkus.funqy.gcp.functions.event.PubsubMessage をパラメーターとするバックグルアンド関数で、PubSub メッセージをデシリアライズする便利なクラスです。

  3. これは、io.quarkus.funqy.gcp.functions.event.StorageEvent をパラメーターとするバックグラウンド関数で、Google Storage イベントをデシリアライズするための便利なクラスです。

  4. This is a cloud events functions, that takes as parameter a io.cloudevents.CloudEvent, inside it the getData() method will return the event content, storage event in this case.

io.quarkus.funqy.gcp.functions.event パッケージ内の Google Cloud の共通イベントをデシリアライズするための便利なクラスを提供しています。これらのクラスは必須ではなく、任意のオブジェクトを使用することができます。

プロジェクトには複数の関数が含まれているので、どの関数を、application.properties 内の以下のプロパティーからデプロイする必要があるかを指定する必要があります。

quarkus.funqy.export=helloPubSubWorld

アプリケーションのビルドと Google Cloud へのデプロイ

アプリケーションをビルドするには、 mvn clean package からアプリケーションをパッケージ化することができます。target/deployment リポジトリー内には、クラスとすべての依存関係が含まれた単一の JAR があります。

Then you will be able to use gcloud to deploy your function to Google Cloud. The gcloud command will be different depending on which event you want to trigger.

初めて gcloud beta functions deploy を実行すると、以下のようなエラーメッセージが表示されます。

ERROR: (gcloud.functions.deploy) OperationError: code=7, message=Build Failed: Cloud Build has not been used in project <project_name> before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/cloudbuild.googleapis.com/overview?project=<my-project> then retry.

これは、Cloud Build がまだ有効化されていないことを意味します。このエラーを解決するには、エラーに表示されている URL を開き指示に従った後、数分待ってからコマンドを再試行してください。

バックグラウンド関数 - PubSub

このコマンドを使用して、Google Cloud Functions にデプロイします。

gcloud functions deploy quarkus-example-funky-pubsub \
  --entry-point=io.quarkus.funqy.gcp.functions.FunqyBackgroundFunction \
  --runtime=java11 --trigger-resource hello_topic --trigger-event google.pubsub.topic.publish \
  --source=target/deployment

Quarkus をブートストラップするのはこのクラスなので、エントリーポイントは常に io.quarkus.funqy.gcp.functions.FunqyBackgroundFunction である必要があります。

You can also use the new Java 17 runtime by using --runtime=java17 in the gcloud command line.

--trigger-resource オプションは PubSub トピックの名前を定義し、--trigger-event google.pubsub.topic.publish オプションは、この関数がトピック内のすべてのメッセージ公開によってトリガーされることを定義します。

この関数にイベントをトリガーするには、 gcloud functions call コマンドを使用します。

gcloud functions call quarkus-example-funky-pubsub —data ‘{“data”:”Pub/Sub”}’

The --data '{"data":"Hello, Pub/Sub"}' option allows you to specify the message to be sent to PubSub.

バックグラウンド関数 - クラウドストレージ

関数をデプロイする前に、バケットを作成する必要があります。

gsutil mb gs://quarkus-hello

そして、このコマンドを使って Google Cloud Functions にデプロイします。

gcloud functions deploy quarkus-example-funky-storage \
  --entry-point=io.quarkus.funqy.gcp.functions.FunqyBackgroundFunction \
  --runtime=java11 --trigger-resource quarkus-hello --trigger-event google.storage.object.finalize \
  --source=target/deployment

Quarkus をブートストラップするのはこのクラスなので、エントリーポイントは常に io.quarkus.funqy.gcp.functions.FunqyBackgroundFunction である必要があります。

You can also use the new Java 17 runtime by using --runtime=java17 in the gcloud command line.

--trigger-resource オプションは Cloud Storage のバケット名を定義します。また、--trigger-event google.storage.object.finalize オプションはこのバケット内のすべての新規ファイルに対してこの関数がトリガーされることを定義します。

この関数にイベントをトリガーするには、 gcloud functions call コマンドを使用します。

gcloud functions call quarkus-example-funky-storage --data '{"name":"test.txt"}'

--data '{"name":"test.txt"}' オプションでは、偽のファイル名を指定することができ、この名前に対して偽のクラウドストレージイベントが作成されます。

また、Web コンソールのコマンドラインを使用して、Cloud Storage にファイルを追加するだけでも簡単にできます。

Cloud Events Functions - Cloud Storage

Cloud Events Function is a feature of Cloud Functions gen 2 only.

関数をデプロイする前に、バケットを作成する必要があります。

gsutil mb gs://quarkus-hello

そして、このコマンドを使って Google Cloud Functions にデプロイします。

gcloud beta functions deploy quarkus-example-cloud-event --gen2 \
  --entry-point=io.quarkus.funqy.gcp.functions.FunqyCloudEventsFunction \
  --runtime=java11 --trigger-bucket=example-cloud-event --source=target/deployment

The entry point always needs to be io.quarkus.funqy.gcp.functions.FunqyCloudEventsFunction as it will be this class that will bootstrap Quarkus.

You can also use the new Java 17 runtime by using --runtime=java17 in the gcloud command line.

The --trigger-bucket= option defines the name of the Cloud Storage bucket.

To trigger the event, you can send a file to the GCS example-cloud-event bucket.

ローカルでのテスト

関数をローカルでテストする最も簡単な方法は、Cloud Function invoker JAR を使用することです。

以下のコマンドで Maven 経由でダウンロードできます。

mvn dependency:copy \
    -Dartifact='com.google.cloud.functions.invoker:java-function-invoker:1.1.0' \
    -DoutputDirectory=.

Before using the invoker, you first need to build your function via:

CLI
quarkus build
Maven
./mvnw clean package
Gradle
./gradlew build

その後、これは、ローカルで関数を起動するために使用することができます。このコマンドは、関数の種類とイベントの種類に依存します。

バックグラウンド関数 - PubSub

バックグラウンド関数の場合は、 io.quarkus.funqy.gcp.functions.FunqyBackgroundFunction のターゲットクラスで invoker を起動します。

java -jar java-function-invoker-1.1.0.jar \
  --classpath target/funqy-google-cloud-functions-1.0.0-SNAPSHOT-runner.jar \
  --target io.quarkus.funqy.gcp.functions.FunqyBackgroundFunction
--classpath パラメーターには、関数クラスと Quarkus 関連のすべてのクラスを含む、先の手順でパッケージ化された JAR を指定する必要があります。

起動後、HTTP 呼び出しにイベントを含むペイロードを付与することでバックグラウンド関数を呼び出すことができます。

curl localhost:8080 -d '{"data":{"data":"world"}}'

これは、PubSub のバックグラウンド関数を PubSubMessage で呼び出します {"data":"hello”}

バックグラウンド関数 - クラウドストレージ

バックグラウンド関数の場合は、 io.quarkus.funqy.gcp.functions.FunqyBackgroundFunction のターゲットクラスで invoker を起動します。

java -jar java-function-invoker-1.1.0.jar \
  --classpath target/funqy-google-cloud-functions-1.0.0-SNAPSHOT-runner.jar \
  --target io.quarkus.funqy.gcp.functions.FunqyBackgroundFunction
--classpath パラメーターには、関数クラスと Quarkus 関連のすべてのクラスを含む、先の手順でパッケージ化された JAR を指定する必要があります。

起動後、HTTP 呼び出しにイベントを含むペイロードを付与することでバックグラウンド関数を呼び出すことができます。

curl localhost:8080 -d '{"data":{"name":"text"}}'

これは、Cloud Storage のイベント {"name":"file.txt"} (file.txt ファイル上のイベント) で PubSub のバックグラウンド関数を呼び出します。

Cloud Events Functions - Cloud Storage

Cloud Events Function is a feature of Cloud Functions gen 2 only.

For cloud events functions, you launch the invoker with a target class of io.quarkus.funqy.gcp.functions.FunqyCloudEventsFunction`.

java -jar java-function-invoker-1.1.0.jar \
  --classpath target/funqy-google-cloud-functions-1.0.0-SNAPSHOT-runner.jar \
  --target io.quarkus.funqy.gcp.functions.FunqyBackgroundFunction
--classpath パラメーターには、関数クラスと Quarkus 関連のすべてのクラスを含む、先の手順でパッケージ化された JAR を指定する必要があります。

起動後、HTTP 呼び出しにイベントを含むペイロードを付与することでバックグラウンド関数を呼び出すことができます。

curl localhost:8080 \
  -X POST \
  -H "Content-Type: application/json" \
  -H "ce-id: 123451234512345" \
  -H "ce-specversion: 1.0" \
  -H "ce-time: 2020-01-02T12:34:56.789Z" \
  -H "ce-type: google.cloud.storage.object.v1.finalized" \
  -H "ce-source: //storage.googleapis.com/projects/_/buckets/MY-BUCKET-NAME" \
  -H "ce-subject: objects/MY_FILE.txt" \
  -d '{
        "bucket": "MY_BUCKET",
        "contentType": "text/plain",
        "kind": "storage#object",
        "md5Hash": "...",
        "metageneration": "1",
        "name": "MY_FILE.txt",
        "size": "352",
        "storageClass": "MULTI_REGIONAL",
        "timeCreated": "2020-04-23T07:38:57.230Z",
        "timeStorageClassUpdated": "2020-04-23T07:38:57.230Z",
        "updated": "2020-04-23T07:38:57.230Z"
      }'

This will call your cloud events function with an event on the "MY_FILE.txt file.

次のステップ

If you are looking for JAX-RS, Servlet or Vert.x support for Google Cloud Functions, we have it thanks to our Google Cloud Functions HTTP binding.