Criar acionadores com base em eventos do Cloud Storage

No Cloud Run, é possível acionar serviços do Cloud Storage usando o Eventarc, em resposta a mudanças no Cloud Storage.

Ao especificar um gatilho do Cloud Storage para seu serviço, você escolhe um tipo de evento e um bucket do Cloud Storage. Como resultado desse gatilho, seu serviço é chamado sempre que ocorre uma mudança em um objeto (arquivo) no bucket especificado.

Para que seu serviço seja acionado por um evento em um bucket do Cloud Storage, o serviço e o bucket precisam estar no mesmo projeto Google Cloud .

Para instruções detalhadas e exemplos de código sobre como criar gatilhos com base em eventos do Cloud Storage, consulte os seguintes tutoriais:

• Acionar serviços do Cloud Storage usando o Eventarc

• Acionar funções do Cloud Storage usando o Eventarc. Também é possível encontrar um exemplo de código no console Google Cloud que demonstra como acionar uma função em resposta a eventos do Cloud Storage depois de implantar a função do Cloud Run com um gatilho do Cloud Storage.

Tipos de eventos do Cloud Storage compatíveis

O Cloud Run é compatível com os seguintes tipos de eventos do Cloud Storage:

Evento	Tipo de evento	Descrição
Objeto finalizado	google.cloud.storage.object.v1.finalized (pelo Eventarc)	Isso ocorre quando você cria um objeto ou substitui um objeto existente, e o Cloud Storage cria uma nova geração desse objeto.
Objeto excluído	google.cloud.storage.object.v1.deleted (pelo Eventarc)	Isso ocorre quando um objeto é excluído de maneira reversível. Para mais informações, consulte Exclusão reversível.
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. Para mais informações, consulte Controle de versão de objeto.
Metadados de objetos atualizados	google.cloud.storage.object.v1.metadataUpdated (pelo Eventarc)	Ocorre quando você muda os metadados de um objeto existente.

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

Antes de começar

1. Verifique se você configurou um novo projeto para o Cloud Run conforme descrito na página de configuração.

2. Ative as APIs Artifact Registry, Cloud Build, API Cloud Run Admin, Eventarc, Cloud Logging, Pub/Sub e Cloud Storage:

   Ativar as APIs

3. Conceda as permissões e os papéis necessários do IAM.

Papéis necessários para a conta do implantador

Para receber as permissões necessárias para acionar eventos do Cloud Storage, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

• Desenvolvedor de origem do Cloud Run (roles/run.sourceDeveloper)
• Acessador de exibição de registros (roles/logging.viewAccessor)
• Administrador de projetos do IAM (roles/resourcemanager.projectIamAdmin)
• Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
• Usuário da conta de serviço (roles/iam.serviceAccountUser)
• Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Por padrão, as permissões do Cloud Build incluem permissões para upload e download de artefatos do Artifact Registry.

Criar um gatilho para serviços

Depois de implantar um serviço, é possível configurar um acionador usando o console Google Cloud , a Google Cloud CLI ou o Terraform.

Console

1. Implante seu serviço do Cloud Run usando contêineres ou de origem.

2. No Google Cloud console, acesse o Cloud Run:

   Acesse o Cloud Run

3. Na lista de serviços, clique em um serviço atual.

4. Na página de detalhes do serviço, acesse a guia Gatilhos.

5. Clique em Adicionar gatilho e selecione Gatilho do Cloud Storage.

6. No painel Gatilho do Eventarc, modifique os detalhes do gatilho da seguinte maneira:

   1. No campo Nome do gatilho, digite um nome ou use o nome padrão.

   2. Selecione um Tipo de acionador na lista para especificar um dos seguintes tipos de acionador:

      • Fontes do Google para especificar acionadores para Pub/Sub, Cloud Storage, Firestore, e outros provedores de eventos do Google.

      • Terceiros para integração com provedores que não são do Google que oferecem uma origem do Eventarc. Para mais informações, consulte Eventos de terceiros no Eventarc.

   3. Selecione Cloud Storage na lista Provedor de eventos para escolher um produto que ofereça o tipo de evento para acionar seu serviço. Para ver a lista de provedores de eventos, consulte Provedores e destinos de eventos.

   4. Selecione google.cloud.storage.object.v1.finalized na lista Tipo de evento. A configuração do gatilho varia de acordo com o tipo de evento compatível: Para mais informações, consulte Tipos de eventos.

   5. 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.

   6. Se o campo Região estiver ativado, selecione um local para o gatilho do Eventarc. Em geral, o local de um gatilho do Eventarc precisa corresponder ao local do recurso Google Cloud que você quer monitorar para eventos. Na maioria dos cenários, você também precisa implantar o serviço na mesma região. Consulte Noções básicas sobre locais do Eventarc para mais detalhes sobre locais de acionador do Eventarc.

   7. No campo Conta de serviço, selecione uma conta de serviço. Os acionadores do Eventarc são vinculados a contas de serviço para usar como uma identidade ao invocar o serviço. A conta de serviço do acionador do Eventarc precisa ter permissão para invocar o serviço. Por padrão, o Cloud Run usa a conta de serviço padrão do Compute Engine.

   8. Se quiser, especifique o caminho do URL do serviço para enviar a solicitação recebida. Esse é o caminho relativo no serviço de destino para o qual os eventos do gatilho precisam ser enviados. Por exemplo: /, /route, route e route/subroute.

   9. Se quiser ativar novas tentativas em caso de falha na tentativa de entrega, marque a caixa de seleção Ativar novas tentativas em caso de falha. Caso contrário, o comportamento padrão é uma única tentativa de entrega sem novas tentativas. Para mais informações, consulte Repetir eventos.

   10. Depois de preencher os campos obrigatórios, clique em Salvar gatilho.

7. Depois de criar o gatilho, verifique a integridade garantindo que haja uma marca de seleção na guia Gatilhos.

   Observação: o gatilho é criado imediatamente, mas pode levar até dois minutos para que ele seja propagado e filtre eventos.

gcloud

1. Implante seu serviço do Cloud Run usando contêineres ou de origem.

2. Execute o comando a seguir para criar um gatilho que filtra e encaminha eventos:

   gcloud eventarc triggers create TRIGGER_NAME  \
       --location=LOCATION \
       --destination-run-service=DESTINATION_RUN_SERVICE  \
       --destination-run-region=DESTINATION_RUN_REGION \
       --event-filters="type=EVENT_FILTER_TYPE" \
       --event-filters="bucket=BUCKET" \
       --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
   

   Substitua:

   • TRIGGER_NAME: o ID do gatilho ou um identificador totalmente qualificado.
   • LOCATION: o local do gatilho do Eventarc. Como alternativa, é possível definir a propriedade eventarc/location, por exemplo: gcloud config set eventarc/location us-central1.

     Para evitar problemas de desempenho e residência de dados, o local precisa corresponder ao do serviço Google Cloud que está gerando eventos. Saiba mais em Locais do Eventarc.

   • DESTINATION_RUN_SERVICE: o nome do serviço do Cloud Run que recebe os eventos do gatilho. O serviço pode estar em qualquer um dos locais compatíveis com o Cloud Run e não precisa estar no mesmo local que o gatilho. No entanto, o serviço precisa estar no mesmo projeto que o gatilho e receberá eventos como solicitações POST HTTP enviadas para o caminho de URL raiz (/) sempre que o evento for gerado.
   • DESTINATION_RUN_REGION: (opcional) o local do Cloud Run em que o serviço de destino do Cloud Run pode ser encontrado. Se não especificado, presume-se que o serviço está na mesma região que o gatilho
   • EVENT_FILTER_TYPE: o identificador do evento. Um evento é gerado quando uma chamada de API para o método é bem-sucedida. Para operações de longa duração, o evento só é gerado no final da operação e apenas se a ação for realizada com êxito. Para conferir uma lista de tipos de evento compatíveis, consulte Tipos de evento do Google compatíveis com o Eventarc.
   • BUCKET: é o identificador exclusivo global do bucket do Cloud Storage.
   • SERVICE_ACCOUNT_NAME: o nome da conta de serviço gerenciada pelo usuário.
   • PROJECT_ID: o ID do projeto Google Cloud .

   Observações:

   • A sinalização --event-filters="type=EVENT_FILTER_TYPE" é obrigatória. Se nenhum outro filtro de evento for definido, a correspondência dos eventos de todos os recursos será feita.
   • Não é possível alterar EVENT_FILTER_TYPE depois da criação. Para mudar EVENT_FILTER_TYPE, crie um novo gatilho e exclua o antigo.
   • Cada gatilho pode ter vários filtros de eventos separados por vírgula em uma sinalização --event-filters=[ATTRIBUTE=VALUE,...] ou repita a sinalização para adicionar mais filtros. Somente eventos que correspondam a todos os filtros são enviados para o destino. Caracteres curinga e expressões regulares não são compatíveis. No entanto, ao usar a sinalização --event-filters-path-pattern, é possível definir um padrão de caminho do recurso.
   • Opcionalmente, para especificar uma única tentativa de entrega de evento sem novas tentativas, use a flag --max-retry-attempts. O único valor válido é 1. Se você omitir a flag, o comportamento padrão de repetição será aplicado. Para mais informações, consulte Repetir eventos.
   • Outras flags estão disponíveis. Para obter mais informações, consulte gcloud eventarc triggers create.

Terraform

Para criar um gatilho do Eventarc para um serviço do Cloud Run, consulte Criar um gatilho usando o Terraform.

Criar um gatilho para funções

Depois de implantar uma função, é possível configurar um gatilho usando o console Google Cloud , a Google Cloud CLI ou o Terraform.

Console

Ao usar o console do Google Cloud para criar uma função, também é possível adicionar um acionador a ela. Siga estas etapas para criar um acionador para sua função:

1. No Google Cloud console, acesse o Cloud Run:

   Acessar o Cloud Run

2. Clique em Escrever uma função e insira os detalhes dela. Para mais informações sobre como configurar funções durante a implantação, consulte Implantar funções.

3. Na seção Gatilho, clique em Adicionar gatilho.

4. Selecione Gatilho do Cloud Storage.

5. No painel Gatilho do Eventarc, modifique os detalhes do gatilho da seguinte maneira:

   1. Insira um nome para o gatilho no campo Nome do gatilho ou use o nome padrão.

   2. Selecione um Tipo de acionador na lista:

      • Fontes do Google para especificar acionadores para Pub/Sub, Cloud Storage, Firestore, e outros provedores de eventos do Google.

      • Terceiros para integração com provedores que não são do Google que oferecem uma origem do Eventarc. Para mais informações, consulte Eventos de terceiros no Eventarc.

   3. Selecione Cloud Storage na lista Provedor de eventos para escolher um produto que ofereça o tipo de evento para acionar sua função. Para ver a lista de provedores de eventos, consulte Provedores e destinos de eventos.

   4. Selecione google.cloud.storage.object.v1.finalized na lista Tipo de evento. A configuração do gatilho varia de acordo com o tipo de evento compatível: Para mais informações, consulte Tipos de eventos.

   5. Deixe o campo Tipo de conteúdo de dados de eventos no estado em que se encontra.

   6. 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.

   7. Se o campo Região estiver ativado, selecione um local para o gatilho do Eventarc. Em geral, o local de um gatilho do Eventarc precisa corresponder ao local do recursoGoogle Cloud que você quer monitorar para eventos. Na maioria dos cenários, você também precisa implantar a função na mesma região. Consulte Noções básicas sobre locais do Eventarc para mais detalhes sobre locais de acionador do Eventarc.

   8. No campo Conta de serviço, selecione uma conta de serviço. Os acionadores do Eventarc são vinculados a contas de serviço para usar como uma identidade ao invocar a função. A conta de serviço do acionador do Eventarc precisa ter permissão para invocar a função. Por padrão, o Cloud Run usa a conta de serviço padrão do Compute Engine.

   9. Se quiser, especifique o caminho do URL do serviço para enviar a solicitação recebida. Esse é o caminho relativo no serviço de destino para o qual os eventos do gatilho precisam ser enviados. Por exemplo: /, /route, route e route/subroute.

   10. Se quiser ativar novas tentativas em caso de falha na tentativa de entrega, marque a caixa de seleção Ativar novas tentativas em caso de falha. Caso contrário, o comportamento padrão é uma única tentativa de entrega sem novas tentativas. Para mais informações, consulte Repetir eventos.

6. Depois de preencher os campos obrigatórios, clique em Salvar gatilho.

7. Clique em Criar.

8. Na guia Origem, edite o código-fonte se necessário e selecione Salvar e implantar novamente.

gcloud

Ao criar uma função usando a CLI gcloud, primeiro é necessário implantar a função e, em seguida, criar um gatilho. Siga estas etapas para criar um gatilho para sua função:

1. Execute o seguinte comando no diretório que contém o exemplo de código para implantar sua função:

   gcloud run deploy FUNCTION \
       --source . \
       --function FUNCTION_ENTRYPOINT \
       --base-image BASE_IMAGE_ID \
       --region REGION
   

   Substitua:

   • FUNCTION: o nome da função que você está implantando. É possível omitir esse parâmetro inteiramente, mas será solicitado o nome, se você omiti-lo.

   • FUNCTION_ENTRYPOINT: o ponto de entrada da função no código-fonte. Esse é o código que o Cloud Run executa quando a função é executada. O valor dessa sinalização precisa ser um nome de função ou de classe totalmente qualificada no código-fonte.

   • BASE_IMAGE_ID: o ambiente de imagem de base para sua função. Para mais detalhes sobre as imagens de base e os pacotes incluídos em cada imagem, consulte Imagens de base dos ambientes de execução.

   • REGION: a Google Cloud região em que você quer implantar a função. Por exemplo, europe-west1.

2. Execute o comando a seguir para criar um gatilho que filtra e encaminha eventos:

   gcloud eventarc triggers create TRIGGER_NAME  \
       --location=LOCATION \
       --destination-run-service=FUNCTION  \
       --destination-run-region=DESTINATION_RUN_REGION \
       --event-filters="type=EVENT_FILTER_TYPE" \
       --event-filters="bucket=BUCKET" \
       --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
   

   Substitua:

   • TRIGGER_NAME: o ID do gatilho ou um identificador totalmente qualificado.
   • LOCATION: o local do gatilho do Eventarc. Como alternativa, é possível definir a propriedade eventarc/location, por exemplo: gcloud config set eventarc/location us-central1.

     Para evitar problemas de desempenho e residência de dados, o local precisa corresponder ao do serviço Google Cloud que está gerando eventos. Saiba mais em Locais do Eventarc.

   • FUNCTION: o nome da função implantada do Cloud Run que recebe os eventos do gatilho.
   • DESTINATION_RUN_REGION: (opcional) o local do Cloud Run em que a função de destino do Cloud Run pode ser encontrada. Se não especificado, presume-se que a função está na mesma região que o gatilho.
   • EVENT_FILTER_TYPE: o identificador do evento. Um evento é gerado quando uma chamada de API para o método é bem-sucedida. Para operações de longa duração, o evento só é gerado no final da operação e apenas se a ação for realizada com êxito. Para conferir uma lista de tipos de evento compatíveis, consulte Tipos de evento do Google compatíveis com o Eventarc.
   • BUCKET: é o identificador exclusivo global do bucket do Cloud Storage.
   • SERVICE_ACCOUNT_NAME: o nome da conta de serviço gerenciada pelo usuário.
   • PROJECT_ID: o ID do projeto Google Cloud .

   Observações:

   • A sinalização --event-filters="type=EVENT_FILTER_TYPE" é obrigatória. Se nenhum outro filtro de evento for definido, a correspondência dos eventos de todos os recursos será feita.
   • Não é possível alterar EVENT_FILTER_TYPE depois da criação. Para mudar EVENT_FILTER_TYPE, crie um novo gatilho e exclua o antigo.
   • Cada gatilho pode ter vários filtros de eventos separados por vírgula em uma sinalização --event-filters=[ATTRIBUTE=VALUE,...] ou repita a sinalização para adicionar mais filtros. Somente eventos que correspondam a todos os filtros são enviados para o destino. Caracteres curinga e expressões regulares não são compatíveis. No entanto, ao usar a sinalização --event-filters-path-pattern, é possível definir um padrão de caminho do recurso.
   • Opcionalmente, para especificar uma única tentativa de entrega de evento sem novas tentativas, use a flag --max-retry-attempts. O único valor válido é 1. Se você omitir a flag, o comportamento padrão de repetição será aplicado. Para mais informações, consulte Repetir eventos.
   • Outras flags estão disponíveis. Para obter mais informações, consulte gcloud eventarc triggers create.

Terraform

Para criar um gatilho do Eventarc para uma função do Cloud Run, consulte Criar um gatilho usando o Terraform.

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

Para contornar essa limitação, gerencie seu próprio tópico do Pub/Sub e registre-o para receber notificações do Cloud Storage do tipo que você quer que sua função responda. Por exemplo, é possível configurar uma única notificação para o evento escolhido (como criação de objeto) em um tópico do Pub/Sub. Em seguida, tenha quantos assinantes de função forem necessários para o tópico processar o evento e distribuí-lo para vários destinos. Exemplo:

1. Crie seu próprio tópico do Pub/Sub.
2. Crie uma única configuração de notificação no bucket do Cloud Storage que seja acionada por um evento específico (como OBJECT_FINALIZE para criação de objetos) e envie o evento para seu único tópico do Pub/Sub.
3. Crie uma ou mais funções acionadas pelo seu tópico do Pub/Sub.

Isso resulta em uma configuração de notificação do Cloud Storage, um tópico do Pub/Sub e quantas funções forem necessárias (dentro dos limites de entrega muito altos permitidos pelo Pub/Sub).

Consulte Cotas e limites do Cloud Storage para saber mais sobre as limitações do serviço.

Próximas etapas

• Saiba como acionar com eventos.
• Saiba como acionar serviços do Cloud Storage usando o Eventarc.
• Saiba como acionar funções do Cloud Storage usando o Eventarc.