Crie acionadores com o Eventarc

Esta página mostra como criar um acionador do Eventarc para que um serviço do Cloud Run possa receber eventos de outro Google Cloud serviço.

O Eventarc é um Google Cloud serviço que lhe permite criar arquiteturas orientadas por eventos sem ter de implementar, personalizar nem manter a infraestrutura subjacente.

Pode criar um acionador do Eventarc especificando filtros para o acionador e configurando o encaminhamento do evento, incluindo a origem do evento e o serviço do Cloud Run de destino. Quando o evento especificado ou o conjunto de eventos correspondem aos filtros, o serviço do Cloud Run é invocado automaticamente em resposta aos eventos. Um serviço que usa acionadores do Eventarc é denominado serviço orientado por eventos. Os eventos enviados para o seu serviço do Cloud Run são recebidos sob a forma de pedidos HTTP.

Os seguintes tipos de eventos acionam pedidos ao seu serviço:

Também pode criar um acionador do Eventarc através da Google Cloud CLI ou da página da consola do Eventarc. Para ver instruções sobre como criar um acionador para um fornecedor, um tipo de evento e um destino específicos, filtre a lista para saber mais sobre os fornecedores e os destinos de eventos do Eventarc.

Localização do acionador

Quando cria um acionador do Eventarc, especifica uma localização para o mesmo. Esta deve corresponder à localização do Google Cloud recurso que quer monitorizar para eventos. Na maioria dos cenários, também deve implementar o serviço do Cloud Run acionado por eventos na mesma região. Para mais informações, consulte o artigo Compreenda as localizações do Eventarc.

Identidade do acionador

A conta de serviço do seu acionador do Eventarc tem de ter autorização para invocar o seu serviço. Pode ter de verificar se a conta de serviço predefinida do Compute Engine tem as autorizações corretas para invocar o seu serviço. Para mais informações, consulte o artigo Funções necessárias.

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 e Eventarc:

    Ative as APIs

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 configurar acionadores do Eventarc, 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 opcional 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 uma opção.

  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 um fornecedor de eventos 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 um tipo de evento 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. 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.

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

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

    8. 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=REGION \
    --destination-run-service=SERVICE  \
    --destination-run-region=REGION \
    --event-filters="EVENT_FILTER" \
    --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 uma opção.

  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 um fornecedor de eventos 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 um tipo de evento 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. 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.

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

    7. 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=REGION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=REGION \
    --event-filters="EVENT_FILTER" \
    --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.

Defina o prazo de confirmação do Pub/Sub

As funções do Cloud Run orientadas por eventos são implementadas através do Eventarc em combinação com uma subscrição do Pub/Sub. Por predefinição, o prazo de confirmação (ack) desta subscrição do Pub/Sub é de 10 segundos. Esta definição é insuficiente para muitas funções e pode ter o efeito de causar execuções duplicadas indesejadas.

Recomendamos que defina o prazo ack para o seu serviço ou função para o valor máximo de 600 segundos da seguinte forma:

Consola

Depois de implementar a função, siga estes passos para modificar o prazo da função:ack

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

    Aceda ao Cloud Run

  2. Localize a função que quer atualizar na lista Serviços e clique para abrir os detalhes dessa função.

  3. Abra o separador Acionadores.

  4. Clique no nome do acionador para abrir os detalhes do acionador.

  5. Clique no link Tópico para abrir o painel de edição de tópicos.

  6. Clique no nome do ID da subscrição para aceder ao painel de subscrição e clique em Editar na parte superior da página.

  7. Defina o valor para o Prazo de confirmação como 600 e clique em Atualizar para guardar a alteração.

gcloud

Atualize o prazo ack por acionador para o valor máximo de 600 segundos. Tenha em atenção que os seguintes comandos fazem referência a variáveis (TRIGGER_NAME e REGION) cujos valores definiu nos passos anteriores.

## Per Cloud Run function:

# Update Ack Deadline to max (600s)
SUBSCRIPTION_ID=$(gcloud eventarc triggers describe "$TRIGGER_NAME" --location $REGION --format json | jq -r '.transport.pubsub.subscription')
gcloud pubsub subscriptions update "$SUBSCRIPTION_ID" --ack-deadline=600

Faça uma atualização em massa em todos os acionadores de serviços e funções para definir os respetivos prazos de ackpara 600 segundos:

### Match all Cloud Run service triggers and update all deadlines to 600s (max timeout)
### This will change ALL Cloud Run Service and Cloud Run function
TRIGGER_NAMES=($(gcloud eventarc triggers list | awk '/Cloud Run service/ {print $1}'))

if [ ${#TRIGGER_NAMES[@]} -eq 0 ]; then
  echo "No matching triggers found"
fi

for trigger in "${TRIGGER_NAMES[@]}"; do
echo "Updating ack deadline for trigger: $trigger"
SUBSCRIPTION_ID=$(gcloud eventarc triggers describe "$trigger" --location $REGION --format json | jq -r '.transport.pubsub.subscription')

if [ -z "$SUBSCRIPTION_ID" ]; then
    echo "Error: Could not retrieve subscription ID for trigger: $trigger"
    continue # Skip to the next trigger
fi
gcloud pubsub subscriptions update "$SUBSCRIPTION_ID" --ack-deadline=600
echo "Ack deadline updated for subscription: $SUBSCRIPTION_ID"
done

Veja o ID e a origem do CloudEvent

Para ver o ID e a origem do CloudEvent que acionaram o seu serviço, veja os seguintes recursos nos registos do serviço do Cloud Run:

  • LogEntry.labels.run.googleapis.com/cloud_event_id
  • LogEntry.labels.run.googleapis.com/cloud_event_source

O que se segue?