Encaminhe eventos do Cloud Firestore para fluxos de trabalho

Um acionador do Eventarc declara o seu interesse num determinado evento ou conjunto de eventos. Pode configurar o encaminhamento de eventos especificando filtros para o acionador, incluindo a origem do evento e o fluxo de trabalho de destino.

Os eventos são entregues no formato CloudEvents através de um pedido HTTP. O serviço Workflows converte o evento num objeto JSON (seguindo a especificação CloudEvents) e passa o evento para a execução do fluxo de trabalho como um argumento de tempo de execução do fluxo de trabalho. Certifique-se de que o tamanho do evento não excede 512 KB. Os eventos superiores ao tamanho máximo dos argumentos dos fluxos de trabalho não acionam execuções de fluxos de trabalho.

O Cloud Firestore suporta o contexto de autorização como um atributo de extensão ao formato CloudEvents. Quando cria um acionador, pode aplicar este atributo de tipo de evento para filtrar eventos com informações de autenticação.

Estas instruções mostram como configurar o encaminhamento de eventos para que uma execução do fluxo de trabalho seja acionada em resposta a um eventoCloud Firestore direto. Para mais detalhes, consulte a lista de eventos diretos suportados.

Prepare-se para criar um acionador

Antes de criar um acionador do Eventarc para um fluxo de trabalho de destino, conclua as seguintes tarefas.

Consola

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

    Aceder ao 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 com os eventos diretos. Por exemplo, para eventos, ative a APICloud Firestore . Cloud Firestore

  4. Se ainda não tiver uma, crie uma conta de serviço gerida pelo utilizador e, em seguida, conceda-lhe as funções e as autorizações necessárias para que o Eventarc possa gerir eventos para um fluxo de trabalho de destino.

    1. Na Google Cloud consola, aceda à página Contas de serviço.

      Aceda a Contas de serviço

    2. Selecione o seu projeto.

    3. No campo Nome da conta de serviço, introduza um nome. A Google Cloud consola preenche o campo ID da conta de serviço com base neste nome.

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

    4. Clique em Criar e continuar.

    5. Para conceder o acesso adequado, na lista Selecionar uma função, selecione as funções de gestão de identidade e de acesso (IAM) necessárias para conceder à sua conta de serviço. Para mais informações, consulte o artigo Funções e autorizações para alvos de fluxos de trabalho.

      Para funções adicionais, clique em Adicionar outra função e adicione cada função adicional.

    6. Clique em Continuar.

    7. Para concluir a criação da conta, 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 com os eventos diretos. Por exemplo, para Cloud Firestore eventos, ative firestore.googleapis.com.

  4. Se ainda não tiver uma, crie uma conta de serviço gerida pelo utilizador e, em seguida, conceda-lhe as funções e as autorizações necessárias para que o Eventarc possa gerir eventos para 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. Tem de ter entre 6 e 30 carateres e pode conter carateres alfanuméricos em minúsculas e traços. Depois de criar uma conta de serviço, não pode alterar o respetivo nome.

    2. Conceda as funções ou as autorizações da gestão de identidade e de acesso (IAM) necessárias. Para mais informações, consulte o artigo Funções e autorizações para alvos de fluxos de trabalho.

Crie um acionador

Pode criar um acionador do Eventarc com um fluxo de trabalho implementado como o recetor de eventos através da CLI Google Cloud (gcloud ou Terraform) ou através da consola Google Cloud .

Consola

  1. Na Google Cloud consola, aceda à página Triggers do Eventarc.

    Aceda a Acionadores

  2. Clique em Criar acionador.
  3. Escreva um Nome do acionador.

    Este é o ID do acionador e tem de começar com uma letra. Pode conter até 63 letras minúsculas, números ou hífenes.

  4. Para o Tipo de acionador, selecione Fontes Google.
  5. Na lista Fornecedor de eventos, selecione Cloud Firestore.

    Tenha em atenção que o nome do fornecedor de eventos usado na Google Cloud documentação associada pode não ter um prefixo de Cloud ou Google Cloud. Por exemplo, na consola, o Memorystore for Redis é denominado Google Cloud Memorystore for Redis.

  6. Na lista Tipo de evento, nos eventos Direto, selecione um tipo de evento.
  7. Na lista Tipo de conteúdo dos dados de eventos, selecione a codificação do payload do evento.

    Para eventos diretos de Cloud Firestore, tem de 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 o artigo Eventos comuns. Tenha em atenção que pode usar uma função da biblioteca padrão do Workflows para codificar bytes em texto Base64. Para mais informações, consulte a secção Devolver bytes.

  8. Na lista Região, selecione a mesma região que o Google Cloud serviço que está a gerar eventos.

    Para mais informações, consulte o artigo Localizações do Eventarc.

  9. Se aplicável ao fornecedor de eventos, clique em Adicionar filtro e especifique o seguinte:
    1. No campo Atributo 1, consoante o evento direto que escolheu, selecione um ID do recurso que pode funcionar como um filtro de eventos.
    2. Selecione um operador:
      • Igual
      • Padrão do caminho: aplicável a recursos document (modo nativo) e entity (modo Datastore). Use carateres universais para responder a alterações que correspondam a um padrão. Um caráter universal * corresponde a um único segmento e um caráter universal de vários segmentos ** corresponde a zero ou mais segmentos no padrão. Não especifique uma barra à esquerda. Por 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 a documentos em subcoleções, como /users/marie/messages/33e2IxYBD9enzS50SJ68

        Para mais informações, consulte o artigo Compreenda os padrões de caminhos.

    3. No campo Valor do atributo 1, consoante o operador que escolheu, escreva o valor exato ou aplique um padrão de caminho.
    4. Se forem aplicáveis mais filtros de atributos, clique em Adicionar filtro e especifique os valores adequados.
  10. Selecione a conta de serviço que vai invocar o seu serviço ou fluxo de trabalho.

    Em alternativa, pode criar uma nova conta de serviço.

    Isto especifica o email da conta de serviço de gestão de identidade e de acesso (IAM) associado ao acionador e ao qual concedeu anteriormente funções específicas necessárias pelo Eventarc.

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

    Este é o nome do fluxo de trabalho para o qual os eventos são transmitidos. Os eventos de uma execução do fluxo de trabalho são transformados e transmitidos ao fluxo de trabalho como argumentos de tempo de execução.

    Para mais informações, consulte o artigo Crie um acionador para fluxos de trabalho.

  13. Opcionalmente, para adicionar uma etiqueta, pode clicar em Adicionar etiqueta. As etiquetas são pares de chave-valor que ajudam a organizar os seus Google Cloud recursos. Para mais informações, consulte o artigo O que são etiquetas?
  14. Clique em Criar.

    15. Depois de criar um acionador, não é possível modificar os filtros da origem do evento. Em alternativa, crie um novo acionador e elimine o antigo. Para mais informações, consulte o artigo Faça a gestão dos acionadores.

gcloud

Pode criar um acionador executando um gcloud eventarc triggers createcomando juntamente com flags obrigatórias e opcionais.

As flags diferem consoante esteja a executar o Firestore no modo nativo ou no modo Datastore. Para mais informações, consulte o artigo 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 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 o seguinte:

  • TRIGGER: o ID do acionador ou um identificador totalmente qualificado.

  • LOCATION: a localização do acionador do Eventarc. Em alternativa, pode definir a propriedade eventarc/location; por exemplo, gcloud config set eventarc/location us-central1.

    Os acionadores do Cloud Firestore para o Eventarc só estão disponíveis em determinadas localizações, e o acionador tem de estar na mesma localização que a base de dados do Cloud Firestore. Para mais informações, consulte Localizações do Eventarc e Localizações do Cloud Firestore.

  • DESTINATION_WORKFLOW: o ID do fluxo de trabalho implementado que recebe os eventos do acionador. O fluxo de trabalho pode estar em qualquer uma das localizações suportadas e não tem de estar na mesma localização que o acionador. No entanto, o fluxo de trabalho tem de estar no mesmo projeto que o acionador.
  • DESTINATION_WORKFLOW_LOCATION (opcional): a localização em que o fluxo de trabalho de destino é implementado. Se não for especificado, assume-se que o fluxo de trabalho está na mesma localização que o acionador.
  • EVENT_FILTER_TYPE: o identificador do evento. É gerado um evento quando uma chamada da 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 ver uma lista dos tipos de eventos suportados, consulte o artigo Tipos de eventos Google suportados pelo Eventarc.

    • O Cloud Firestore suporta os seguintes tipos de eventos apenas no modo nativo.

    • google.cloud.firestore.document.v1.created: o evento é enviado quando um documento é escrito pela primeira vez
    • google.cloud.firestore.document.v1.created.withAuthContext: event with authentication information attributes is sent when a document is written to for the first time
    • google.cloud.firestore.document.v1.updated: o evento é enviado quando já existe um documento e qualquer valor é alterado
    • google.cloud.firestore.document.v1.updated.withAuthContext: event with authentication information attributes is sent when a document already exists and has any value changed
    • google.cloud.firestore.document.v1.deleted: o evento é enviado quando um documento é eliminado
    • google.cloud.firestore.document.v1.deleted.withAuthContext: event with authentication information attributes is sent when a document is deleted
    • google.cloud.firestore.document.v1.written: o evento é enviado quando um documento é criado, atualizado ou eliminado
    • google.cloud.firestore.document.v1.written.withAuthContext: event with authentication information attributes is sent when a document is created, updated, or deleted.

    O Cloud Firestore suporta os seguintes tipos de eventos apenas no modo Datastore. Os objetos de dados no Firestore no modo Datastore são conhecidos como entidades.

    • google.cloud.datastore.entity.v1.created: o evento é enviado quando uma entidade é escrita pela primeira vez
    • google.cloud.datastore.entity.v1.created.withAuthContext: evento com atributos de informações de autenticação é enviado quando uma entidade é escrita pela primeira vez
    • google.cloud.datastore.entity.v1.updated: o evento é enviado quando uma entidade já existe e tem algum valor alterado
    • google.cloud.datastore.entity.v1.updated.withAuthContext: event with authentication information attributes is sent when an entity already exists and has any value changed
    • google.cloud.datastore.entity.v1.deleted: o evento é enviado quando uma entidade é eliminada
    • google.cloud.datastore.entity.v1.deleted.withAuthContext: evento com atributos de informações de autenticação é enviado quando uma entidade é eliminada
    • google.cloud.datastore.entity.v1.written: o evento é enviado quando uma entidade é criada, atualizada ou eliminada
    • google.cloud.datastore.entity.v1.written.withAuthContext: evento com atributos de informações de autenticação é enviado quando uma entidade é criada, atualizada ou eliminada
  • DATABASE: a base de dados do Firestore. Para o nome da base de dados predefinido, use (default).
  • NAMESPACE (opcional): o espaço de nomes da base de dados do Firestore. Para o espaço de nomes predefinido no modo Datastore, use (default). Se não for especificado, é feita uma correspondência de caráter universal (*) com todas as ocorrências.
  • DOCUMENT (opcional): aplicável a instâncias de base de dados em execução apenas no modo nativo. O caminho da base de dados a partir do qual quer receber eventos quando os dados são criados, atualizados ou eliminados nesse caminho. Não especifique uma barra inicial. O operador pode ser um dos seguintes:
    • Igual; por exemplo, --event-filters="document=DOCUMENT"
    • Padrão de caminho; por exemplo, --event-filters-path-pattern="document=DOCUMENT".

      Use carateres universais para responder a alterações em documentos que correspondam a um padrão. Um caráter universal * corresponde a um único segmento e um caráter universal de vários segmentos ** corresponde a zero ou mais segmentos no padrão, por 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 a documentos em subcoleções, como /users/marie/messages/33e2IxYBD9enzS50SJ68
      Para mais informações, consulte o artigo Compreenda os padrões de caminhos.
  • ENTITY (opcional): aplicável a instâncias de base de dados em execução apenas no modo Datastore. O caminho da base de dados a partir do qual quer receber eventos quando os dados são criados, atualizados ou eliminados nesse caminho. Não especifique uma barra inicial. O operador pode ser um dos seguintes:
    • Igual; por exemplo, --event-filters="document=ENTITY"
    • Padrão de caminho; por exemplo, --event-filters-path-pattern="ENTITY=ENTITY"

      Para mais informações, consulte o artigo Compreenda os padrões de caminhos.

      Tenha em atenção que pode ter de interpretar carateres de forma literal nos IDs de tipo e nos IDs de entidades. A remoção de carateres especiais permite que o filtro de eventos interprete corretamente o ID. Para mais informações, consulte o artigo Escape de carateres.

  • EVENT_DATA_CONTENT_TYPE: a codificação da carga útil do evento. Para eventos diretos do Firestore, tem de 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 o artigo Eventos comuns. Tenha em atenção que pode usar uma função da biblioteca padrão do Workflows para codificar bytes em texto Base64. Para mais informações, consulte a secção Devolver bytes.
  • SERVICE_ACCOUNT_NAME: o nome da conta de serviço do IAM que criou à qual concedeu funções específicas exigidas pelos Workflows.
  • PROJECT_ID: o ID do seu Google Cloud projeto

Notas:

  • Para eventos diretos de Cloud Firestore, a codificação do payload do evento é application/protobuf.
  • A flag --event-filters="type=EVENT_FILTER_TYPE" é obrigatória. Se não estiver definido nenhum outro filtro de eventos, os eventos de todos os recursos são correspondentes.
  • Não é possível alterar o valor EVENT_FILTER_TYPE após a criação. Para alterar EVENT_FILTER_TYPE, crie um novo acionador e elimine o antigo.
  • Cada acionador pode ter vários filtros de eventos, separados por vírgulas numa --event-filters=[ATTRIBUTE=VALUE,...] sinalização, ou pode repetir a sinalização para adicionar mais filtros. Apenas os eventos que correspondem a todos os filtros são enviados para o destino. Os carateres universais e as expressões regulares não são suportados. No entanto, quando usa a flag --event-filters-path-pattern, pode definir um padrão de caminho do recurso.
  • A flag --service-account é usada para especificar o email da conta de serviço de gestão de identidade e de acesso (IAM) associado ao acionador.

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"

Este comando cria um acionador denominado helloworld-trigger para o evento identificado como google.cloud.firestore.document.v1.updated na instância da base de dados my-database em execução no modo nativo e filtra eventos para caminhos document que correspondem a users/my-document-.

Terraform

Pode criar um acionador para um fluxo de trabalho com o Terraform. Para ver detalhes, consulte o artigo Acione um fluxo de trabalho com o Eventarc e o Terraform.

Crie uma lista de um acionador

Pode confirmar a criação de um acionador listando os acionadores do Eventarc através da CLI do Google Cloud ou da Google Cloud consola.

Consola

  1. Na Google Cloud consola, aceda à página Triggers do Eventarc.

    Aceda a Acionadores

    Esta página lista os seus acionadores em todas as localizações e inclui detalhes como nomes, regiões, fornecedores de eventos, destinos e muito mais.

  2. Para filtrar os acionadores:

    1. Clique em Filtro ou no campo Acionadores de filtro.
    2. Na lista Propriedades, selecione uma opção para filtrar os acionadores.

    Pode selecionar uma única propriedade ou usar o operador lógico OR para adicionar mais propriedades.

  3. Para ordenar os acionadores, junto ao título de qualquer coluna suportada, clique em Ordenar.

gcloud

Execute o seguinte comando para listar os seus acionadores:

gcloud eventarc triggers list --location=-

Este comando lista os seus acionadores em todas as localizações e inclui detalhes como nomes, tipos, destinos e estados.

O que se segue?