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.
O Cloud Firestore é compatível com o Auth Context como um atributo de extensão para o formato do CloudEvents. Ao criar um gatilho, é possível aplicar esse atributo de tipo de evento para filtrar eventos com informações de autenticação.
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 Firestore direto. Para saber mais, consulte a lista de eventos diretos compatíveis.
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
No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.
Ative as APIs Eventarc, Eventarc Publishing, Workflows e Workflow Executions.
Se aplicável, ative a API relacionada aos eventos diretos. Por exemplo, para eventos Cloud Firestore, ative a API Cloud Firestore.
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.
No console do Google Cloud, acesse a página Contas de serviço.
Selecione o projeto.
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
.Clique em Criar e continuar.
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.Clique em Continuar.
Para concluir a criação da conta de serviço, clique em Concluído.
gcloud
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
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
Se aplicável, ative a API relacionada aos eventos diretos. Por exemplo, para eventos Cloud Firestore, ative
firestore.googleapis.com
.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.
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.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.
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.
Console
- No Console do Google Cloud, acesse a página Gatilhos do Eventarc.
- Clique em Criar gatilho.
- 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.
- Em Tipo de gatilho, selecione Fontes do Google.
- Na lista Provedor de eventos, selecione
Cloud Firestore.
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.
- Na lista Tipo de evento, nos eventos Diretos, selecione um tipo de evento.
- Na lista Tipo de conteúdo de dados do evento, selecione a codificação
do payload do evento.
Para eventos diretos de Cloud Firestore, ele precisa ser application/protobuf e os dados do evento são uma matriz de bytes. Para mais informações sobre as mensagens protobuf para eventos do Cloud Firestore, consulte Eventos comuns. É possível usar uma função da biblioteca padrão do Workflows para codificar bytes em texto em Base64. Para mais informações, consulte Como retornar bytes.
- Na lista Região, selecione a mesma região do
serviço do Google Cloud que está gerando eventos.
Saiba mais em Locais do Eventarc.
- Se for aplicável ao evento, clique em Adicionar filtro
e faça as seguintes especificações:
- No campo Atributo 1, dependendo do evento direto escolhido, selecione um ID de recurso que possa atuar como filtro de evento.
- Selecione um operador:
- Igual
- Padrão de caminho
Para mais informações, consulte Entender os padrões de caminho.
- No campo Valor do atributo 1, dependendo do operador escolhido, digite o valor exato ou aplique um padrão de caminho.
- Se um campo Atributo 2 for aplicável, especifique os valores apropriados.
- 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.
- Na lista Destino do evento, selecione Workflows.
- 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.
- 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
Para criar um gatilho, execute um comando
gcloud eventarc triggers create
com as sinalizações obrigatórias e opcionais.
As sinalizações serão diferentes dependendo se você estiver executando o Firestore no modo nativo ou no modo Datastore. Para mais informações, consulte Escolher entre o modo nativo e o modo Datastore.
Modo nativo
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="database=DATABASE" \ --event-filters="namespace=NAMESPACE" \ --event-filters-path-pattern="document=DOCUMENT" \ --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \ --service-account="MY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"
Modo do Datastore
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="database=DATABASE" \ --event-filters="namespace=NAMESPACE" \ --event-filters-path-pattern="entity=ENTITY" \ --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \ --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. Como alternativa, é possível definir a propriedadeeventarc/location
; por exemplo:gcloud config set eventarc/location us-central1
.Os gatilhos do Cloud Firestore para Eventarc estão disponíveis apenas em determinados locais, e o gatilho precisa estar no mesmo local que o banco de dados do Cloud Firestore. Para mais informações, consulte Locais do Eventarc e Locais do Cloud Firestore.
-
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. 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 compatíveis com o Eventarc.google.cloud.firestore.document.v1.created
: o evento é enviado quando um documento é gravado pela primeira vezgoogle.cloud.firestore.document.v1.created.withAuthContext
: o evento com atributos de informações de autenticação é enviado quando um documento é gravado pela primeira vez.google.cloud.firestore.document.v1.updated
: o evento é enviado quando um documento já existe e algum valor é alteradogoogle.cloud.firestore.document.v1.updated.withAuthContext
: o evento com atributos de informações de autenticação é enviado quando um documento já existe e tem algum valor alteradogoogle.cloud.firestore.document.v1.deleted
: o evento é enviado quando um documento é excluídogoogle.cloud.firestore.document.v1.deleted.withAuthContext
: um evento com atributos de informações de autenticação é enviado quando um documento é excluído.google.cloud.firestore.document.v1.written
: o evento é enviado quando um documento é criado, atualizado ou excluídogoogle.cloud.firestore.document.v1.written.withAuthContext
: um evento com atributos de informações de autenticação é enviado quando um documento é criado, atualizado ou excluído.google.cloud.datastore.entity.v1.created
: o evento é enviado quando uma entidade é gravada pela primeira vezgoogle.cloud.datastore.entity.v1.created.withAuthContext
: o evento com atributos de informações de autenticação é enviado quando uma entidade é gravada pela primeira vez.google.cloud.datastore.entity.v1.updated
: o evento é enviado quando uma entidade já existe e algum valor é alteradogoogle.cloud.datastore.entity.v1.updated.withAuthContext
: o evento com atributos de informações de autenticação é enviado quando uma entidade já existe e tem algum valor alterado.google.cloud.datastore.entity.v1.deleted
: o evento é enviado quando uma entidade é excluídagoogle.cloud.datastore.entity.v1.deleted.withAuthContext
: um evento com atributos de informações de autenticação é enviado quando uma entidade é excluída.google.cloud.datastore.entity.v1.written
: o evento é enviado quando uma entidade é criada, atualizada ou excluídagoogle.cloud.datastore.entity.v1.written.withAuthContext
: o evento com atributos de informações de autenticação é enviado quando uma entidade é criada, atualizada ou excluída.DATABASE
: o banco de dados do Firestore. Para o nome padrão do banco de dados, use(default)
.NAMESPACE
(opcional): o namespace do banco de dados do Firestore. Para o namespace padrão no modo Datastore, use(default)
. Se não for especificado, será feita uma correspondência de caractere curinga (*
) para qualquer ocorrência.DOCUMENT
(opcional): aplicável a instâncias de banco de dados em execução somente no modo nativo. O caminho do banco de dados de onde você quer receber eventos de quando os dados são criados, atualizados ou excluídos nesse caminho. O operador pode ser um dos seguintes:- Igual; por exemplo,
--event-filters="document=DOCUMENT"
- Padrão do caminho; por exemplo,
--event-filters-path-pattern="document=DOCUMENT"
. Para mais informações, consulte Entender os padrões de caminho.
- Igual; por exemplo,
ENTITY
(opcional): aplicável a instâncias de banco de dados em execução somente no modo Datastore. O caminho do banco de dados de onde você quer receber eventos de quando os dados são criados, atualizados ou excluídos nesse caminho. O operador pode ser um dos seguintes:- Igual; por exemplo,
--event-filters="document=ENTITY"
Padrão do caminho; por exemplo,
--event-filters-path-pattern="ENTITY=ENTITY"
. Para mais informações, consulte Entender os padrões de caminho.Talvez seja necessário usar caracteres de escape em IDs de tipo e de entidade. O escape de um caractere permite que o filtro de evento interprete o ID corretamente. Para saber mais, consulte Escape de caracteres.
- Igual; por exemplo,
EVENT_DATA_CONTENT_TYPE
: a codificação do payload do evento. Para eventos diretos do Firestore, ele precisa serapplication/protobuf
e os dados do evento são uma matriz de bytes. Para mais informações sobre as mensagens protobuf para eventos do Cloud Firestore, consulte Eventos comuns. É possível usar uma função da biblioteca padrão do Workflows para codificar bytes em texto Base64. Para mais informações, consulte Como retornar bytes.-
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
O Cloud Firestore é compatível com os seguintes tipos de evento no Modo nativo apenas.
O Cloud Firestore é compatível com os seguintes tipos de evento no modo Datastore apenas. Os objetos de dados do Firestore no modo Datastore são conhecidos como entidades.
Observações:
- Para eventos diretos de Cloud Firestore, a codificação
do payload do evento é
application/protobuf
. - 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 mudarEVENT_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. - A sinalização
--service-account
é usada para especificar o e-mail da conta de serviço do Identity and Access Management (IAM) associado ao gatilho.
Exemplo:
gcloud eventarc triggers create helloworld-trigger \ --location=us-east1 \ --destination-workflow=my-workflow \ --destination-workflow-location=us-east1 \ --event-filters="type=google.cloud.firestore.document.v1.updated" \ --event-filters="database=my-database" \ --event-filters-path-pattern="document=users/my-document-*" \ --event-data-content-type="application/protobuf" \ --service-account="${TRIGGER_SA}@${PROJECT_ID}.iam.gserviceaccount.com"
Esse comando cria um gatilho chamado helloworld-trigger
para
o evento identificado como google.cloud.firestore.document.v1.updated
na
instância de banco de dados my-database
em execução no modo nativo e
filtra eventos para caminhos document
que correspondem a users/my-document-
.
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.
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
No Console do Google Cloud, acesse a página Gatilhos do Eventarc.
Confira nesta página os gatilhos em todos os locais e os detalhes como nomes, regiões, provedores de eventos, destinos e muito mais.
Para filtrar os gatilhos, siga estas etapas:
- Clique em Filtrar ou no campo Filtrar gatilhos.
- 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.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.