Criar gatilhos com base em eventos do Pub/Sub

É possível invocar serviços e funções do Cloud Run configurando um gatilho do Pub/Sub.

Ao configurar o gatilho, você o vincula a um tópico específico do Pub/Sub. Isso garante que o serviço ou a função seja chamado automaticamente sempre que uma mensagem for publicada nesse tópico.

É possível configurar esse gatilho de duas maneiras:

  • Gatilho direto do Pub/Sub (recomendado): encaminhe mensagens diretamente para o serviço ou função usando o Pub/Sub. Você gerencia a assinatura diretamente, e seu serviço ou função recebe a solicitação de push padrão do Pub/Sub. Use essa opção se precisar de uma configuração mais simples e de menor latência.
  • Gatilho baseado no Eventarc: encaminhe mensagens do Pub/Sub para seu serviço ou função usando o Eventarc. Você gerencia os gatilhos do Pub/Sub da mesma forma que outras origens do Eventarc, e seu serviço ou função recebe eventos como CloudEvents. Use essa opção se precisar dos recursos avançados de filtragem ou roteamento do Eventarc.

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 as APIs Artifact Registry, Cloud Build, Cloud Run Admin, Cloud Logging e Pub/Sub:

    Ativar as APIs

    Se você estiver configurando um gatilho baseado no Eventarc, também será necessário ativar a API Eventarc:

    Ativar a API Eventarc

Funções exigidas

Conceda as permissões e os papéis necessários do IAM. Se você estiver configurando um gatilho baseado no Eventarc, consulte os papéis e as permissões do IAM necessários para o Eventarc.

Papéis necessários para a conta de 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 usando papéis personalizados ou outros papéis predefinidos.

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

Criar um gatilho do Pub/Sub

Console

  1. No console do Google Cloud , acesse a página Serviços do Cloud Run:

    Acessar o Cloud Run

  2. Clique no serviço ou na função para criar um gatilho do Pub/Sub.

  3. Selecione a guia Gatilhos.

    Selecione a guia da configuração de gatilho escolhida:

    1. Clique em Adicionar gatilho e selecione Gatilho do Pub/Sub > Direto.
    2. No painel Assinatura direta do Pub/Sub:
      • No campo Tópico do Cloud Pub/Sub, selecione o tópico se você já tiver criado um ou clique em Criar novo tópico para criar um novo tópico.
      • No campo Conta de serviço, selecione a conta de serviço que a assinatura usa para invocar seu serviço. Se o console listar papéis ausentes, clique em Conceder todos.
      • No Caminho do URL do serviço, insira o caminho no serviço que vai receber mensagens, como / (padrão) ou /pubsub. O console adiciona esse caminho ao URL do serviço.
    3. Clique em Salvar.

    Eventarc

    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 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. Na lista Selecionar um tópico do Cloud Pub/Sub, escolha um tópico para o acionador monitorar. As mensagens publicadas neste tópico acionarão 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 recurso doGoogle 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 Noções básicas sobre locais do Eventarc para mais detalhes sobre locais de acionador 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 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.

    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 em caso de falha na entrega, marque a caixa de seleção Ativar nova tentativa em caso de falha. Caso contrário, o comportamento padrão será uma única tentativa de entrega sem novas tentativas. Para mais informações, consulte Repetir eventos.

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

gcloud

Para criar um gatilho para seu serviço ou função usando a CLI gcloud:

  1. Implante o serviço ou a função, caso ainda não tenha feito isso.

  2. Se você já tiver um tópico do Pub/Sub, pule esta etapa. Caso contrário, crie um tópico do Pub/Sub:

    gcloud pubsub topics create TOPIC_NAME

  3. Selecione a guia da configuração de gatilho escolhida:

    Direto

    1. Configure os papéis necessários para o agente de serviço do Pub/Sub:

      Papéis necessários para o agente de serviço do Pub/Sub

      As etapas a seguir descrevem como criar e usar uma conta de serviço que pode ser usada pela assinatura do Pub/Sub para invocar seu serviço ou função. Essas etapas são necessárias ao usar a Google Cloud CLI para criar um comando de gatilho do Pub/Sub. Se você estiver usando o console do Google Cloud para criar o gatilho, pule estas etapas.

      1. Crie ou selecione uma conta de serviço para representar a identidade da assinatura do Pub/Sub.

             gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
        --display-name "Cloud Run Pub/Sub Invoker"

        Substitua SERVICE_ACCOUNT_NAME por um nome exclusivo para sua conta de serviço.

      2. Conceda permissão à conta de serviço do invocador para invocar seu serviço:

          gcloud run services add-iam-policy-binding SERVICE_NAME \
     --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID. \
     --role=roles/run.invoker

        Pode levar vários minutos para que as alterações do IAM sejam propagadas. Enquanto isso, talvez você veja erros HTTP 403 nos registros do serviço.

      3. Permita que o Pub/Sub crie tokens de autenticação no seu projeto:

          gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub. \
     --role=roles/iam.serviceAccountTokenCreator

        Substitua:

        • PROJECT_ID: o ID do projeto Google Cloud .
        • PROJECT_NUMBER: o número do projeto do Google Cloud .

        O ID do projeto e o número do projeto estão listados no painel Informações do projeto no console doGoogle Cloud do seu projeto.

    2. Crie uma assinatura do Pub/Sub com a conta de serviço:

      gcloud pubsub subscriptions create SUBSCRIPTION_NAME \
  --topic TOPIC_NAME \
  --ack-deadline=600 \
  --push-endpoint=SERVICE_URL/ \
  --push-auth-service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.

      Substitua:

      • SUBSCRIPTION_NAME: o nome da assinatura que você quer criar.
      • TOPIC_NAME: o nome do tópico que você criou anteriormente.
      • SERVICE_URL: o URL HTTPS fornecido ao implantar o serviço. Esse URL funciona mesmo que você também tenha adicionado um mapeamento de domínio.
      • SERVICE_ACCOUNT_NAME: o nome da conta de serviço que você criou anteriormente.
      • PROJECT_ID: o ID do projeto do Google Cloud .

      Observações:

      • A flag --push-auth-service-account ativa a funcionalidade de push do Pub/Sub para Autenticação e autorização.

      • O domínio do serviço do Cloud Run é registrado automaticamente para uso com assinaturas do Pub/Sub.

      • Somente para o Cloud Run, há uma verificação de autenticação integrada para confirmar se o token é válido e uma verificação de autorização para confirmar se a conta de serviço tem permissão para invocar o serviço do Cloud Run.

    Eventarc

    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_NAME \
   --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.

    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 serviço do Google Cloud que está gerando eventos. Saiba mais em Locais do Eventarc.

    • DESTINATION_RUN_SERVICE: o nome do serviço implantado ou da função do Cloud Run que recebe os eventos do gatilho.
    • DESTINATION_RUN_REGION: (opcional) a Cloud Run location em que a função do Cloud Run de destino pode ser encontrada. Se não for especificado, presume-se que a função esteja 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_NAME: 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 gerenciada pelo usuário.
    • PROJECT_ID: o ID do projeto Google Cloud .

    Observações:

    • Como opção, 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 de nova tentativa padrão será aplicado. Para mais informações, consulte Repetir eventos.
    • Outras sinalizações 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.

Próximas etapas