Gatilhos do Cloud Storage


Você pode acionar uma função em resposta ao upload, à atualização ou à exclusão de arquivos e pastas no Cloud Storage.

Os exemplos desta página são baseados em uma função de amostra acionada com o upload de arquivos de imagem no Cloud Storage. Essa função demonstra como acessar atributos de eventos, como fazer o download de um arquivo para uma instância do Cloud Functions e outros princípios básicos do gerenciamento de eventos do Cloud Storage.

Para mais exemplos de casos de uso, acesse O que posso fazer com o Cloud Functions?.

Acionar uma função quando há alterações no Cloud Storage

Use functions.storage para criar uma função que gerencie eventos do Cloud Storage. É possível dimensionar sua função de acordo com um bucket específico do Cloud Storage ou usar o bucket padrão. Dependendo da sua escolha, use uma das seguintes opções:

Por exemplo, a amostra do gerador de miniaturas tem como escopo o bucket padrão do projeto:

exports.firstGenGenerateThumbnail = functions.storage.object().onFinalize(async (object) => {
  // ...
});

O Cloud Storage oferece suporte aos seguintes eventos:

  • onArchive: enviado apenas depois que o controle de versões do objeto é ativado no bucket. Este evento indica que a versão ativa de um objeto se tornou uma versão arquivada por ter sido arquivada ou substituída pelo upload de um objeto de mesmo nome.
  • onDelete: enviado quando um objeto é excluído permanentemente. Isso inclui objetos que são substituídos ou são excluídos como parte da configuração do ciclo de vida do bucket. Nos buckets com o controle de versões dos objetos ativado, ele não é enviado quando um objeto é arquivado (confira onArchive), mesmo que o arquivamento ocorra usando o método storage.objects.delete.
  • onFinalize: enviado quando um novo objeto ou uma nova geração de um objeto é criada com sucesso no bucket. Isso inclui copiar ou regravar um objeto. Um upload com falha não aciona esse evento.
  • onMetadataUpdate: enviado quando os metadados de um objeto são modificados.

Defina o evento dentro do manipulador de eventos on como mostrado acima para onFinalize.

Acessar atributos de objetos do Cloud Storage

O Cloud Functions fornece ao arquivo atualizado diversos atributos de objetos do Cloud Storage, como size e contentType. O atributo metageneration será incrementado sempre que houver uma alteração nos metadados do objeto. Para novos objetos, o valor de metageneration é 1.

const fileBucket = object.bucket; // The Storage bucket that contains the file.
const filePath = object.name; // File path in the bucket.
const contentType = object.contentType; // File content type.
index.js

A amostra de geração de miniaturas usa alguns desses atributos para detectar casos de saída em que a função retorna:

// Exit if this is triggered on a file that is not an image.
if (!contentType.startsWith('image/')) {
  return functions.logger.log('This is not an image.');
}

// Get the file name.
const fileName = path.basename(filePath);
// Exit if the image is already a thumbnail.
if (fileName.startsWith('thumb_')) {
  return functions.logger.log('Already a Thumbnail.');
}
index.js

Fazer o download, transformar e fazer upload de um arquivo

Para alguns casos, pode não ser necessário fazer o download de arquivos do Cloud Storage. Mas, para executar tarefas intensivas, como gerar uma imagem de miniatura usando um arquivo armazenado no Cloud Storage, é necessário fazer o download dos arquivos para a instância das funções, ou seja, para a máquina virtual que executa seu código.

Para fazer o download e um novo upload dos objetos no Cloud Storage, instale este pacote usando npm install --save @google-cloud/storage e depois importe o pacote. Para usar promessas de JavaScript a fim de lidar com processos externos, como tarefas de processamento de miniaturas na amostra, importe também child-process-promise:

const functions = require('firebase-functions/v1');
const admin = require('firebase-admin');
admin.initializeApp()
const path = require('path');

//library for resizing images
const sharp = require('sharp');
index.js

Use o gcs.bucket.file(filePath).download para fazer o download de um arquivo para um diretório temporário na sua instância do Cloud Functions. Nesse local, é possível processar o arquivo conforme necessário e depois fazer o upload para o Cloud Storage. Ao executar tarefas assíncronas, retorne uma promessa de JavaScript na callback.

Exemplo: transformação de imagem

Ao usar o Cloud Functions com programas de processamento de imagens como o sharp, é possível fazer manipulações em arquivos de imagens gráficas. Veja abaixo um exemplo de como criar uma imagem em miniatura para um arquivo de imagem:

// Download file from bucket.
const bucket = admin.storage().bucket(fileBucket);
const metadata = {
  contentType: contentType,
};
const downloadResponse = await bucket.file(filePath).download();
const imageBuffer = downloadResponse[0];
functions.logger.log("Image downloaded!");

// Generate a thumbnail using sharp.
const thumbnailBuffer = await sharp(imageBuffer).resize({
  width: 200,
  height: 200,
  withoutEnlargement: true,
}).toBuffer();
functions.logger.log("Thumbnail created");

// Upload the thumbnail with a 'thumb_' prefix.
const thumbFileName = `thumb_${fileName}`;
const thumbFilePath = path.join(path.dirname(filePath), thumbFileName);
await bucket.file(thumbFilePath).save(thumbnailBuffer, {
  metadata: metadata,
});
return functions.logger.log("Thumbnail uploaded!");
index.js

Esse código cria uma miniatura de 200x200 para a imagem salva em um diretório temporário e, em seguida, faz o upload dela de volta ao Cloud Storage.

Ver mais exemplos

Conheça outros exemplos de funções comuns de transformação de mídia, incluindo transcodificação de imagens, moderação de conteúdo e extração de metadados EXIF (todos em inglês). A lista completa de exemplos (em inglês) está disponível no GitHub.