Encaminhar eventos do Cloud Firestore 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.

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.

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 Firestore , ative a APICloud Firestore .

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.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   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.

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 Firestore , ative firestore.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.

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 uma correspondência exata e não permite caracteres curinga ou expressões regulares. No entanto, é possível usar a sinalização --event-filters-path-pattern no comando da gcloud CLI a seguir ou definir um padrão de caminho usando o console. Para mais informações, consulte Entender os padrões de caminho.

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

6. Na lista Tipo de evento, nos eventos Diretos, selecione um tipo de evento.
7. 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.

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

9. Se for aplicável ao evento, clique em Adicionar filtro e faça as seguintes especificações:
   1. No campo Atributo 1, dependendo do evento direto escolhido, selecione um ID de recurso que possa atuar como filtro de evento.
   2. Selecione um operador:
      • Igual
      • Padrão de caminho: aplicável aos recursos document (modo nativo) e entity (modo Datastore). Use caracteres curinga para responder a mudanças que correspondam a um padrão. Um caractere curinga * corresponde a um único segmento, e um caractere curinga de vários segmentos ** corresponde a zero ou mais segmentos no padrão. Exemplo:

        /users/* ou /users/{userId}	Corresponde a todos os documentos na coleção /users. Não corresponde a documentos em subcoleções como /users/marie/messages/33e2IxYBD9enzS50SJ68
        /users/**	Corresponde a todos os documentos na coleção /users e aos documentos em subcoleções como /users/marie/messages/33e2IxYBD9enzS50SJ68

        Para mais informações, consulte Entender os padrões de caminho.

   3. No campo Valor do atributo 1, dependendo do operador escolhido, digite o valor exato ou aplique um padrão de caminho.
   4. Se mais filtros de atributos forem aplicáveis, clique em Adicionar filtro e especifique os valores apropriados.
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

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 propriedade eventarc/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.

O Cloud Firestore é compatível com os seguintes tipos de evento no Modo nativo apenas.

• google.cloud.firestore.document.v1.created: o evento é enviado quando um documento é gravado pela primeira vez
• google.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 é alterado
• google.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 alterado
• google.cloud.firestore.document.v1.deleted: o evento é enviado quando um documento é excluído
• google.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ído
• google.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.

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.

• google.cloud.datastore.entity.v1.created: o evento é enviado quando uma entidade é gravada pela primeira vez
• google.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 é alterado
• google.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ída
• google.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ída
• google.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".

    Use caracteres curinga para responder a alterações em documentos que correspondam a um padrão. Um caractere curinga * corresponde a um único segmento, e um caractere curinga de vários segmentos ** corresponde a zero ou mais segmentos no padrão. Exemplo:

    /users/* ou /users/{userId}	Corresponde a todos os documentos na coleção /users. Não corresponde a documentos em subcoleções como /users/marie/messages/33e2IxYBD9enzS50SJ68
    /users/**	Corresponde a todos os documentos na coleção /users e aos documentos em subcoleções como /users/marie/messages/33e2IxYBD9enzS50SJ68

    Para mais informações, consulte Entender os padrões de caminho.
• 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.

• EVENT_DATA_CONTENT_TYPE: a codificação do payload do evento. Para eventos diretos do 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 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

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

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

• Saiba mais sobre como usar o Eventarc e o Cloud Firestore.
• Acione um fluxo de trabalho usando o Eventarc e o Terraform.
• Saiba mais sobre o Eventarc.
• Saiba como gerenciar gatilhos.