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 オブジェクトとして関数に渡されます。

プロパティ	型	説明
`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 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']);

    $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
{
    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|
  # 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 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 チュートリアルをご覧ください。

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

ヒントとアドバイス

イベントのロギング

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