Criar gatilhos com base em eventos do Pub/Sub

No Cloud Run, é possível acionar serviços em resposta a mensagens do Pub/Sub usando o Eventarc. Ao especificar um gatilho do Pub/Sub para seu serviço, você também especifica um tópico do Pub/Sub. Como resultado desse gatilho, seu serviço é chamado sempre que você publica uma mensagem no tópico especificado.

O repositório de eventos do Google contém outros recursos para trabalhar com dados de eventos.

Antes de começar

  1. Verifique se você configurou um novo projeto para o Cloud Run conforme descrito na página de configuração.

  2. Ative o Artifact Registry, o Cloud Build, a API Cloud Run Admin, o Eventarc, o Cloud Logging e as APIs Pub/Sub:

    Ativar as APIs

  3. Conceda os papéis e as permissões necessários do IAM.

Papéis necessários para a conta do implantador

Para receber as permissões necessárias para acionar eventos do Pub/Sub, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Observe que, por padrão, Cloud Build as permissões incluem permissões para upload e download de artefatos do Artifact Registry.

Criar um gatilho para serviços

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

Console

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

  2. No Google Cloud console, acesse o 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, navegue até a guia Acionadores.

  5. Clique em Adicionar gatilho e selecione Gatilho do Pub/Sub.

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

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

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

      • Fontes do Google para especificar gatilhos 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 Pub/Sub na lista Provedor de eventos para selecionar 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 google.cloud.pubsub.topic.v1.messagePublished 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. No campo de tópico Selecionar um tópico do Cloud Pub/Sub, escolha um tópico para o gatilho monitorar. As mensagens publicadas nesse tópico acionam chamadas para sua função.

    6. 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 Google Cloud recurso que você quer monitorar para 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 gatilho do Eventarc.

    7. No campo Conta de serviço, selecione uma conta de serviço. Os gatilhos 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 gatilho 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.

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

    9. Se quiser ativar novas tentativas caso a tentativa de entrega falhe, 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 mais informações, consulte Eventos de nova tentativa.

    10. 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 o serviço do Cloud Run usando contêineres ou da origem.

  2. Execute o comando a seguir para criar um gatilho que filtre e encaminhe eventos:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE  \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
    --transport-topic=projects/PROJECT_ID/topics/TOPIC_ID \
    --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 residência de dados, o local precisa corresponder ao 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 do 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.
    • A flag --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" é obrigatória e não pode ser alterada. Para um tipo de evento diferente, crie um novo gatilho.
    • TOPIC_ID: o ID do tópico do Pub/Sub atual. O tópico precisa estar no mesmo projeto que o gatilho.
    • SERVICE_ACCOUNT_NAME: o nome da conta de serviço gerenciado pelo usuário.
    • PROJECT_ID: o ID do Google Cloud projeto.

    Observações:

    • Se quiser especificar uma única tentativa de entrega de eventos sem novas tentativas, use a --max-retry-attempts flag. O único valor válido é 1. Se você omitir a flag, o comportamento de nova tentativa padrão será aplicado. Para mais informações, consulte Eventos de nova tentativa.
    • Outras flags estão disponíveis. Para 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 Google Cloud console, a Google Cloud CLI ou o Terraform.

Console

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

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

    Acesse o Cloud Run

  2. Clique em Escrever uma função e insira os detalhes da função. 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 Gatilho do Pub/Sub.

  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 gatilho na lista:

      • Fontes do Google para especificar gatilhos 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 Pub/Sub na lista Provedor de eventos para selecionar 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 google.cloud.pubsub.topic.v1.messagePublished 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. No campo de tópico Selecionar um tópico do Cloud Pub/Sub, escolha um tópico para o gatilho monitorar. As mensagens publicadas nesse tópico acionam chamadas para sua função.

    6. 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 Google Cloud recurso que você quer monitorar para eventos. Na maioria dos cenários, você também precisa implantar a função na mesma região. Consulte Noções básicas sobre locais do Eventarc para mais detalhes sobre locais de gatilho do Eventarc.

    7. No campo Conta de serviço, selecione uma conta de serviço. Os gatilhos 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 gatilho 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.

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

    9. Se quiser ativar novas tentativas caso a tentativa de entrega falhe, 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 mais informações, consulte Eventos de nova tentativa.

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

  7. Clique em Criar.

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

gcloud

Ao criar uma função usando a CLI gcloud, primeiro implante a função e depois crie um gatilho. Siga estas etapas para criar um gatilho para sua função:

  1. Execute o comando a seguir no diretório que contém o exemplo de código para implantar a 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 é executada. O valor dessa flag 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 filtre e encaminhe eventos:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
    --transport-topic=projects/PROJECT_ID/topics/TOPIC_ID \
    --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 residência de dados, o local precisa corresponder ao 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 for especificado, presumirá que a função está na mesma região que o gatilho.
    • A flag --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" é obrigatória e não pode ser alterada. Para um tipo de evento diferente, crie um novo gatilho.
    • TOPIC_ID: o ID do tópico do Pub/Sub atual. O tópico precisa estar no mesmo projeto que o gatilho.
    • SERVICE_ACCOUNT_NAME: o nome da conta de serviço gerenciado pelo usuário.
    • PROJECT_ID: o ID do Google Cloud projeto.

    Observações:

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

Próximas etapas