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:

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 você exclui um objeto 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 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, Cloud Run Admin, Eventarc, Cloud Logging, Pub/Sub e Cloud Storage:

    Ativar as APIs

Defina os papéis necessários

Você ou seu administrador precisa conceder à conta do implantador, à identidade do gatilho e, opcionalmente, ao agente de serviço do Pub/Sub os seguintes papéis do IAM.

Papéis necessários para a conta do implantador

Para ter 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:

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 por meio de papéis personalizados ou de 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.

Papéis necessários para a identidade do gatilho

  1. Anote as propriedades da conta de serviço padrão do Compute Engine, porque você vai anexá-la a um gatilho do Eventarc para representar a identidade do acionador para fins de teste. Essa conta de serviço é criada automaticamente depois de ativar ou usar um serviço do Google Cloud que usa o Compute Engine e com o seguinte formato de e-mail:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Substitua PROJECT_NUMBER pelo número do seu projeto Google Cloud. Encontre o número do projeto na página Boas-vindas do console do Google Cloud ou executando o seguinte comando:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    Para ambientes de produção, é altamente recomendável criar uma nova conta de serviço, conceder a ela um ou mais papéis do IAM que contenham as permissões mínimas necessárias, bem como seguir o princípio de privilégio mínimo.

  2. Por padrão, os serviços do Cloud Run só podem ser chamados por proprietários do projeto, editores do projeto e administradores e invocadores do Cloud Run. É possível controlar o acesso por serviço. No entanto, para fins de teste, conceda o papel de chamador do Cloud Run (run.invoker) no projeto Google Cloud à conta de serviço do Compute Engine. Isso concede o papel em todos os serviços e jobs do Cloud Run em um projeto. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    Se você criar um gatilho para um serviço autenticado do Cloud Run sem conceder o papel de chamador do Cloud Run, o gatilho será criado com sucesso e estará ativo. No entanto, o acionador não funcionará conforme o esperado e uma mensagem semelhante à seguinte aparecerá nos registros:

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  3. Conceda o papel de receptor de eventos do Eventarc (roles/eventarc.eventReceiver) no projeto à conta de serviço padrão do Compute Engine para que o gatilho do Eventarc possa receber eventos de provedores de eventos. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver

Papel necessário para o agente de serviço do Pub/Sub

  • Se você ativou o agente de serviço do Cloud Pub/Sub até 8 de abril de 2021, para oferecer compatibilidade com solicitações push autenticadas do Pub/Sub, conceda o papel de Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) ao agente de serviço. Caso contrário, esse papel é concedido por padrão: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Criar um gatilho para serviços

É possível especificar um acionador depois de implantar um serviço.

Clique na guia para ver instruções usando a ferramenta de sua preferência.

Console

  1. Implante seu serviço do Cloud Run usando contêineres ou da 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 "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. 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.

gcloud

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

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

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=SERVICE  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=PROJECT_ID-bucket" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Substitua:

    • TRIGGER_NAME pelo nome do gatilho.

    • EVENTARC_TRIGGER_LOCATION com o local do 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. Para mais informações, consulte Locais do Eventarc.

    • SERVICE pelo nome do serviço que você está implantando.

    • REGION pela região do Cloud Run do serviço. Por exemplo, europe-west1.

    • PROJECT_NUMBER pelo número do projeto Google Cloud . 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 gatilho do Eventarc precisa ter permissão para invocar o serviço. Por padrão, o Cloud Run usa a conta de serviço de computação padrão.

    Cada flag event-filters especifica um tipo de evento, e a função é acionada somente quando um evento atende a todos os critérios especificados nas flags event-filters. Cada gatilho precisa ter uma flag event-filters especificando um tipo de evento compatível, como um novo documento gravado no Firestore ou um arquivo enviado para o Cloud Storage. Não é possível mudar o tipo de filtro de evento depois da criação. Para mudar o tipo de filtro de evento, crie um novo gatilho e exclua o antigo. Opcional: é possível repetir a flag --event-filters com um filtro compatível no formato ATTRIBUTE=VALUE para adicionar mais filtros.

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

Clique na guia para ver instruções usando a ferramenta de sua preferência.

Console

Ao usar o console do Google Cloud para criar uma função, você também pode adicionar um gatilho a ela. Siga estas etapas para criar um gatilho 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. 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 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.

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

    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.

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

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 código de amostra para implantar sua função:

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

    Substitua:

    • FUNCTION pelo 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 é 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 com o ambiente de imagem base da 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 com 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 eventos:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=PROJECT_ID-bucket" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Substitua:

    • TRIGGER_NAME pelo nome do gatilho.

    • EVENTARC_TRIGGER_LOCATION com o local do 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 a função na mesma região. Para mais informações, consulte Locais do Eventarc.

    • FUNCTION pelo nome da função que você está implantando.

    • REGION pela região do Cloud Run da função.

    • PROJECT_NUMBER pelo número do projeto Google Cloud . 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 gatilho do Eventarc precisa ter permissão para invocar a função. Por padrão, o Cloud Run usa a conta de serviço de computação padrão.

    Cada flag event-filters especifica um tipo de evento, e a função é acionada somente quando um evento atende a todos os critérios especificados nas flags event-filters. Cada gatilho precisa ter uma flag event-filters especificando um tipo de evento compatível, como um novo documento gravado no Firestore ou um arquivo enviado para o Cloud Storage. Não é possível mudar o tipo de filtro de evento depois da criação. Para mudar o tipo de filtro de evento, crie um novo gatilho e exclua o antigo. Opcional: é possível repetir a flag --event-filters com um filtro compatível no formato ATTRIBUTE=VALUE para adicionar mais filtros.

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 em 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