Criar gatilhos com o Eventarc

Nesta página, mostramos como criar um gatilho do Eventarc para que um serviço do Cloud Run possa receber eventos de outro serviço Google Cloud .

O Eventarc é um serviço do Google Cloud que permite criar arquiteturas orientadas por eventos sem precisar implementar, personalizar ou manter a infraestrutura subjacente.

Para criar um acionador do Eventarc, especifique filtros para o acionador e configure o roteamento do evento, incluindo a origem do evento e o serviço de destino do Cloud Run. Quando o evento ou o conjunto de eventos especificados correspondem aos filtros, o serviço do Cloud Run é invocado automaticamente em resposta aos eventos. Um serviço que utiliza gatilhos Eventarc é chamado de serviço orientado a eventos. Os eventos enviados para o seu serviço Cloud Run são recebidos na forma de solicitações HTTP.

Os seguintes tipos de evento podem acionar solicitações para seu serviço:

Local do gatilho

Ao criar um acionador do Eventarc, você especifica um local para ele. Ele precisa corresponder ao local do recurso Google Cloud que você quer monitorar para eventos. Na maioria dos cenários, você também precisa implantar o serviço do Cloud Run orientado a eventos na mesma região. Para mais informações, consulte Entender os locais do Eventarc.

Identidade do acionador

Ao criar um gatilho do Eventarc, você especifica uma conta de serviço do Identity and Access Management (IAM). O gatilho usa essa conta de serviço como identidade padrão. Recomendamos que você especifique uma conta de serviço gerenciado pelo usuário e conceda a ela as permissões mínimas necessárias.

Antes de começar

  1. Configure seu ambiente do Cloud Run.

  2. Ative as APIs Artifact Registry, Cloud Build, API Cloud Run Admin e Eventarc:

    Ativar as APIs

  3. Conceda as funções e permissões IAM necessárias.

Criar um gatilho para serviços

Depois de implantar um serviço, é possível configurar um acionador usando o console Google Cloud , a Google Cloud CLI ou o Terraform.

Console

  1. Implante seu serviço do Cloud Run usando contêineres ou de origem.

  2. No console Google Cloud , vá para Cloud Run:

    Acesse o Cloud Run

  3. Na lista de serviços, clique em um serviço atual.

  4. Na página de detalhes do serviço, acesse a guia Gatilhos.

  5. Clique em Adicionar acionador e selecione uma opção.

  6. No painel Gatilho do Eventarc, modifique os detalhes do gatilho da seguinte maneira:

    1. No campo Nome do gatilho, insira um nome para o gatilho ou use o nome padrão.

    2. Selecione um Tipo de acionador na lista para especificar um dos seguintes tipos de acionador:

      • Fontes do Google para especificar acionadores para Pub/Sub, Cloud Storage, Firestore, e outros provedores de eventos do Google.

      • Terceiros para integração com provedores que não são do Google que oferecem uma origem do Eventarc. Para mais informações, consulte Eventos de terceiros no Eventarc.

    3. Selecione um provedor de eventos na lista Provedor de eventos para escolher um produto que ofereça o tipo de evento para acionar seu serviço. Para ver a lista de provedores de eventos, consulte Provedores e destinos de eventos.

    4. Selecione um tipo de evento na lista Tipo de evento. A configuração do gatilho varia de acordo com o tipo de evento compatível: Para mais informações, consulte Tipos de eventos.

    5. Se o campo Região estiver habilitado, selecione um local para o gatilho Eventarc. Em geral, a localização de um gatilho Eventarc deve corresponder à localização do Google Cloud Recurso que você deseja monitorar em busca de eventos. Na maioria dos cenários, você também precisa implantar o serviço na mesma região. Consulte Noções básicas sobre locais do Eventarc para mais detalhes sobre locais de acionador do Eventarc.

    6. No campo Conta de serviço, selecione uma conta de serviço. Os acionadores do Eventarc são vinculados a contas de serviço para usar como uma identidade ao invocar o serviço. A conta de serviço do acionador do Eventarc precisa ter permissão para invocar o serviço. Por padrão, o Cloud Run usa a conta de serviço padrão do Compute Engine.

    7. Se quiser, especifique o caminho do URL do serviço para enviar a solicitação recebida. Esse é o caminho relativo no serviço de destino para o qual os eventos do gatilho precisam ser enviados. Por exemplo: /, /route, route e route/subroute.

    8. Se quiser ativar novas tentativas em caso de falha na tentativa de entrega, marque a caixa de seleção Ativar novas tentativas em caso de falha. Caso contrário, o comportamento padrão é uma única tentativa de entrega sem novas tentativas. Para obter mais informações, consulte Repetir eventos.

    9. Depois de preencher os campos obrigatórios, clique em Salvar gatilho.

  7. Depois de criar o gatilho, verifique a integridade garantindo que haja uma marca de seleção na guia Gatilhos.

gcloud

  1. Implante seu serviço do Cloud Run usando contêineres ou de origem.

  2. Execute o seguinte comando para criar um gatilho que filtra e encaminha eventos:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE  \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --max-retry-attempts=1 \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Substitua:

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

      Para evitar problemas de desempenho e de residência de dados, a localização deve corresponder à localização do Google Cloud serviço que está gerando eventos. Saiba mais em Locais do Eventarc.

    • DESTINATION_RUN_SERVICE: o nome do serviço do Cloud Run que recebe os eventos do gatilho. O serviço pode estar em qualquer um dos locais compatíveis com o Cloud Run e não precisa estar no mesmo local que o gatilho. No entanto, o serviço precisa estar no mesmo projeto que o gatilho e receberá eventos como solicitações POST HTTP enviadas para o caminho de URL raiz (/) sempre que o evento for gerado.
    • DESTINATION_RUN_REGION: (opcional) o local do Cloud Run em que o serviço de destino do Cloud Run pode ser encontrado. Se não especificado, presume-se que o serviço está na mesma região 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 do Google compatíveis com o Eventarc.
    • SERVICE_ACCOUNT_NAME: o nome da conta de serviço gerenciada pelo usuário.
    • PROJECT_ID: o ID do projeto Google Cloud .

    Observações:

    • 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.
    • Opcionalmente, para especificar uma única tentativa de entrega de evento sem novas tentativas, use a flag --max-retry-attempts. O único valor válido é 1. Se você omitir a flag, o comportamento padrão de repetição será aplicado. Para mais informações, consulte Repetir eventos.
    • Outras flags estão disponíveis. Para obter mais informações, consulte gcloud eventarc triggers create.

Terraform

Para criar um gatilho do Eventarc para um serviço do Cloud Run, consulte Criar um gatilho usando o Terraform.

Criar um gatilho para funções

Depois de implantar uma função, é possível configurar um gatilho usando o console Google Cloud , a Google Cloud CLI ou o Terraform.

Console

Ao usar o console do Google Cloud para criar uma função, também é possível adicionar um acionador a ela. Siga estas etapas para criar um acionador para sua função:

  1. No Google Cloud console, acesse o Cloud Run:

    Acessar o Cloud Run

  2. Clique em Escrever uma função e insira os detalhes dela. Para mais informações sobre como configurar funções durante a implantação, consulte Implantar funções.

  3. Na seção Gatilho, clique em Adicionar gatilho.

  4. Selecione uma opção.

  5. No painel Gatilho do Eventarc, modifique os detalhes do gatilho da seguinte maneira:

    1. Insira um nome para o gatilho no campo Nome do gatilho ou use o nome padrão.

    2. Selecione um Tipo de acionador na lista:

      • Fontes do Google para especificar acionadores para Pub/Sub, Cloud Storage, Firestore, e outros provedores de eventos do Google.

      • Terceiros para integração com provedores que não são do Google que oferecem uma origem do Eventarc. Para mais informações, consulte Eventos de terceiros no Eventarc.

    3. Selecione um provedor de eventos na lista Provedor de eventos para escolher um produto que ofereça o tipo de evento para acionar sua função. Para ver a lista de provedores de eventos, consulte Provedores e destinos de eventos.

    4. Selecione um tipo de evento na lista Tipo de evento. A configuração do gatilho varia de acordo com o tipo de evento compatível: Para mais informações, consulte Tipos de eventos.

    5. Se o campo Região estiver ativado, selecione um local para o gatilho do Eventarc. Em geral, o local de um gatilho do Eventarc precisa corresponder ao local do recursoGoogle Cloud que você quer monitorar para eventos. Na maioria dos cenários, você também precisa implantar a função na mesma região. Consulte Entender locais do Eventarc para obter mais detalhes sobre os locais de gatilho do Eventarc.

    6. No campo Conta de serviço, selecione uma conta de serviço. Os acionadores do Eventarc são vinculados a contas de serviço para usar como uma identidade ao invocar a função. A conta de serviço do acionador do Eventarc precisa ter permissão para invocar a função. Por padrão, o Cloud Run usa a conta de serviço padrão do Compute Engine.

    7. Se quiser, especifique o caminho do URL do serviço para enviar a solicitação recebida. Esse é o caminho relativo no serviço de destino para o qual os eventos do gatilho precisam ser enviados. Por exemplo: /, /route, route e route/subroute.

    8. Se quiser ativar novas tentativas em caso de falha na tentativa de entrega, marque a caixa de seleção Ativar novas tentativas em caso de falha. Caso contrário, o comportamento padrão é uma única tentativa de entrega sem novas tentativas. Para obter mais informações, consulte Repetir eventos.

  6. Depois de preencher os campos obrigatórios, clique em Salvar gatilho.

  7. Clique em Criar.

  8. Na aba Source, edite o código-fonte, se necessário, e selecione Salvar e reimplantar.

gcloud

Ao criar uma função usando a CLI gcloud, você deve primeiro deploy sua função e, em seguida, criar um gatilho. Siga estas etapas para criar um gatilho para sua função:

  1. Execute o seguinte comando no diretório que contém o exemplo de código para implantar sua função:

    gcloud run deploy FUNCTION \
    --source . \
    --function FUNCTION_ENTRYPOINT \
    --base-image BASE_IMAGE_ID \
    --region REGION

    Substitua:

    • FUNCTION: o nome da função que você está implantando. É possível omitir esse parâmetro inteiramente, mas será solicitado o nome, se você omiti-lo.

    • FUNCTION_ENTRYPOINT: o ponto de entrada da função no código-fonte. Esse é o código que o Cloud Run executa quando a função é executada. O valor dessa sinalização precisa ser um nome de função ou de classe totalmente qualificada no código-fonte.

    • BASE_IMAGE_ID: o ambiente de imagem de base para sua função. Para mais detalhes sobre as imagens de base e os pacotes incluídos em cada imagem, consulte Imagens de base dos ambientes de execução.

    • REGION: a Google Cloud região em que você quer implantar a função. Por exemplo, europe-west1.

  2. Execute o comando a seguir para criar um gatilho que filtra e encaminha eventos:

    gcloud eventarc triggers create TRIGGER_NAME \
    --location=LOCATION \
    --destination-run-service=FUNCTION \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --max-retry-attempts=1 \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Substitua:

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

      Para evitar problemas de desempenho e de residência de dados, a localização deve corresponder à localização do Google Cloud serviço que está gerando eventos. Saiba mais em Locais do Eventarc.

    • FUNCTION: o nome da função implantada do Cloud Run que recebe os eventos do gatilho.
    • DESTINATION_RUN_REGION: (opcional) o local do Cloud Run em que a função de destino do Cloud Run pode ser encontrada. Se não especificado, presume-se que a função está na mesma região 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 do Google compatíveis com o Eventarc.
    • SERVICE_ACCOUNT_NAME: o nome da conta de serviço gerenciada pelo usuário.
    • PROJECT_ID: o ID do projeto Google Cloud .

    Observações:

    • 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.
    • Opcionalmente, para especificar uma única tentativa de entrega de evento sem novas tentativas, use a flag --max-retry-attempts. O único valor válido é 1. Se você omitir a flag, o comportamento padrão de repetição será aplicado. Para mais informações, consulte Repetir eventos.
    • Outras flags estão disponíveis. Para obter mais informações, consulte gcloud eventarc triggers create.

Terraform

Para criar um gatilho do Eventarc para uma função do Cloud Run, consulte Criar um gatilho usando o Terraform.

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

As funções do Cloud Run orientadas a eventos são implementadas usando o Eventarc em combinação com uma assinatura do Pub/Sub. Por padrão, o prazo de confirmação (ack) dessa assinatura do Pub/Sub é de 10 segundos. Essa configuração é insuficiente para muitas funções e pode ter o efeito de causar execuções duplicadas indesejadas.

Recomendamos que você defina o prazo ack para seu serviço ou função com o valor máximo de 600 segundos, conforme mostrado a seguir:

Console

Depois de implantar a função, siga estas etapas para modificar o prazo ack dela:

  1. No console Google Cloud , vá para Cloud Run:

    Acesse o Cloud Run

  2. Localize a função que você quer atualizar na lista de serviços e clique nela para abrir os detalhes.

  3. Abra a guia Gatilhos.

  4. Clique no nome do gatilho para abrir Detalhes do gatilho.

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

  6. Clique no nome ID da assinatura para acessar o painel de assinatura e clique em Editar na parte de cima da página.

  7. Defina o valor do Prazo de confirmação como 600 e clique em Atualizar para salvar a mudança.

gcloud

Atualize o prazo de ack por acionador para o valor máximo de 600 segundos. Os comandos a seguir fazem referência a variáveis (TRIGGER_NAME e LOCATION) cujos valores foram definidos nas etapas anteriores.

## Per Cloud Run function:

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

Execute uma atualização em massa em todos os gatilhos de serviço e função para definir seus prazos ack para 600 segundos:

### Match all Cloud Run service triggers and update all deadlines to 600s (max timeout)
### This will change ALL Cloud Run services and Cloud Run functions
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 $LOCATION --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

Ver o ID e a origem do CloudEvent

Para conferir o ID e a origem do CloudEvent que acionaram seu serviço, consulte os seguintes recursos nos registros de serviço do Cloud Run:

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

A seguir