Google Cloud Storage 触发器

Cloud Functions 函数可以响应来自 Google Cloud Storage 的更改通知。您可以对这些通知进行配置,使其为了响应存储分区内的各种事件(对象创建、删除、归档和元数据更新)而触发。

事件类型

Cloud Functions 函数使用的 Cloud Storage 事件基于针对 Google Cloud Storage 的 Cloud Pub/Sub 通知,并且可以采用类似方式进行配置。

支持的触发器类型值为:

  • google.storage.object.finalize(默认值)

  • google.storage.object.delete

  • google.storage.object.archive

  • google.storage.object.metadataUpdate

完成对象创建

触发器类型值:google.storage.object.finalize

当存储分区中创建了新对象(或者现有对象被覆盖,以及创建了该对象的新实例)时,系统将发送此事件。

例如,以下函数会在事件发生时记录相关数据:

Node.js

 
/**
 * Generic background Cloud Function to be triggered by Cloud Storage.
 *
 * @param {object} file The Cloud Storage file metadata.
 * @param {object} context The event metadata.
 */
exports.helloGCS = (file, context) => {
  console.log(`  Event: ${context.eventId}`);
  console.log(`  Event Type: ${context.eventType}`);
  console.log(`  Bucket: ${file.bucket}`);
  console.log(`  File: ${file.name}`);
  console.log(`  Metageneration: ${file.metageneration}`);
  console.log(`  Created: ${file.timeCreated}`);
  console.log(`  Updated: ${file.updated}`);
};

Python

 
def hello_gcs(event, context):
    """Background Cloud Function to be triggered by Cloud Storage.
       This generic function logs relevant data when a file is changed.

    Args:
        event (dict):  The dictionary with data specific to this type of event.
                       The `data` field contains a description of the event in
                       the Cloud Storage `object` format described here:
                       https://cloud.google.com/storage/docs/json_api/v1/objects#resource
        context (google.cloud.functions.Context): Metadata of triggering event.
    Returns:
        None; the output is written to Stackdriver Logging
    """

    print('Event ID: {}'.format(context.event_id))
    print('Event type: {}'.format(context.event_type))
    print('Bucket: {}'.format(event['bucket']))
    print('File: {}'.format(event['name']))
    print('Metageneration: {}'.format(event['metageneration']))
    print('Created: {}'.format(event['timeCreated']))
    print('Updated: {}'.format(event['updated']))

Go

 

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

import (
	"context"
	"fmt"
	"log"
	"time"

	"cloud.google.com/go/functions/metadata"
)

// GCSEvent is the payload of a GCS event.
type GCSEvent struct {
	Kind                    string                 `json:"kind"`
	ID                      string                 `json:"id"`
	SelfLink                string                 `json:"selfLink"`
	Name                    string                 `json:"name"`
	Bucket                  string                 `json:"bucket"`
	Generation              string                 `json:"generation"`
	Metageneration          string                 `json:"metageneration"`
	ContentType             string                 `json:"contentType"`
	TimeCreated             time.Time              `json:"timeCreated"`
	Updated                 time.Time              `json:"updated"`
	TemporaryHold           bool                   `json:"temporaryHold"`
	EventBasedHold          bool                   `json:"eventBasedHold"`
	RetentionExpirationTime time.Time              `json:"retentionExpirationTime"`
	StorageClass            string                 `json:"storageClass"`
	TimeStorageClassUpdated time.Time              `json:"timeStorageClassUpdated"`
	Size                    string                 `json:"size"`
	MD5Hash                 string                 `json:"md5Hash"`
	MediaLink               string                 `json:"mediaLink"`
	ContentEncoding         string                 `json:"contentEncoding"`
	ContentDisposition      string                 `json:"contentDisposition"`
	CacheControl            string                 `json:"cacheControl"`
	Metadata                map[string]interface{} `json:"metadata"`
	CRC32C                  string                 `json:"crc32c"`
	ComponentCount          int                    `json:"componentCount"`
	Etag                    string                 `json:"etag"`
	CustomerEncryption      struct {
		EncryptionAlgorithm string `json:"encryptionAlgorithm"`
		KeySha256           string `json:"keySha256"`
	}
	KMSKeyName    string `json:"kmsKeyName"`
	ResourceState string `json:"resourceState"`
}

// HelloGCS consumes a GCS event.
func HelloGCS(ctx context.Context, e GCSEvent) error {
	meta, err := metadata.FromContext(ctx)
	if err != nil {
		return fmt.Errorf("metadata.FromContext: %v", err)
	}
	log.Printf("Event ID: %v\n", meta.EventID)
	log.Printf("Event type: %v\n", meta.EventType)
	log.Printf("Bucket: %v\n", e.Bucket)
	log.Printf("File: %v\n", e.Name)
	log.Printf("Metageneration: %v\n", e.Metageneration)
	log.Printf("Created: %v\n", e.TimeCreated)
	log.Printf("Updated: %v\n", e.Updated)
	return nil
}

Java

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import functions.eventpojos.GcsEvent;
import java.util.logging.Logger;

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

  @Override
  public void accept(GcsEvent event, Context context) {
    logger.info("Event: " + context.eventId());
    logger.info("Event Type: " + context.eventType());
    logger.info("Bucket: " + event.getBucket());
    logger.info("File: " + event.getName());
    logger.info("Metageneration: " + event.getMetageneration());
    logger.info("Created: " + event.getTimeCreated());
    logger.info("Updated: " + event.getUpdated());
  }
}

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

要使用“完成对象创建”触发器部署函数,请在包含函数代码的目录中运行以下命令:

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs10 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
您可以使用 --runtime 标志的以下值来指定偏好的 Node.js 版本:
  • nodejs10
  • nodejs12

Python

gcloud functions deploy hello_gcs \
--runtime python37 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
您可以使用 --runtime 标志的以下值来指定偏好的 Python 版本:
  • python37
  • python38

Go

gcloud functions deploy HelloGCS \
--runtime go111 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
您可以使用 --runtime 标志的以下值来指定偏好的 Go 版本:
  • go111
  • go113

Java

gcloud functions deploy java-gcs-function \
--entry-point HelloGcs \
--runtime java11 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

C#

gcloud functions deploy csharp-gcs-function \
--entry-point HelloGcs.Function \
--runtime dotnet3 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

其中,YOUR_TRIGGER_BUCKET_NAME 是函数将监控的 Cloud Storage 存储分区的名称。

对象删除

触发器类型值:google.storage.object.delete

此事件在某个对象被永久删除时发送。根据存储分区的对象版本控制设置,这意味着:

  • 对于启用了版本控制的存储分区,只有当某个版本被永久删除时(而不是在对象被归档时),系统才会发送此事件。

  • 对于未启用版本控制的存储分区,当某个对象被删除或覆盖时,系统会发送此事件。

对象归档

触发器类型值:google.storage.object.archive

此事件在对象的现行版本被归档或被删除时发送。

系统仅针对启用了版本控制的存储分区发送此事件。

对象元数据更新

触发器类型值:google.storage.object.metadataUpdate

此事件在现有对象的元数据发生更改时发送。

事件结构

存储事件数据以 Cloud Storage object 格式传送。

事件传送机制

事件随来自 Cloud Storage 的 Pub/Sub 通知一起传送。针对同一存储分区设置过多的函数可能会耗尽存储分区的通知限制,从而无法再创建函数,如错误 Cloud Storage bucket ...: Pub/Sub notification limit reached 所示。如需详细了解通知限制,请参阅 Google Cloud Storage Cloud Pub/Sub 通知文档。

旧版 Cloud Storage 触发器

下面的 gcloud 命令将部署一个由特定存储分区的旧版对象更改通知触发的函数。通常,与对象更改通知相比,Cloud Pub/Sub 通知更易于使用、更灵活,而且功能更强大。但是,已在使用这些事件的旧版函数支持这些旧版通知。

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event providers/cloud.storage/eventTypes/object.change \
FLAGS...
参数 说明
--trigger-resource NAME 函数可检测其更改情况的 Cloud Storage 存储分区的名称。
--trigger-event NAME 函数希望接收的事件类型的名称。在此示例中,事件类型为旧版 object.change 事件。
FLAGS... 您在部署期间必须指定的其他标志,例如 --runtime。如需查看完整参考信息,请参阅 gcloud functions deploy 文档

后续步骤

如需查看有关如何实现由 Cloud Storage 触发的后台函数的示例,请参阅 Cloud Storage 教程