Rotear eventos do Cloud Storage para o Workflows

Um gatilho do Eventarc declara seu interesse em um determinado evento ou conjunto de eventos. Para configurar o roteamento de eventos, especifique filtros para o gatilho, incluindo a origem do evento e o serviço de destino.

Os eventos são entregues no formato CloudEvents por meio de uma solicitação HTTP. O serviço do Workflows converte o evento em um objeto JSON (seguindo a especificação do CloudEvents) e transmite o evento para a execução do fluxo de trabalho como um argumento do ambiente de execução do fluxo de trabalho. Verifique se o tamanho do evento não ultrapassa 512 KB. Eventos maiores que o tamanho máximo de argumentos do Workflows não acionarão execuções de fluxo de trabalho.

Estas instruções mostram como configurar o roteamento de eventos para que uma execução do fluxo de trabalho seja acionada em resposta a um evento Cloud Storage direto. Isso se aplica a um provedor de eventos do Cloud Storage. Para saber mais, consulte a lista de eventos diretos compatíveis.

Observação: se os eventos de registro diretos e de auditoria forem compatíveis com um provedor do Google, recomendamos criar um gatilho que filtre o evento direto. Os eventos diretos oferecem várias vantagens sobre os eventos de registro de auditoria. Para mais informações, consulte Rotas de eventos.

Preparar para criar um gatilho

Antes de criar um gatilho do Eventarc para um fluxo de trabalho de destino, conclua as tarefas a seguir.

Console

1. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

2. Ative as APIs Eventarc, Eventarc Publishing, Workflows e Workflow Executions.

   Ative as APIs

3. Se aplicável, ative a API relacionada aos eventos diretos. Por exemplo, para eventos Cloud Storage, ative a API Cloud Storage.

4. Se você ainda não tiver uma, crie uma conta de serviço gerenciada pelo usuário e conceda a ela os papéis e as permissões necessários para que o Eventarc gerencie eventos de um fluxo de trabalho de destino.

   1. No console do Google Cloud, acesse a página Contas de serviço.

      Acessar a página "Contas de serviço"

   2. Selecione o projeto.

   3. No campo Nome da conta de serviço, insira um nome. O Console do Google Cloud preenche o campo ID da conta de serviço com base nesse nome.

      No campo Descrição da conta de serviço, insira uma descrição. Por exemplo, Service account for event trigger.

   4. Clique em Criar e continuar.

   5. Para fornecer o acesso apropriado, na lista Selecionar um papel, escolha os papéis necessários do Identity and Access Management (IAM) para conceder à sua conta de serviço. Para mais informações, consulte Papéis e permissões para destinos do Workflows.

      Para papéis adicionais, clique em Adicionar outro papel e adicione cada papel adicional.

   6. Clique em Continuar.

   7. Para concluir a criação da conta de serviço, clique em Concluído.

5. Conceda o papel de Editor do Pub/Sub ao agente de serviço do Cloud Storage. Normalmente, é o agente [e-mail]. É possível recuperar o endereço de e-mail do agente de serviço do Cloud Storage.

   1. No console do Google Cloud, abra a página IAM.

      Acessar IAM

   2. Na linha do agente de serviço do Cloud Storage, clique em Editar principal. Se o agente de serviço não estiver listado, prossiga para a próxima etapa. O painel Editar acesso será aberto.

      1. Clique em Adicionar outro papel e pesquise o papel Editor do Pub/Sub.
      2. Selecione o papel.
      3. Clique em Save.

   3. Se o agente de serviço não estiver listado, clique em Conceder acesso. O painel Conceder acesso será aberto.

      1. No campo Novos principais, insira o endereço de e-mail do agente de serviço.
      2. Na lista Selecionar um papel, procure o papel Editor do Pub/Sub.
      3. Selecione o papel.
      4. Clique em Salvar.

gcloud

1. No Console do Google Cloud, ative o Cloud Shell.

   Ativar o Cloud Shell

   Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

2. Ative as APIs Eventarc, Eventarc Publishing, Workflows e Workflow Executions:

   gcloud services enable eventarc.googleapis.com \
       eventarcpublishing.googleapis.com \
       workflows.googleapis.com \
       workflowexecutions.googleapis.com
   

3. Se aplicável, ative a API relacionada aos eventos diretos. Por exemplo, para eventos Cloud Storage, ative storage.googleapis.com.

4. Se você ainda não tiver uma, crie uma conta de serviço gerenciada pelo usuário e conceda a ela os papéis e as permissões necessários para que o Eventarc possa gerenciar eventos de um fluxo de trabalho de destino.

   1. Crie a conta de serviço:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Substitua SERVICE_ACCOUNT_NAME pelo nome da conta de serviço. Ele precisa ter entre 6 e 30 caracteres e pode conter letras minúsculas, caracteres alfanuméricos e traços. Depois de criar uma conta de serviço, não é possível alterar o nome dela.

   2. Conceda os papéis ou as permissões necessários do Identity and Access Management (IAM). Para mais informações, consulte Papéis e permissões para destinos do Workflows.

5. Se estiver criando um gatilho para um evento direto do Cloud Storage, conceda o papel pubsub.publisher à conta de serviço do Cloud Storage:

   SERVICE_ACCOUNT="$(gsutil kms serviceaccount -p PROJECT_ID)"
   
   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:${SERVICE_ACCOUNT}" \
       --role="roles/pubsub.publisher"
   

Criar um gatilho

É possível criar um gatilho do Eventarc com um fluxo de trabalho implantado como receptor de eventos usando a CLI do Google Cloud (gcloud ou Terraform) ou o console do Google Cloud.

Observação: a filtragem é feita por meio de uma correspondência exata e não permite caracteres curinga ou expressões regulares.

Console

1. No Console do Google Cloud, acesse a página Gatilhos do Eventarc.

   Acessar gatilhos

2. Clique em Criar gatilho.
3. Digite um Nome de gatilho.

   Esse é o ID do gatilho e precisa começar com uma letra. Ele pode conter até 63 letras minúsculas, números ou hífens.

4. Em Tipo de gatilho, selecione Fontes do Google.
5. Na lista Provedor de eventos, selecione Cloud Storage.

   O nome do provedor de eventos usado na documentação do Google Cloud associada pode não ter o prefixo Cloud ou Google Cloud. Por exemplo, no console, o Memorystore para Redis é chamado de Google Cloud Memorystore para Redis.

6. Na lista Tipo de evento, nos eventos Diretos, selecione um tipo de evento:
   • google.cloud.storage.object.v1.archived: o evento é enviado quando uma versão ativa de um objeto é arquivada ou excluída. Este só é enviado para buckets com controle de versão.
   • google.cloud.storage.object.v1.delete: o 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ão, ele é enviado quando um objeto é excluído ou substituído.
   • google.cloud.storage.object.v1.finalized: o evento é enviado quando um novo objeto é criado (ou um objeto existente é substituído e uma nova geração desse objeto é criado) no bucket.
   • google.cloud.storage.object.v1.metadataUpdated: o evento é enviado quando o [metadata](/storage/docs/metadata) de um objeto existente é alterado.
7. Na lista Tipo de conteúdo de dados do evento, selecione a codificação do payload do evento.

   Para eventos diretos de Cloud Storage, ele precisa ser application/json.

8. Especifique ou procure o identificador exclusivo global do bucket do Cloud Storage.

   O bucket do Cloud Storage precisa residir no mesmo projeto do Google Cloud e na região ou multirregião que o gatilho do Eventarc.

9. Selecione uma Região.

   Os gatilhos do Cloud Storage para o Eventarc estão disponíveis em locais de região única, birregionais e multirregionais. O bucket do Cloud Storage precisa estar no mesmo projeto e região ou multirregião do Google Cloud que o gatilho do Eventarc.

   Os eventos são entregues usando notificações do Pub/Sub no Cloud Storage. A configuração de muitas notificações registradas no mesmo bucket pode esgotar o limite de notificações do bucket, conforme indicado pelo erro Cloud Storage bucket ...: Pub/Sub notification limit reached. É possível ter até 10 configurações de notificação definidas no bucket para acionar um determinado evento. Confira mais cotas e limitações na página Cotas e limites do Cloud Storage.

10. Selecione a conta de serviço que vai invocar seu serviço ou fluxo de trabalho.

    ou crie uma nova conta de serviço.

    Ele especifica o e-mail da conta de serviço do Identity and Access Management (IAM) associado ao gatilho e aos quais você já concedeu papéis específicos exigidos pelo Eventarc.

11. Na lista Destino do evento, selecione Workflows.
12. Selecione um fluxo de trabalho.
    

    Esse é o nome do fluxo de trabalho para o qual transmitir eventos. Os eventos de uma execução de fluxo de trabalho são transformados e transmitidos para o fluxo de trabalho como argumentos de ambiente de execução.

    Para mais informações, consulte Criar um gatilho para os Workflows.

13. Clique em Criar.

Depois que um gatilho é criado, os filtros da origem de eventos não podem ser modificados. Crie um novo gatilho e exclua o antigo. Para mais informações, consulte Gerenciar acionadores.

gcloud

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-workflow=DESTINATION_WORKFLOW  \
    --destination-workflow-location=DESTINATION_WORKFLOW_LOCATION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="bucket=BUCKET" \
    --service-account="MY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"

Substitua:

• TRIGGER: o ID do gatilho ou um identificador totalmente qualificado.
• LOCATION: o local do gatilho do Eventarc e disponível em locais de região única, birregional e multirregião; não é possível criar um gatilho global do Eventarc. O bucket do Cloud Storage precisa residir no mesmo projeto e região do Google Cloud que o gatilho do Eventarc. Saiba mais em Locais do Eventarc.
• DESTINATION_WORKFLOW: o ID do fluxo de trabalho implantado que recebe os eventos do gatilho. O fluxo de trabalho pode estar em qualquer um dos locais compatíveis com o Workflows e não precisa estar no mesmo local do gatilho. No entanto, o fluxo de trabalho precisa estar no mesmo projeto que o gatilho.
• DESTINATION_WORKFLOW_LOCATION (opcional): o local em que o fluxo de trabalho de destino está implantado. Se não for especificado, presumirá que o fluxo de trabalho está no mesmo local que o gatilho.
• EVENT_FILTER_TYPE: o identificador do evento do Cloud Storage e pode ser um dos seguintes:
  • google.cloud.storage.object.v1.finalized: o evento é enviado quando um novo objeto é criado (ou um objeto é substituído e uma nova geração desse objeto é criada) no bucket.
  • google.cloud.storage.object.v1.archived: esse evento é enviado quando uma versão ativa de um objeto é arquivada ou excluída. Este evento só é enviado para buckets com controle de versão.
  • google.cloud.storage.object.v1.deleted: esse 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.
  • google.cloud.storage.object.v1.metadataUpdated: esse evento é enviado quando os metadados de um objeto existente mudam.
• BUCKET: é o identificador exclusivo global do bucket do Cloud Storage.
• SERVICE_ACCOUNT_NAME: o nome da conta de serviço do IAM que você criou para a qual você concedeu papéis específicos exigidos pelos fluxos de trabalho.
• PROJECT_ID: o ID do projeto do Google Cloud

Observações:

• Para eventos diretos de Cloud Storage, a codificação do payload do evento é application/json.
• Essas sinalizações são necessárias:
  • --event-filters="type=EVENT_FILTER_TYPE"
  • --event-filters="bucket=BUCKET"
• Após a criação de um gatilho, EVENT_FILTER_TYPE não pode ser alterado. Para um tipo diferente de evento, crie um novo gatilho.
• --service-account: o e-mail da conta de serviço do IAM que o gatilho do Eventarc usará para invocar as execuções de fluxo de trabalho. Recomendamos o uso de uma conta de serviço com os privilégios mínimos necessários para acessar os recursos necessários. Para saber mais sobre contas de serviço, consulte Criar e gerenciar contas de serviço.
• Os eventos são entregues usando notificações do Pub/Sub do Cloud Storage. A configuração de muitas notificações registradas no mesmo bucket pode esgotar o limite de notificações do bucket, conforme indicado pelo erro Cloud Storage bucket ...: Pub/Sub notification limit reached. É possível ter até 10 configurações de notificação definidas no bucket para acionar um determinado evento. Veja mais cotas e limitações na página Cotas e limites do Cloud Storage.
• 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 aceitos.
• O bucket do Cloud Storage precisa residir no mesmo projeto do Google Cloud e na região ou multirregião que o gatilho do Eventarc.
• Por padrão, as assinaturas do Pub/Sub criadas para o Eventarc persistem independentemente da atividade e não expiram. Para mudar a duração da inatividade, consulte Propriedades da assinatura.

Exemplo:

gcloud eventarc triggers create helloworld-trigger \
    --location=us-central1 \
    --destination-workflow=my-workflow \
    --destination-workflow-location=europe-west4 \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=my-project-bucket" \
    --service-account="${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

Esse comando cria um gatilho chamado helloworld-trigger para o bucket do Cloud Storage my-project-bucket e o evento identificado como google.cloud.storage.object.v1.finalized.

Terraform

É possível criar um gatilho para um fluxo de trabalho usando o Terraform. Para mais detalhes, acesse Como acionar um fluxo de trabalho usando o Eventarc e o Terraform.

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

Listar um gatilho

É possível confirmar a criação de um gatilho listando os gatilhos do Eventarc usando a CLI do Google Cloud ou o console do Google Cloud.

Console

1. No Console do Google Cloud, acesse a página Gatilhos do Eventarc.

   Acessar gatilhos

   Confira nesta página os gatilhos em todos os locais e os detalhes como nomes, regiões, provedores de eventos, destinos e muito mais.

2. Para filtrar os gatilhos, siga estas etapas:

   1. Clique em Filtrar ou no campo Filtrar gatilhos.
   2. Na lista Propriedades, selecione uma opção para filtrar os gatilhos.

   É possível selecionar uma única propriedade ou usar o operador lógico OR para adicionar mais propriedades.

3. Para classificar gatilhos, ao lado de qualquer cabeçalho de coluna com suporte, clique em Ordenar.

gcloud

Execute o comando a seguir para listar os gatilhos:

gcloud eventarc triggers list --location=-

Esse comando lista os gatilhos em todos os locais e inclui detalhes como nomes, tipos, destinos e status.

A seguir

• Como acionar um fluxo de trabalho usando o Eventarc e o Terraform

• Acionar o Workflows com eventos do Cloud Storage

• Acionar fluxos de trabalho com mensagens do Pub/Sub

• Saiba mais sobre o Eventarc