CloudEvent 関数

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

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

サポート ランタイム

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

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

関数のパラメータ

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

C#

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

プロパティ 説明
cloudEvent.Id String イベントの一意の ID。
cloudEvent.Source uri 影響を受ける Google Cloud エンティティ。形式は /[SERVICE_DOMAIN_NAME]/[RESOURCE]/ です。
cloudEvent.Type String 受信したイベントの CloudEvent タイプ。
cloudEvent.Time DateTime イベント発生時のタイムスタンプ。
cloudEvent.SpecVersion CloudEventsSpecVersion イベントの作成に使用される CloudEvents 仕様のバージョン。
cloudEvent.data Object イベントタイプ固有のデータを含む object
cloudEvent.subject null 可能性 String 基盤となるイベントが Cloud Storage オブジェクトを参照している場合、オブジェクトの場所に設定されます(形式は objects/path/to/object)。基盤となるイベントがこのようなオブジェクトを参照していない場合、このプロパティは 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 基盤となるイベントが Cloud Storage オブジェクトを参照している場合、オブジェクトの場所に設定されます(形式は objects/path/to/object)。基盤となるイベントがこのようなオブジェクトを参照していない場合、このプロパティは Nil になります。Cloud Storage イベントをご覧ください。

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 基盤となるイベントが Cloud Storage オブジェクトを参照している場合、オブジェクトの場所に設定されます(形式は objects/path/to/object)。基盤となるイベントがこのようなオブジェクトを参照していない場合、このプロパティは null になります。
cloudEvent->getData() Object イベントタイプ固有のデータを含む object

使用例

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

Pub/Sub の例

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

C#

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

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


use Google\CloudFunctions\CloudEvent;

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

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

    if ($pubSubData) {
        $name = htmlspecialchars($pubSubData);
    } else {
        $name = 'World';
    }

    $result = 'Hello, ' . $name . '!';
    fwrite($log, $result . PHP_EOL);
}

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

Cloud Storage の例

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

C#

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
{
    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

require "functions_framework"

FunctionsFramework.cloud_event "hello_gcs" do |event|
  # 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


use Google\CloudFunctions\CloudEvent;

function helloGCS(CloudEvent $cloudevent)
{
    $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 チュートリアルをご覧ください。

ヒントとアドバイス

イベントのロギング

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

CloudEvent 関数の終了

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

自動再試行

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

次のステップ