Gatilhos do Cloud Storage

No Cloud Run functions, um acionador do Cloud Storage permite que uma função seja chamada em resposta às mudanças no Cloud Storage. Ao especificar um gatilho do Cloud Storage para uma função, você escolhe um tipo de evento e um bucket do Cloud Storage. A função será chamada sempre que ocorrer uma alteração em um objeto (arquivo) no bucket especificado.

Os seguintes tipos de eventos do Cloud Storage são compatíveis:

Evento Tipo de evento Descrição
Objeto finalizado
  • google.cloud.storage.object.v1.finalized (pelo Eventarc)
 Isso ocorre quando um novo objeto é criado ou um objeto existente é substituído e uma nova geração desse objeto é criada.
Objeto excluído
  • google.cloud.storage.object.v1.deleted (pelo Eventarc)
 Isso ocorre quando um objeto é excluído permanentemente.
Objeto arquivado
  • google.cloud.storage.object.v1.archived (pelo Eventarc)
 Isso ocorre quando uma versão ativa de um objeto se torna uma versão não atual. Consulte Controle de versão de objeto para mais informações.
Metadados de objetos atualizados
  • google.cloud.storage.object.v1.metadataUpdated (pelo Eventarc)
 Ocorre quando os metadados de um objeto são alterados.

Um gatilho do Cloud Storage é implementado como uma Função CloudEvent, em que os dados do evento do Cloud Storage são transmitidos para a função no formato CloudEvents e o payload dos dados CloudEvent é do tipo StorageObjectData

O repositório Eventos do Google contém outros recursos para trabalhar com dados de eventos.

Permissões

Para usar gatilhos do Cloud Storage no Cloud Run functions, o agente de serviço do Cloud Storage precisa ter o papel do IAM Publicador do Pub/Sub (roles/pubsub.publisher) no projeto.

Implantação

É possível especificar um acionador do Cloud Storage ao implantar uma função. Consulte Implantar uma função do Cloud Run para instruções gerais sobre como implantar uma função. Confira abaixo mais informações específicas para configurar gatilhos do Cloud Storage durante a implantação.

gcloud

Se você estiver implantando usando a CLI gcloud, poderá usar o tipo de evento Objeto finalizado do Cloud Storage com as seguintes sinalizações:

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-bucket=YOUR_STORAGE_BUCKET \
[--retry] \
...
  • A flag --trigger-bucket especifica o bucket do Cloud Storage que será monitorado pelo gatilho. Eventos finalizados pelo objeto nesse bucket acionarão chamadas para sua função.
  • A sinalização --retry controla se as chamadas de função com falha são repetidas automaticamente. Consulte Como repetir funções orientadas a eventos para mais informações.

Para usar tipos de eventos diferentes de objeto finalizado, use as seguintes sinalizações:

  gcloud functions deploy YOUR_FUNCTION_NAME 

  --gen2 

  --trigger-event-filters="type=EVENT_TYPE" 

  --trigger-event-filters="bucket=YOUR_STORAGE_BUCKET" 

  ...

Ao implantar funções, especifique apenas o nome do bucket sem o gs:// principal; por exemplo, --trigger-event-filters="bucket=my-bucket".

Console

Se você estiver implantando usando o Console do Google Cloud, será possível configurar um acionador do Cloud Storage na seção Acionador:

  1. No campo Tipo de gatilho, selecione Cloud Storage.

  2. No campo Tipo de evento, selecione um evento de gatilho. O padrão é google.cloud.storage.object.v1.finalized.

    Para um evento do Cloud Storage que usa os Registros de auditoria do Cloud, consulte as instruções de configuração de um gatilho do Eventarc.

  3. No campo Bucket, clique em Procurar para selecionar um bucket do Cloud Storage para o gatilho monitorar. As alterações feitas nos objetos dentro desse bucket acionarão chamadas para sua função.

  4. Marque ou desmarque a caixa de seleção Tentar novamente em caso de falha para controlar se o Cloud Run functions repetirá automaticamente uma invocação de função que falhou. Consulte Como repetir funções orientadas a eventos para mais informações.

  5. Clique em Mais opções para fazer outras configurações no gatilho:

    • No campo Tipo de gatilho, especifique uma das Fontes do Google, Personalizado ou Terceiros:

      • As Fontes do Google permitem especificar gatilhos para o Pub/Sub, Cloud Storage, Firestore e outros provedores de eventos do Google. No painel Gatilho do Eventarc, use o campo Provedor de eventos para selecionar o produto que fornece o tipo de evento que você quer que acione sua função. Em seguida, no campo Evento, selecione o evento que você quer usar como gatilho.

      • A opção Personalizada permite produzir e consumir eventos do código do aplicativo. Siga as instruções no painel Gatilho do Eventarc para criar um canal. Um canal é um recurso usado como pipeline para entregar eventos personalizados de produtores a consumidores. Eventos personalizados são publicados em um canal, e um gatilho do Eventarc é inscrito nesses eventos.

      • A opção Terceiros permite a integração com provedores que não são do Google que oferecem uma fonte do Eventarc. Consulte Eventos de terceiros no Eventarc para mais detalhes.

    • No campo Evento, selecione um evento de gatilho. O padrão é google.cloud.storage.object.v1.finalized.

    • Opcionalmente, no campo Conta de serviço, selecione uma conta de serviço a ser usada como a identidade do acionador do Eventarc. Consulte Identidade do gatilho para mais informações.

  6. Clique em Salvar acionador.

Entrega de eventos

Os gatilhos do Cloud Storage são implementados com notificações do Pub/Sub para Cloud Storage. Os eventos estão sujeitos às garantias de entrega de notificações do Pub/Sub.

Um bucket do Cloud Storage pode ter até 10 configurações de notificação definidas para gatilho de um evento específico. Exceder os limites de notificações do bucket fará com que outras implantações de função falhem com um erro como este:

Cloud Storage bucket ...: Pub/Sub notification limit reached

Consulte Cotas e limites do Cloud Storage para saber mais.

Próximas etapas