Crie acionadores a partir de eventos do Cloud Storage

No Cloud Run, pode acionar serviços a partir do Cloud Storage através do Eventarc, em resposta a alterações no Cloud Storage.

Quando especifica um acionador do Cloud Storage para o seu serviço, escolhe um tipo de evento e especifica um contentor do Cloud Storage. Como resultado deste acionador, o seu serviço é chamado sempre que ocorre uma alteração num objeto (ficheiro) no contentor especificado.

Para que o seu serviço seja acionado por um evento num contentor do Cloud Storage, o serviço e o contentor têm de estar no mesmo Google Cloud projeto.

Para obter instruções detalhadas e exemplos de código para criar acionadores a partir de eventos do Cloud Storage, consulte os seguintes tutoriais:

Tipos de eventos do Cloud Storage suportados

O Cloud Run suporta os seguintes tipos de eventos do Cloud Storage:

Evento Tipo de evento Descrição
Objeto finalizado
  • google.cloud.storage.object.v1.finalized (através do Eventarc)
 Ocorre quando cria um novo objeto ou substitui um objeto existente e o Cloud Storage cria uma nova geração desse objeto.
Objeto eliminado
  • google.cloud.storage.object.v1.deleted (através do Eventarc)
 Ocorre quando um objeto é eliminado temporariamente. Para mais informações, consulte o artigo Eliminação temporária.
Objeto arquivado
  • google.cloud.storage.object.v1.archived (através do Eventarc)
 Ocorre quando uma versão publicada de um objeto se torna uma versão não atual. Para mais informações, consulte o artigo Controlo de versões de objetos.
Metadados do objeto atualizados
  • google.cloud.storage.object.v1.metadataUpdated (através do Eventarc)
 Ocorre quando altera os metadados de um objeto existente.

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

Antes de começar

  1. Certifique-se de que 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 API, Eventarc, Cloud Logging, Pub/Sub e Cloud Storage:

    Ative as APIs

Defina funções necessárias

O utilizador ou o administrador tem de conceder à conta de implementação, à identidade do acionador e, opcionalmente, ao agente do serviço Pub/Sub as seguintes funções de IAM.

Funções necessárias para a conta do implementador

Para receber as autorizações de que precisa para acionar a partir de eventos do Cloud Storage, peça ao seu administrador para lhe conceder as seguintes funções do IAM no seu projeto:

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Tenha em atenção que, por predefinição, as autorizações do Cloud Build incluem autorizações para carregar e transferir artefactos do Artifact Registry.

Funções necessárias para a identidade do acionador

  1. Tome nota da conta de serviço predefinida do Compute Engine, uma vez que a vai anexar a um acionador do Eventarc para representar a identidade do acionador para fins de teste. Esta conta de serviço é criada automaticamente depois de ativar ou usar um Google Cloud serviço que usa o Compute Engine e com o seguinte formato de email:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

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

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

    Para ambientes de produção, recomendamos vivamente que crie uma nova conta de serviço e lhe conceda uma ou mais funções do IAM que contenham as autorizações mínimas necessárias e siga o princípio do privilégio mínimo.

  2. Por predefiniçã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. Pode controlar o acesso por serviço. No entanto, para fins de teste, conceda a função de invocador do Cloud Run (run.invoker) no Google Cloud projeto à conta de serviço do Compute Engine. Isto concede a função em todos os serviços e tarefas do Cloud Run num projeto. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    Tenha em atenção que, se criar um acionador para um serviço do Cloud Run autenticado sem conceder a função de invocador do Cloud Run, o acionador é criado com êxito e está ativo. No entanto, o acionador não funciona conforme esperado e é apresentada uma mensagem semelhante à seguinte nos registos:

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

Função necessária para o agente do serviço Pub/Sub

  • Se ativou o agente do serviço Cloud Pub/Sub a 8 de abril de 2021 ou antes, para suportar pedidos de envio do Pub/Sub autenticados, conceda a função de criador de tokens de conta de serviço (roles/iam.serviceAccountTokenCreator) ao agente do serviço. Caso contrário, esta função é concedida por predefinição: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Crie um acionador para serviços

Pode especificar um acionador depois de implementar um serviço.

Clique no separador para ver instruções sobre como usar a ferramenta da sua escolha.

Consola

  1. Implemente o seu serviço do Cloud Run através de contentores ou a partir de origem.

  2. Na Google Cloud consola, aceda ao Cloud Run:

    Aceda ao Cloud Run

  3. Na lista de serviços, clique num serviço existente.

  4. Na página Detalhes do serviço, navegue para o separador Acionadores.

  5. Clique em Adicionar acionador e selecione Acionador do Cloud Storage.

  6. No painel Acionador do Eventarc, modifique os detalhes do acionador da seguinte forma:

    1. No campo Nome do acionador, introduza um nome para o acionador ou use o nome predefinido.

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

      • Origens Google para especificar acionadores para o Pub/Sub, o Cloud Storage, o Firestore e outros fornecedores de eventos Google.

      • Terceiros para integrar com fornecedores que não sejam da Google que oferecem uma origem do Eventarc. Para mais informações, consulte o artigo Eventos de terceiros no Eventarc.

    3. Selecione Cloud Storage na lista Fornecedor de eventos para selecionar um produto que forneça o tipo de evento para acionar o seu serviço. Para ver a lista de fornecedores de eventos, consulte o artigo Fornecedores de eventos e destinos.

    4. Selecione google.cloud.storage.object.v1.finalized na lista Tipo de evento. A configuração do acionador varia consoante o tipo de evento suportado. Para mais informações, consulte o artigo Tipos de eventos.

    5. No campo Bucket, clique em Procurar para selecionar um bucket do Cloud Storage para monitorizar o acionador. As alterações aos objetos neste contentor vão acionar chamadas para a sua função.

    6. Se o campo Região estiver ativado, selecione uma localização para o acionador do Eventarc. Em geral, a localização de um acionador do Eventarc deve corresponder à localização do recurso que quer monitorizar para eventos. Google Cloud Na maioria dos cenários, também deve implementar o serviço na mesma região. Consulte o artigo Compreenda as localizações do Eventarc para ver mais detalhes sobre as localizações dos acionadores do Eventarc.

    7. No campo Conta de serviço, selecione uma conta de serviço. Os acionadores do Eventarc estão associados a contas de serviço para usar como identidade quando invocam o seu serviço. A conta de serviço do acionador do Eventarc tem de ter a autorização para invocar o seu serviço. Por predefinição, o Cloud Run usa a conta de serviço predefinida do Compute Engine.

    8. Opcionalmente, especifique o caminho do URL do serviço para o qual enviar o pedido recebido. Este é o caminho relativo no serviço de destino para o qual os eventos do acionador devem ser enviados. Por exemplo: /, /route, route e route/subroute.

    9. Depois de preencher os campos obrigatórios, clique em Guardar acionador.

  7. Depois de criar o acionador, verifique o respetivo estado certificando-se de que existe uma marca de verificação no separador Acionadores.

gcloud

  1. Implemente o seu serviço do Cloud Run através de contentores ou a partir de origem.

  2. Execute o seguinte comando para criar um acionador 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

    Substituir:

    • TRIGGER_NAME com o nome do acionador.

    • EVENTARC_TRIGGER_LOCATION com a localização do acionador do Eventarc. Em geral, a localização de um acionador do Eventarc deve corresponder à localização do Google Cloud recurso que quer monitorizar para eventos. Na maioria dos cenários, também deve implementar o seu serviço na mesma região. Para mais informações, consulte o artigo Localizações do Eventarc.

    • SERVICE com o nome do serviço que está a implementar.

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

    • PROJECT_NUMBER com o seu Google Cloud número do projeto. Os acionadores do Eventarc estão associados a contas de serviço para usar como identidade quando invoca o seu serviço. A conta de serviço do seu acionador do Eventarc tem de ter autorização para invocar o seu serviço. Por predefinição, o Cloud Run usa a conta de serviço de computação predefinida.

    Cada sinalização event-filters especifica um tipo de evento, com a função a ser acionada apenas quando um evento cumpre todos os critérios especificados nas respetivas sinalizações event-filters. Cada acionador tem de ter uma flag event-filters que especifique um tipo de evento suportado, como um novo documento escrito no Firestore ou um ficheiro carregado para o Cloud Storage. Não pode alterar o tipo de filtro de eventos após a criação. Para alterar o tipo de filtro de eventos, tem de criar um novo acionador e eliminar o antigo. Opcionalmente, pode repetir a flag --event-filters com um filtro suportado no formato ATTRIBUTE=VALUE para adicionar mais filtros.

Terraform

Para criar um acionador do Eventarc para um serviço do Cloud Run, consulte o artigo Crie um acionador com o Terraform.

Crie um acionador para funções

Clique no separador para ver instruções sobre como usar a ferramenta da sua escolha.

Consola

Quando usa a Google Cloud consola para criar uma função, também pode adicionar um acionador à sua função. Siga estes passos para criar um acionador para a sua função:

  1. Na Google Cloud consola, aceda ao Cloud Run:

    Aceda ao Cloud Run

  2. Clique em Escrever uma função e introduza os detalhes da função. Para mais informações sobre a configuração de funções durante a implementação, consulte Implementar funções.

  3. Na secção Acionador, clique em Adicionar acionador.

  4. Selecione Acionador do Cloud Storage.

  5. No painel Acionador do Eventarc, modifique os detalhes do acionador da seguinte forma:

    1. Introduza um nome para o acionador no campo Nome do acionador ou use o nome predefinido.

    2. Selecione um Tipo de acionador na lista:

      • Origens Google para especificar acionadores para o Pub/Sub, o Cloud Storage, o Firestore e outros fornecedores de eventos Google.

      • Terceiros para integrar com fornecedores que não sejam da Google que oferecem uma origem do Eventarc. Para mais informações, consulte o artigo Eventos de terceiros no Eventarc.

    3. Selecione Cloud Storage na lista Fornecedor de eventos para selecionar um produto que forneça o tipo de evento para acionar a sua função. Para ver a lista de fornecedores de eventos, consulte o artigo Fornecedores de eventos e destinos.

    4. Selecione google.cloud.storage.object.v1.finalized na lista Tipo de evento. A configuração do acionador varia consoante o tipo de evento suportado. Para mais informações, consulte o artigo Tipos de eventos.

    5. No campo Bucket, clique em Procurar para selecionar um bucket do Cloud Storage para monitorizar o acionador. As alterações aos objetos neste contentor vão acionar chamadas para a sua função.

    6. Se o campo Região estiver ativado, selecione uma localização para o acionador do Eventarc. Em geral, a localização de um acionador do Eventarc deve corresponder à localização do recurso que quer monitorizar para eventos. Google Cloud Na maioria dos cenários, também deve implementar a função na mesma região. Consulte o artigo Compreenda as localizações do Eventarc para ver mais detalhes sobre as localizações dos acionadores do Eventarc.

    7. No campo Conta de serviço, selecione uma conta de serviço. Os acionadores do Eventarc estão associados a contas de serviço para usar como identidade quando invocam a sua função. A conta de serviço do acionador do Eventarc tem de ter a autorização para invocar a sua função. Por predefinição, o Cloud Run usa a conta de serviço predefinida do Compute Engine.

    8. Opcionalmente, especifique o caminho do URL do serviço para o qual enviar o pedido recebido. Este é o caminho relativo no serviço de destino para o qual os eventos do acionador devem ser enviados. Por exemplo: /, /route, route e route/subroute.

  6. Depois de preencher os campos obrigatórios, clique em Guardar acionador.

gcloud

Quando cria uma função através da CLI gcloud, tem primeiro de implementar a função e, em seguida, criar um acionador. Siga estes passos para criar um acionador para a sua função:

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

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

    Substituir:

    • FUNCTION com o nome da função que está a implementar. Pode omitir este parâmetro por completo, mas é-lhe pedido o nome se o omitir.

    • FUNCTION_ENTRYPOINT com o ponto de entrada da sua função no código-fonte. Este é o código que o Cloud Run executa quando a sua função é executada. O valor desta flag tem de ser um nome de função ou um nome de classe totalmente qualificado que exista no seu código-fonte.

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

    • REGION com a Google Cloud região onde quer implementar a sua função. Por exemplo, europe-west1.

  2. Execute o seguinte comando para criar um acionador 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

    Substituir:

    • TRIGGER_NAME com o nome do acionador.

    • EVENTARC_TRIGGER_LOCATION com a localização do acionador do Eventarc. Em geral, a localização de um acionador do Eventarc deve corresponder à localização do Google Cloud recurso que quer monitorizar para eventos. Na maioria dos cenários, também deve implementar a função na mesma região. Para mais informações, consulte o artigo Localizações do Eventarc.

    • FUNCTION com o nome da função que está a implementar.

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

    • PROJECT_NUMBER com o seu Google Cloud número do projeto. Os acionadores do Eventarc estão associados a contas de serviço para serem usados como uma identidade quando invocam a sua função. A conta de serviço do seu acionador do Eventarc tem de ter autorização para invocar a sua função. Por predefinição, o Cloud Run usa a conta de serviço de computação predefinida.

    Cada sinalização event-filters especifica um tipo de evento, com a função a ser acionada apenas quando um evento cumpre todos os critérios especificados nas respetivas sinalizações event-filters. Cada acionador tem de ter uma flag event-filters que especifique um tipo de evento suportado, como um novo documento escrito no Firestore ou um ficheiro carregado para o Cloud Storage. Não pode alterar o tipo de filtro de eventos após a criação. Para alterar o tipo de filtro de eventos, tem de criar um novo acionador e eliminar o antigo. Opcionalmente, pode repetir a flag --event-filters com um filtro suportado no formato ATTRIBUTE=VALUE para adicionar mais filtros.

Terraform

Para criar um acionador do Eventarc para uma função do Cloud Run, consulte o artigo Crie um acionador com o Terraform.

Entrega de eventos

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

Um contentor do Cloud Storage pode ter até 10 configurações de notificações definidas para serem acionadas para um evento específico. Exceder os limites de notificações do contentor faz com que as implementações de funções adicionais falhem com um erro semelhante ao seguinte:

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

Pode contornar esta limitação gerindo o seu próprio tópico do Pub/Sub e registando-o para receber notificações do Cloud Storage do tipo ao qual quer que a sua função responda. Por exemplo, pode configurar uma única notificação para o evento escolhido (como a criação de objetos) para um tópico do Pub/Sub. Em seguida, tenha tantos subscritores de funções quanto necessário para que o tópico processe o evento e o distribua para vários destinos. Por exemplo:

  1. Crie o seu próprio tópico Pub/Sub.
  2. Crie uma única configuração de notificação no seu contentor do Cloud Storage que é acionada num evento específico (como OBJECT_FINALIZE para a criação de objetos) e envia o evento para o seu único tópico do Pub/Sub.
  3. Crie uma função (ou funções) acionada pelo seu tópico Pub/Sub.

Isto resulta numa configuração de notificação do Cloud Storage, num tópico do Pub/Sub e em tantas funções quantas precisar (dentro dos limites de entrega muito elevados permitidos pelo Pub/Sub).

Consulte as cotas e os limites do Cloud Storage para saber mais acerca das limitações do Cloud Storage.

Passos seguintes