Gatilhos do Google Cloud Storage

O Cloud Functions pode responder a notificações de alteração surgidas do Google Cloud Storage. Essas notificações podem ser configuradas para serem acionadas em resposta a vários eventos dentro de um intervalo: criação de objetos, exclusão, arquivamento e atualizações de metadados.

Observação: o Cloud Functions só pode ser acionado por intervalos do Cloud Storage no mesmo projeto do Google Cloud Platform.

Tipos de evento

Os eventos do Cloud Storage usados pelo Cloud Functions se baseiam em Notificações do Cloud Pub/Sub para o Google Cloud Storage e podem ser configurados de maneira semelhante.

Os valores do tipo de gatilho compatível são:

• google.storage.object.finalize

• google.storage.object.delete

• google.storage.object.archive

• google.storage.object.metadataUpdate

Finalização do objeto

Valor do tipo de gatilho: google.storage.object.finalize

Esse evento é enviado quando um novo objeto é criado (ou um objeto existente é substituído e uma nova geração desse objeto é criada) no intervalo.

Por exemplo, a seguinte função registra dados relevantes quando ocorre um evento:

Node.js 8+

functions/node8/index.js

Veja no GitHub Feedback

/**
 * Generic background Cloud Function to be triggered by Cloud Storage.
 *
 * @param {object} data The event payload.
 * @param {object} context The event metadata.
 */
exports.helloGCSGeneric = (data, context) => {
  const file = data;
  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}`);
};

Node.js 6 (obsoleto)

functions/helloworld/index.js

Veja no GitHub Feedback

/**
 * Generic background Cloud Function to be triggered by Cloud Storage.
 *
 * @param {object} event The Cloud Functions event.
 * @param {function} callback The callback function.
 */
exports.helloGCSGeneric = (event, callback) => {
  const file = event.data;

  console.log(`  Event: ${event.eventId}`);
  console.log(`  Event Type: ${event.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}`);

  callback();
};

Python

functions/gcs/main.py

Veja no GitHub Feedback

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

    Args:
        data (dict): The Cloud Functions event payload.
        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(data['bucket']))
    print('File: {}'.format(data['name']))
    print('Metageneration: {}'.format(data['metageneration']))
    print('Created: {}'.format(data['timeCreated']))
    print('Updated: {}'.format(data['updated']))

Go

functions/helloworld/storage_generic/hello_storage_generic.go

Veja no GitHub Feedback

// 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 {
	Bucket         string    `json:"bucket"`
	Name           string    `json:"name"`
	Metageneration string    `json:"metageneration"`
	ResourceState  string    `json:"resourceState"`
	TimeCreated    time.Time `json:"timeCreated"`
	Updated        time.Time `json:"updated"`
}

// HelloGCSInfo prints information about a GCS event.
func HelloGCSInfo(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
}

Para implantar a função com um gatilho de finalização do objeto, execute o seguinte comando no diretório que contém o código da função:

Node.js

gcloud functions deploy helloGCSGeneric --runtime nodejs8 --trigger-resource YOUR_TRIGGER_BUCKET_NAME --trigger-event google.storage.object.finalize

É possível usar os seguintes valores para que a sinalização --runtime use versões diferentes do Node.js:

• nodejs6 (obsoleto)
• nodejs8
• nodejs10 (beta)

Python

gcloud functions deploy hello_gcs_generic --runtime python37 --trigger-resource YOUR_TRIGGER_BUCKET_NAME --trigger-event google.storage.object.finalize

Go

gcloud functions deploy HelloGCSInfo --runtime go111 --trigger-resource YOUR_TRIGGER_BUCKET_NAME --trigger-event google.storage.object.finalize

em que YOUR_TRIGGER_BUCKET_NAME é o nome do intervalo do Cloud Storage que a função vai monitorar.

Exclusão do objeto

Valor do tipo de gatilho: google.storage.object.delete

Este evento é enviado quando um objeto é excluído permanentemente. Dependendo da configuração do controle de versões do objeto de um intervalo, isso significa:

• Para intervalos do controle de versões, ele só é enviado quando uma versão é excluída permanentemente (mas não quando um objeto é arquivado).

• Para intervalos sem controle de versões, ele é enviado quando um objeto é excluído ou substituído.

Arquivamento do objeto

Valor do tipo de gatilho: google.storage.object.archive

Este evento é enviado quando uma versão ativa de um objeto é arquivada ou excluída.

Este só é enviado para intervalos com controle de versões.

Atualização de metadados do objeto

Valor do tipo de gatilho: google.storage.object.metadataUpdate

Este evento é enviado quando os metadados de um objeto existente mudam.

Estrutura do evento

Os dados de eventos de armazenamento são entregues no formato object do Cloud Storage.

Mecanismo de entrega do evento

Os eventos são enviados com notificações do Pub/Sub do Cloud Storage. A configuração de muitas funções no mesmo intervalo pode esgotar o limite de notificações para o intervalo e impossibilitar a criação da função, conforme indicado pelo erro Cloud Storage bucket ...: Pub/Sub notification limit reached. Consulte a documentação Notificações do Cloud Pub/Sub do Google Cloud Storage para mais informações sobre limites de notificação.

Gatilhos legados do Cloud Storage

O comando gcloud abaixo implanta uma função que é acionada por notificações de alteração de objeto legadas em um intervalo específico. Geralmente, as notificações do Cloud Pub/Sub são mais fáceis de usar, mais flexíveis e mais eficientes do que as notificações de alteração do objeto. Porém, essas notificações legadas são compatíveis com funções legadas que já consomem esses eventos.

gcloud functions deploy YOUR_FUNCTION_NAME --trigger-resource YOUR_TRIGGER_BUCKET_NAME --trigger-event providers/cloud.storage/eventTypes/object.change FLAGS...

Argumento	Descrição
--trigger-resource NAME	O nome do intervalo do Cloud Storage em que a função detecta alterações.
--trigger-event NAME	O nome do tipo de evento que a função quer receber. Nesse caso, é o evento legado de object.change.
FLAGS...	Sinalizações adicionais que você precisa especificar durante a implantação, como --runtime. Para uma referência completa, consulte a documentação gcloud functions deploy.

Próximas etapas

Consulte o Tutorial do Cloud Storage para um exemplo de como implementar uma função em segundo plano acionada pelo Cloud Storage.