CloudEvent 関数

CloudEvent 関数はイベント ドリブン関数の 1 つです。CloudEvent 関数は、Pub/Sub トピックのメッセージ、Cloud Storage バケットの変更、Firebase イベントなどのイベントに応答して間接的に呼び出されます。

CloudEvent の関数は、バックグラウンド関数と概念的によく似ています。この 2 つの主な違いは次のとおりです。CloudEvent の関数は CloudEvents という業界標準のイベント形式を使用します。また、Cloud Functions の関数は HTTP リクエストを使用して CloudEvent 関数を呼び出します。これは任意の場所で再現できます。このような違いがあるため、CloudEvent 関数はコンピューティング イベント間でシームレスに移動できます。

ベータ版: ベータ版トリガーによって生成された CloudEvents は、形式が変更される可能性があります。Source 属性と Subject 属性、追加の拡張属性、データ（ペイロード）形式は、すべて変更される可能性があります。

サポート ランタイム

次のランタイムは CloudEvent 関数をサポートしています。

言語	バージョン
PHP Beta	すべて
C# Beta	すべて
Ruby Beta	すべて

注: CloudEvent 関数をサポートしていないランタイム バージョンではバックグラウンド関数がサポートされています。

関数のパラメータ

CloudEvent 関数には、関数の実行をトリガーしたイベントのプロパティとメタデータが格納された単一の cloudEvent 引数が渡されます。受信した CloudEvent は、Functions Framework ライブラリを使用して言語固有の以下の表現に変換されます。

C#

cloudEvent パラメータは、次のプロパティを含む CloudEvent オブジェクトとして関数に渡されます。

プロパティ	型	説明
Id	String	イベントの一意の ID。
Source	Uri	影響を受ける Google Cloud エンティティ。形式は /[SERVICE_DOMAIN_NAME]/[RESOURCE]/ です。
Type	String	受信したイベントの CloudEvent タイプ。
Time	null 許容 DateTimeOffset	イベント発生時のタイムスタンプ。
SpecVersion	CloudEventsSpecVersion	イベントの作成に使用される CloudEvents 仕様のバージョン。
Data	Object	イベントタイプ固有のデータを含む object。
Subject	null 許容 String	subject の値は、トリガーされるイベントのタイプによって異なります。たとえば、基盤となるイベントが Cloud Storage オブジェクトを参照している場合、オブジェクトの場所に設定されます（形式は objects/path/to/object）。一部のイベントでは subject が設定されません。その場合、このプロパティは null になります。

Ruby

cloudEvent パラメータは、次のプロパティを含む CloudEvents::Event::V1 オブジェクトとして関数に渡されます。

プロパティ	型	説明
cloudEvent.id	String	イベントの一意の ID。
cloudEvent.source	URI	影響を受ける Google Cloud エンティティ。形式は /[SERVICE_DOMAIN_NAME]/[RESOURCE]/ です。
cloudEvent.type	String	受信したイベントの CloudEvent タイプ。
cloudEvent.time	DateTime	イベント発生時のタイムスタンプ。
cloudEvent.specversion	String	イベントの作成に使用される CloudEvents 仕様のバージョン。
cloudEvent.data	Hash	イベントタイプ固有のデータを含む Hash。
cloudEvent.subject	String または Nil	subject の値は、トリガーされるイベントのタイプによって異なります。たとえば、基盤となるイベントが Cloud Storage オブジェクトを参照している場合、オブジェクトの場所に設定されます（形式は objects/path/to/object）。一部のイベントでは subject が設定されません。その場合、このプロパティは Nil になります。

PHP

cloudEvent パラメータは、次のプロパティを含む CloudEvent オブジェクトとして関数に渡されます。

関数	型	説明
cloudEvent->getId()	string	イベントの一意の ID。
cloudEvent->getSource()	string	影響を受ける Google Cloud エンティティ。形式は /[SERVICE_DOMAIN_NAME]/[RESOURCE]/ です。
cloudEvent->getType()	string	受信したイベントの CloudEvent タイプ。
cloudEvent->getTime()	?string	イベント発生時のタイムスタンプ。
cloudEvent->getSpecVersion()	string	イベントの作成に使用される CloudEvents 仕様のバージョン。
cloudEvent->getSubject()	?string	subject の値は、トリガーされるイベントのタイプによって異なります。たとえば、基盤となるイベントが Cloud Storage オブジェクトを参照している場合、オブジェクトの場所に設定されます（形式は objects/path/to/object）。一部のイベントでは subject が設定されません。その場合、このプロパティは null になります。
cloudEvent->getData()	Object	イベントタイプ固有のデータを含む object。

使用例

以下の例は、Pub/Sub と Cloud Storage からイベントを処理する方法を示しています。異なるソースからのイベントを処理する方法については、Cloud Functions の呼び出しをご覧ください。

Pub/Sub の例

この例では、Pub/Sub イベントで CloudEvent 関数をトリガーします。Pub/Sub トピックにメッセージが公開されるたびに関数が呼び出され、メッセージから派生したデータを含む挨拶がログに書き込まれます。

C#

functions/helloworld/HelloPubSub/Function.cs

GitHub で表示 フィードバック

using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.PubSub.V1;
using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks;

namespace HelloPubSub
{
    public class Function : ICloudEventFunction<MessagePublishedData>
    {
        private readonly ILogger _logger;

        public Function(ILogger<Function> logger) =>
            _logger = logger;

        public Task HandleAsync(CloudEvent cloudEvent, MessagePublishedData data, CancellationToken cancellationToken)
        {
            string nameFromMessage = data.Message?.TextData;
            string name = string.IsNullOrEmpty(nameFromMessage) ? "world" : nameFromMessage;
            _logger.LogInformation("Hello {name}", name);
            return Task.CompletedTask;
        }
    }
}

Ruby

functions/helloworld/pubsub/app.rb

GitHub で表示 フィードバック

require "functions_framework"
require "base64"

FunctionsFramework.cloud_event "hello_pubsub" do |event|
  # The event parameter is a CloudEvents::Event::V1 object.
  # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
  name = Base64.decode64 event.data["message"]["data"] rescue "World"

  # A cloud_event function does not return a response, but you can log messages
  # or cause side effects such as sending additional events.
  logger.info "Hello, #{name}!"
end

PHP

functions/helloworld_pubsub/index.php

GitHub で表示 フィードバック

use CloudEvents\V1\CloudEventInterface;
use Google\CloudFunctions\FunctionsFramework;

// Register the function with Functions Framework.
// This enables omitting the `FUNCTIONS_SIGNATURE_TYPE=cloudevent` environment
// variable when deploying. The `FUNCTION_TARGET` environment variable should
// match the first parameter.
FunctionsFramework::cloudEvent('helloworldPubsub', 'helloworldPubsub');

function helloworldPubsub(CloudEventInterface $event): void
{
    $log = fopen(getenv('LOGGER_OUTPUT') ?: 'php://stderr', 'wb');

    $cloudEventData = $event->getData();
    $pubSubData = base64_decode($cloudEventData['message']['data']);

    $name = $pubSubData ? htmlspecialchars($pubSubData) : 'World';
    fwrite($log, "Hello, $name!" . PHP_EOL);
}

Pub/Sub イベントでトリガーされる Cloud Functions をデプロイする方法については、Pub/Sub トリガーと Pub/Sub チュートリアルをご覧ください。

Cloud Storage の例

この例では、Cloud Storage イベントで CloudEvent 関数をトリガーします。オブジェクトが Cloud Storage バケットに作成されるたびに関数が呼び出され、変更に関するメッセージがログに記録されます。

C#

functions/helloworld/HelloGcs/Function.cs

GitHub で表示 フィードバック

using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.Storage.V1;
using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks;

namespace HelloGcs
{
     /// <summary>
     /// Example Cloud Storage-triggered function.
     /// This function can process any event from Cloud Storage.
     /// </summary>
    public class Function : ICloudEventFunction<StorageObjectData>
    {
        private readonly ILogger _logger;

        public Function(ILogger<Function> logger) =>
            _logger = logger;

        public Task HandleAsync(CloudEvent cloudEvent, StorageObjectData data, CancellationToken cancellationToken)
        {
            _logger.LogInformation("Event: {event}", cloudEvent.Id);
            _logger.LogInformation("Event Type: {type}", cloudEvent.Type);
            _logger.LogInformation("Bucket: {bucket}", data.Bucket);
            _logger.LogInformation("File: {file}", data.Name);
            _logger.LogInformation("Metageneration: {metageneration}", data.Metageneration);
            _logger.LogInformation("Created: {created:s}", data.TimeCreated?.ToDateTimeOffset());
            _logger.LogInformation("Updated: {updated:s}", data.Updated?.ToDateTimeOffset());
            return Task.CompletedTask;
        }
    }
}

Ruby

functions/helloworld/storage/app.rb

GitHub で表示 フィードバック

require "functions_framework"

FunctionsFramework.cloud_event "hello_gcs" do |event|
  # This function supports all Cloud Storage events.
  # The `event` parameter is a CloudEvents::Event::V1 object.
  # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
  payload = event.data

  logger.info "Event: #{event.id}"
  logger.info "Event Type: #{event.type}"
  logger.info "Bucket: #{payload['bucket']}"
  logger.info "File: #{payload['name']}"
  logger.info "Metageneration: #{payload['metageneration']}"
  logger.info "Created: #{payload['timeCreated']}"
  logger.info "Updated: #{payload['updated']}"
end

PHP

functions/helloworld_storage/index.php

GitHub で表示 フィードバック

use CloudEvents\V1\CloudEventInterface;
use Google\CloudFunctions\FunctionsFramework;

// Register the function with Functions Framework.
// This enables omitting the `FUNCTIONS_SIGNATURE_TYPE=cloudevent` environment
// variable when deploying. The `FUNCTION_TARGET` environment variable should
// match the first parameter.
FunctionsFramework::cloudEvent('helloGCS', 'helloGCS');

function helloGCS(CloudEventInterface $cloudevent)
{
    // This function supports all Cloud Storage event types.
    $log = fopen(getenv('LOGGER_OUTPUT') ?: 'php://stderr', 'wb');
    $data = $cloudevent->getData();
    fwrite($log, 'Event: ' . $cloudevent->getId() . PHP_EOL);
    fwrite($log, 'Event Type: ' . $cloudevent->getType() . PHP_EOL);
    fwrite($log, 'Bucket: ' . $data['bucket'] . PHP_EOL);
    fwrite($log, 'File: ' . $data['name'] . PHP_EOL);
    fwrite($log, 'Metageneration: ' . $data['metageneration'] . PHP_EOL);
    fwrite($log, 'Created: ' . $data['timeCreated'] . PHP_EOL);
    fwrite($log, 'Updated: ' . $data['updated'] . PHP_EOL);
}

Cloud Storage イベントでトリガーされる CloudEvent 関数をデプロイする方法については、Cloud Storage トリガーと Cloud Storage チュートリアルをご覧ください。

Eventarc を使用して、ターゲットのCloud Run サービスにイベント（CloudEvents 形式）を配信する方法については、Cloud Run のトリガーを作成するをご覧ください。

ヒントとアドバイス

イベントのロギング

機密情報が含まれている可能性があるため、イベント コンテンツは自動的に記録されません。イベントの内容をログに記録する場合は、ログの作成、表示、処理の説明に従って明示的に処理を行う必要があります。

CloudEvent 関数の終了

CloudEvent 関数によってバックグラウンド タスクが作成される場合は、エラーや未定義の動作を回避するため、関数から戻る前にこれらのタスクを解決する必要があります。

自動再試行

失敗した呼び出しを自動的に再試行するように CloudEvent 関数を構成できます。詳細については、イベント ドリブン関数の再試行をご覧ください。

次のステップ

• Cloud Functions をデプロイする。
• Pub/Sub トリガー関数を呼び出す。
• Cloud Storage トリガー関数を呼び出す。
• Cloud Functions と Pub/Sub のチュートリアル。
• Cloud Functions と Cloud Storage のチュートリアル。