Gatilhos do Google Cloud Storage
O Cloud Functions usa funções orientadas a eventos para processar eventos pela Infraestrutura do Cloud. Por exemplo, 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 bucket: criação de objetos, exclusão, arquivamento e atualizações de metadados.
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 são fornecidos no formato da API JSON do Cloud Storage.
As funções acionadas pelo armazenamento aceitam quatro tipos de gatilho. Esses valores de tipo de gatilho são usados na implantação da função para especificar quais eventos do Cloud Storage acionarão as funções:
google.storage.object.finalize
(padrão)
Cógido de função de amostra
O exemplo de função a seguir registra dados relevantes quando ocorre um evento.
Especifique o tipo de gatilho ao implantar a função. Por exemplo,
o exemplo de implantação abaixo usa a função para registrar toda vez
que um objeto é criado ao especificar o
tipo de gatilho google.storage.object.finalize
.
Para ver um tutorial completo sobre como executar esse código, consulte o tutorial do Cloud Storage:
Node.js
Python
Go
Java
C#
Ruby
PHP
Como especificar o tipo de gatilho na implantação
O comando gcloud
a seguir implanta a função com um
gatilho object.finalize
.
Node.js
gcloud functions deploy helloGCS \ --runtime nodejs16 \É possível usar os seguintes valores para a sinalização
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
para especificar sua versão preferida do Node.js: nodejs16
(recomendado)nodejs14
nodejs12
nodejs10
Python
gcloud functions deploy hello_gcs \ --runtime python39 \É possível usar os seguintes valores da sinalização
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
para especificar a versão preferencial do Python:
python310
(visualização)python39
(recomendado)python38
python37
Go
gcloud functions deploy HelloGCS \ --runtime go116 \É possível usar os seguintes valores para a sinalização
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
para especificar sua versão Go preferencial: go116
(recomendado)go113
go111
Java
gcloud functions deploy java-gcs-function \ --entry-point functions.HelloGcs \ --runtime java11 \ --memory 512MB \É possível usar os seguintes valores da sinalização
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
para especificar a versão preferencial do Java:
java17
(visualização)java11
(recomendado)
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
Ruby
gcloud functions deploy hello_gcs --runtime ruby30 \Use os seguintes valores da sinalização
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
para especificar a versão do Ruby que você quer usar:
ruby30
(recomendado)ruby27
ruby26
PHP
gcloud functions deploy helloGCS --runtime php74 \É possível usar os seguintes valores da sinalização
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
para especificar a versão preferencial do PHP:
php81
(visualização)php74
(recomendado)
em que YOUR_TRIGGER_BUCKET_NAME
é o nome do bucket do
Cloud Storage que a função vai monitorar.
Objeto finalize
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 bucket.
Objeto delete
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ão do objeto de um bucket isso significa:
Para buckets do controle de versões, ele só é enviado quando uma versão é excluída permanentemente (mas não quando um objeto é arquivado).
Para buckets 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 buckets com controle de versão.
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 envio do evento
Os eventos são entregues usando notificações do Pub/Sub do Cloud Storage. Os eventos estão sujeitos às garantias de envio do Pub/Sub.
Limite de notificações
É possível ter até 10 configurações de notificação definidas no bucket para acionar um determinado evento. A configuração de muitas notificações para o mesmo bucket pode exceder o limite de notificações do bucket e impossibilitar a criação da função, conforme indicado por este erro:
Cloud Storage bucket ...: Pub/Sub notification limit reached
Se você atingir o limite, não será possível criar uma função até tomar medidas corretivas, como remover as notificações.
Saiba mais sobre as cotas e os limites de solicitação do Cloud Storage.
Permissões
É necessário ter permissões suficientes no projeto que receberá as notificações. Isso inclui garantir que você faça o seguinte:
Encontre o endereço de e-mail da conta de serviço associada ao projeto que contém o bucket do Cloud Storage.
Use esse endereço de e-mail para atribuir ao agente de serviço o papel do IAM
pubsub.publisher
para o tópico do Pub/Sub relevante.
Saiba mais sobre o recurso Como configurar notificações do Pub/Sub para Cloud Storage.
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
bucket 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 bucket 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 orientada a eventos que é acionada pelo Cloud Storage.