Google Cloud Pub/Sub トリガー

Cloud Functions は、イベント ドリブン関数を使用してクラウド インフラストラクチャのイベントを処理します。たとえば、Cloud Functions は、関数と同じ Cloud プロジェクトで Pub/Sub トピックにパブリッシュされたメッセージによってトリガーできます。Pub/Sub はグローバルに分散されたメッセージバスであり、必要に応じて自動的にスケーリングし、堅牢でグローバルな独自のサービスを構築するための基盤を提供します。

注: このドキュメントは、Cloud Pub/Sub HTTP push サブスクリプション によって呼び出される HTTP トリガーの関数には適用されません。HTTP push サブスクリプションによって転送される Pub/Sub メッセージを処理する関数は、異なる関数の引数とイベント構造を持っています。

イベントの種類

Cloud Functions で使用される単一の Pub/Sub イベントが存在し、そのトリガータイプ値は google.pubsub.topic.publish です。

このイベントは、関数のデプロイ時に指定される Pub/Sub トピックにメッセージが公開されたときに送信されます。このトピックに公開されるすべてのメッセージによって関数の実行がトリガーされ、メッセージのコンテンツが入力データとして送られます。

イベントの構造

Pub/Sub トピックからトリガーされる Cloud Functions には、PubsubMessage タイプに準拠するイベントが送信されますが、PubsubMessage では publishTime と messageId を直接使用できないことに注意します。代わりに、publishTime と messageId にはイベント メタデータのイベント ID とタイムスタンプのプロパティを使用するとアクセスできます。このメタデータには、呼び出しの際に関数に渡されるコンテキスト オブジェクトを介してアクセスできます。

トピックに公開されるデータである PubsubMessage オブジェクトのペイロードは、base64 エンコード文字列として PubsubMessage の data 属性に格納されます。PubsubMessage オブジェクトのペイロードを抽出するには、次の例に示されているように、データ属性のデコードが必要な場合もあります。

サンプルコード

Node.js

functions/helloworld/index.js

GitHub で表示 フィードバック

/**
 * Background Cloud Function to be triggered by Pub/Sub.
 * This function is exported by index.js, and executed when
 * the trigger topic receives a message.
 *
 * @param {object} message The Pub/Sub message.
 * @param {object} context The event metadata.
 */
exports.helloPubSub = (message, context) => {
  const name = message.data
    ? Buffer.from(message.data, 'base64').toString()
    : 'World';

  console.log(`Hello, ${name}!`);
};

Python

functions/helloworld/main.py

GitHub で表示 フィードバック

def hello_pubsub(event, context):
    """Background Cloud Function to be triggered by Pub/Sub.
    Args:
         event (dict):  The dictionary with data specific to this type of
                        event. The `@type` field maps to
                         `type.googleapis.com/google.pubsub.v1.PubsubMessage`.
                        The `data` field maps to the PubsubMessage data
                        in a base64-encoded string. The `attributes` field maps
                        to the PubsubMessage attributes if any is present.
         context (google.cloud.functions.Context): Metadata of triggering event
                        including `event_id` which maps to the PubsubMessage
                        messageId, `timestamp` which maps to the PubsubMessage
                        publishTime, `event_type` which maps to
                        `google.pubsub.topic.publish`, and `resource` which is
                        a dictionary that describes the service API endpoint
                        pubsub.googleapis.com, the triggering topic's name, and
                        the triggering event type
                        `type.googleapis.com/google.pubsub.v1.PubsubMessage`.
    Returns:
        None. The output is written to Cloud Logging.
    """
    import base64

    print("""This Function was triggered by messageId {} published at {} to {}
    """.format(context.event_id, context.timestamp, context.resource["name"]))

    if 'data' in event:
        name = base64.b64decode(event['data']).decode('utf-8')
    else:
        name = 'World'
    print('Hello {}!'.format(name))

Go

functions/helloworld/hello_pubsub.go

GitHub で表示 フィードバック

// Package helloworld provides a set of Cloud Functions samples.
package helloworld

import (
	"context"
	"log"
)

// PubSubMessage is the payload of a Pub/Sub event.
// See the documentation for more details:
// https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage
type PubSubMessage struct {
	Data []byte `json:"data"`
}

// HelloPubSub consumes a Pub/Sub message.
func HelloPubSub(ctx context.Context, m PubSubMessage) error {
	name := string(m.Data) // Automatically decoded from base64.
	if name == "" {
		name = "World"
	}
	log.Printf("Hello, %s!", name)
	return nil
}

Java

functions/helloworld/hello-pubsub/src/main/java/functions/HelloPubSub.java

GitHub で表示 フィードバック

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import com.google.events.cloud.pubsub.v1.Message;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.logging.Level;
import java.util.logging.Logger;

public class HelloPubSub implements BackgroundFunction<Message> {
  private static final Logger logger = Logger.getLogger(HelloPubSub.class.getName());

  @Override
  public void accept(Message message, Context context) {
    String name = "world";
    if (message != null && message.getData() != null) {
      name = new String(
          Base64.getDecoder().decode(message.getData().getBytes(StandardCharsets.UTF_8)),
          StandardCharsets.UTF_8);
    }
    logger.info(String.format("Hello %s!", name));
    return;
  }
}

Kotlin

functions/src/main/kotlin/EventExample.kt

GitHub で表示 フィードバック

import java.util.Base64
import java.util.logging.Logger

class EventExample {
    companion object {
        var log: Logger = Logger.getLogger(EventExample::class.java.name)
    }

    fun helloPubSub(message: PubSubMessage) {
        val data = String(Base64.getDecoder().decode(message.data))
        log.info(data)
    }
}

data class PubSubMessage(
    val data: String,
    val messageId: String,
    val publishTime: String,
    val attributes: Map<String, String>
)

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);
}

注: 例外がスローされ、自動再試行が有効になっていない場合、関数の完了時、Cloud Functions は受信メッセージに対して内部で ack を送信します。例外がスローされたときに呼び出しを自動的に再試行する方法の詳細は、バックグラウンド関数の再試行のドキュメントをご覧ください。

関数内からメッセージを公開する

関数内からメッセージを Pub/Sub トピックに公開することもできます。これにより、Cloud Pub/Sub メッセージを使用して、後続の Cloud Function の呼び出しをトリガーできます。この手法は、以下の処理に使用できます。

• 順次関数呼び出しを一緒に行う。
• 複数の Cloud Functions の関数インスタンス間に同時に、タスクのグループを分配（または「ファンアウト」）する。

次の例では、HTTP publish 関数によって、Pub/Sub トピックにメッセージが送信され、それによって subscribe 関数がトリガーされます。

このスニペットは、Pub/Sub トピックにメッセージを公開する publish 関数を示します。

注: 以下のコードでは、GOOGLE_CLOUD_PROJECT 環境変数に Google Cloud プロジェクトの名前が設定されていることを前提としています。

Node.js

functions/pubsub/index.js

GitHub で表示 フィードバック

const {PubSub} = require('@google-cloud/pubsub');

// Instantiates a client
const pubsub = new PubSub();

/**
 * Publishes a message to a Cloud Pub/Sub Topic.
 *
 * @example
 * gcloud functions call publish --data '{"topic":"[YOUR_TOPIC_NAME]","message":"Hello, world!"}'
 *
 *   - Replace `[YOUR_TOPIC_NAME]` with your Cloud Pub/Sub topic name.
 *
 * @param {object} req Cloud Function request context.
 * @param {object} req.body The request body.
 * @param {string} req.body.topic Topic name on which to publish.
 * @param {string} req.body.message Message to publish.
 * @param {object} res Cloud Function response context.
 */
exports.publish = async (req, res) => {
  if (!req.body.topic || !req.body.message) {
    res
      .status(400)
      .send(
        'Missing parameter(s); include "topic" and "message" properties in your request.'
      );
    return;
  }

  console.log(`Publishing message to topic ${req.body.topic}`);

  // References an existing topic
  const topic = pubsub.topic(req.body.topic);

  const messageObject = {
    data: {
      message: req.body.message,
    },
  };
  const messageBuffer = Buffer.from(JSON.stringify(messageObject), 'utf8');

  // Publishes a message
  try {
    await topic.publish(messageBuffer);
    res.status(200).send('Message published.');
  } catch (err) {
    console.error(err);
    res.status(500).send(err);
    return Promise.reject(err);
  }
};

Python

functions/pubsub/main.py

GitHub で表示 フィードバック

import base64
import json
import os

from google.cloud import pubsub_v1

# Instantiates a Pub/Sub client
publisher = pubsub_v1.PublisherClient()
PROJECT_ID = os.getenv('GOOGLE_CLOUD_PROJECT')

# Publishes a message to a Cloud Pub/Sub topic.
def publish(request):
    request_json = request.get_json(silent=True)

    topic_name = request_json.get("topic")
    message = request_json.get("message")

    if not topic_name or not message:
        return ('Missing "topic" and/or "message" parameter.', 400)

    print(f'Publishing message to topic {topic_name}')

    # References an existing topic
    topic_path = publisher.topic_path(PROJECT_ID, topic_name)

    message_json = json.dumps({
        'data': {'message': message},
    })
    message_bytes = message_json.encode('utf-8')

    # Publishes a message
    try:
        publish_future = publisher.publish(topic_path, data=message_bytes)
        publish_future.result()  # Verify the publish succeeded
        return 'Message published.'
    except Exception as e:
        print(e)
        return (e, 500)

Go

functions/tips/contexttip/context_tip.go

GitHub で表示 フィードバック

// Package contexttip is an example of how to use Pub/Sub and context.Context in
// a Cloud Function.
package contexttip

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"

	"cloud.google.com/go/pubsub"
)

// GOOGLE_CLOUD_PROJECT is a user-set environment variable.
var projectID = os.Getenv("GOOGLE_CLOUD_PROJECT")

// client is a global Pub/Sub client, initialized once per instance.
var client *pubsub.Client

func init() {
	// err is pre-declared to avoid shadowing client.
	var err error

	// client is initialized with context.Background() because it should
	// persist between function invocations.
	client, err = pubsub.NewClient(context.Background(), projectID)
	if err != nil {
		log.Fatalf("pubsub.NewClient: %v", err)
	}
}

type publishRequest struct {
	Topic   string `json:"topic"`
	Message string `json:"message"`
}

// PublishMessage publishes a message to Pub/Sub. PublishMessage only works
// with topics that already exist.
func PublishMessage(w http.ResponseWriter, r *http.Request) {
	// Parse the request body to get the topic name and message.
	p := publishRequest{}

	if err := json.NewDecoder(r.Body).Decode(&p); err != nil {
		log.Printf("json.NewDecoder: %v", err)
		http.Error(w, "Error parsing request", http.StatusBadRequest)
		return
	}

	if p.Topic == "" || p.Message == "" {
		s := "missing 'topic' or 'message' parameter"
		log.Println(s)
		http.Error(w, s, http.StatusBadRequest)
		return
	}

	m := &pubsub.Message{
		Data: []byte(p.Message),
	}
	// Publish and Get use r.Context() because they are only needed for this
	// function invocation. If this were a background function, they would use
	// the ctx passed as an argument.
	id, err := client.Topic(p.Topic).Publish(r.Context(), m).Get(r.Context())
	if err != nil {
		log.Printf("topic(%s).Publish.Get: %v", p.Topic, err)
		http.Error(w, "Error publishing message", http.StatusInternalServerError)
		return
	}
	fmt.Fprintf(w, "Message published: %v", id)
}

Java

functions/pubsub/publish-message/src/main/java/functions/PublishMessage.java

GitHub で表示 フィードバック

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import com.google.cloud.pubsub.v1.Publisher;
import com.google.protobuf.ByteString;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.PubsubMessage;
import java.io.BufferedWriter;
import java.io.IOException;
import java.net.HttpURLConnection;
import java.nio.charset.StandardCharsets;
import java.util.Optional;
import java.util.concurrent.ExecutionException;
import java.util.logging.Level;
import java.util.logging.Logger;

public class PublishMessage implements HttpFunction {
  // TODO<developer> set this environment variable
  private static final String PROJECT_ID = System.getenv("GOOGLE_CLOUD_PROJECT");

  private static final Logger logger = Logger.getLogger(PublishMessage.class.getName());

  @Override
  public void service(HttpRequest request, HttpResponse response) throws IOException {
    Optional<String> maybeTopicName = request.getFirstQueryParameter("topic");
    Optional<String> maybeMessage = request.getFirstQueryParameter("message");

    BufferedWriter responseWriter = response.getWriter();

    if (maybeTopicName.isEmpty() || maybeMessage.isEmpty()) {
      response.setStatusCode(HttpURLConnection.HTTP_BAD_REQUEST);

      responseWriter.write("Missing 'topic' and/or 'message' parameter(s).");
      return;
    }

    String topicName = maybeTopicName.get();
    logger.info("Publishing message to topic: " + topicName);

    // Create the PubsubMessage object
    ByteString byteStr = ByteString.copyFrom(maybeMessage.get(), StandardCharsets.UTF_8);
    PubsubMessage pubsubApiMessage = PubsubMessage.newBuilder().setData(byteStr).build();

    Publisher publisher = Publisher.newBuilder(
        ProjectTopicName.of(PROJECT_ID, topicName)).build();

    // Attempt to publish the message
    String responseMessage;
    try {
      publisher.publish(pubsubApiMessage).get();
      responseMessage = "Message published.";
    } catch (InterruptedException | ExecutionException e) {
      logger.log(Level.SEVERE, "Error publishing Pub/Sub message: " + e.getMessage(), e);
      responseMessage = "Error publishing Pub/Sub message; see logs for more info.";
    }

    responseWriter.write(responseMessage);
  }
}

このスニペットは、Pub/Sub トピックにメッセージが公開されるとトリガーされる subscribe 関数を示しています。

Node.js

functions/pubsub/index.js

GitHub で表示 フィードバック

/**
 * Triggered from a message on a Cloud Pub/Sub topic.
 *
 * @param {object} pubsubMessage The Cloud Pub/Sub Message object.
 * @param {string} pubsubMessage.data The "data" property of the Cloud Pub/Sub Message.
 */
exports.subscribe = pubsubMessage => {
  // Print out the data from Pub/Sub, to prove that it worked
  console.log(Buffer.from(pubsubMessage.data, 'base64').toString());
};

Python

functions/pubsub/main.py

GitHub で表示 フィードバック

# Triggered from a message on a Cloud Pub/Sub topic.
def subscribe(event, context):
    # Print out the data from Pub/Sub, to prove that it worked
    print(base64.b64decode(event['data']))

Java

functions/pubsub/subscribe-to-topic/src/main/java/functions/SubscribeToTopic.java

GitHub で表示 フィードバック

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import com.google.events.cloud.pubsub.v1.Message;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.logging.Logger;

public class SubscribeToTopic implements BackgroundFunction<Message> {
  private static final Logger logger = Logger.getLogger(SubscribeToTopic.class.getName());

  @Override
  public void accept(Message message, Context context) {
    if (message.getData() == null) {
      logger.info("No message provided");
      return;
    }

    String messageString = new String(
        Base64.getDecoder().decode(message.getData().getBytes(StandardCharsets.UTF_8)),
        StandardCharsets.UTF_8);
    logger.info(messageString);
  }
}

本番環境では、次のように、cURL コマンドライン ユーティリティを使用しても publish 関数を呼び出せます。

curl https://GCF_REGION-GCP_PROJECT_ID.cloudfunctions.net/publish -X POST  -d "{\"topic\": \"PUBSUB_TOPIC\", \"message\":\"YOUR_MESSAGE\"}" -H "Content-Type: application/json"

テストとデバッグ以外の場合は、gcloud functions call コマンドを代わりに使用して、関数を直接呼び出すことができます。次の手順では、gcloud functions call コマンドを使用して、上記のサンプルを実行する方法について説明します。

1. Pub/Sub トピックを作成します。ここで、MY_TOPIC は、作成する新しいトピックの名前です。

   gcloud pubsub topics create MY_TOPIC

2. publish 関数をデプロイします。ここで、RUNTIME は、使用するランタイムの名前（nodejs8 など）です。

   gcloud functions deploy publish --trigger-http --runtime RUNTIME

3. subscribe 関数をデプロイします。

   gcloud functions deploy subscribe --trigger-topic MY_TOPIC --runtime RUNTIME

4. gcloud functions call コマンドを使用して publish 関数を直接呼び出し、必要なデータは、--data 引数で JSON 形式として指定します。

   gcloud functions call publish --data '{"topic":"MY_TOPIC","message":"Hello World!"}'

5. ログで subscribe 関数を確認します。ログに結果が表示されるまで、数分間かかることがあります。

   gcloud functions logs read subscribe

次のような出力が表示されます。

D    ...Function execution started
I    ...{"data":{"message":"Hello World!"}}
D    ...Function execution took 753 ms, finished with status: 'ok'

関数のデプロイ

次の gcloud コマンドは、Pub/Sub トピックにメッセージが公開されるとトリガーされる関数をデプロイします。

gcloud functions deploy FUNCTION_NAME --entry-point ENTRY_POINT --trigger-topic TOPIC_NAME FLAGS...

注: gcloud コマンドライン ツールを使用して関数をデプロイする場合、deploy コマンドを実行するコードに含まれる関数の名前をコマンドに指定する必要があります。この関数は、実装のニーズに応じて、FUNCTION_NAME またはオプションの --entry-point フラグで指定します。このトピックの詳細については、gcloud ツールによるデプロイをご覧ください。

引数	説明
FUNCTION_NAME	デプロイする Cloud Functions の関数の登録名。ソースコード内の関数の名前にすることも、任意の文字列にすることもできます。FUNCTION_NAME が任意の文字列の場合は、--entry-point フラグを含める必要があります。
--entry-point ENTRY_POINT	ソースコード内の関数またはクラスの名前。FUNCTION_NAME を使用して、デプロイ時に実行する関数をソースコードに指定していない場合は省略できます。それ以外の場合は、--entry-point を使用して実行可能関数の名前を指定する必要があります。
--trigger-topic TOPIC_NAME	関数が登録されている Pub/Sub トピックの名前。トピックが存在しない場合は、デプロイ時に作成されます。
FLAGS...	デプロイ時に指定する必要がある --runtime などの追加フラグ。網羅的なリファレンスについては、gcloud functions deploy のドキュメントをご覧ください。

Pub/Sub トリガーの使用法を示す完全な例については、Pub/Sub チュートリアルをご覧ください。

レガシー Cloud Pub/Sub トリガー

次の gcloud コマンドは、特定のトピックでレガシー Pub/Sub 通知によってトリガーされる関数をデプロイします。これらのイベントをすでに使用しているレガシー関数では、これらの通知がサポートされます。ただし、将来、レガシー通知は削除される可能性があるため、代わりに --trigger-topic フラグの使用をおすすめします。

gcloud functions deploy FUNCTION_NAME \
--trigger-resource TOPIC_NAME \
--trigger-event providers/cloud.pubsub/eventTypes/topic.publish \
FLAGS...

注: レガシー イベントを使用する既存の関数があり、その代わりとして新しいイベントタイプを使用するときは、まず、レガシー イベントを使用する関数を削除する必要があります。

次のステップ

Pub/Sub によってトリガーされるイベント ドリブン関数を実装する方法の例について、Pub/Sub チュートリアルで確認する。