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

   Ativar as APIs

3. Conceda as permissões e os papéis 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:

• Desenvolvedor de origem do Cloud Run (roles/run.sourceDeveloper)
• Acessador de exibição de registros (roles/logging.viewAccessor)
• Administrador de projetos do IAM (roles/resourcemanager.projectIamAdmin)
• Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
• Usuário da conta de serviço (roles/iam.serviceAccountUser)
• Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin)

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.

Por padrão, as permissões do Cloud Build 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 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 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, acesse a guia Gatilhos.

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 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 Pub/Sub 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 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 Selecionar um tópico do Cloud Pub/Sub, escolha um tópico para o acionador 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 recurso Google Cloud 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 acionador do Eventarc.

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

   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 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 mais informações, consulte Repetir eventos.

   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.

   Observação: o gatilho é criado imediatamente, mas pode levar até dois minutos para que ele seja propagado e filtre eventos.

gcloud

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

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=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 serviço Google Cloud 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
   • 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 gerenciada pelo usuário.
   • PROJECT_ID: o ID do projeto Google Cloud .

   Observações:

   • 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 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 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 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 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 Selecionar um tópico do Cloud Pub/Sub, escolha um tópico para o acionador 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 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 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 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.

   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 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 mais informações, consulte Repetir eventos.

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

gcloud

Ao criar uma função usando a CLI gcloud, primeiro é necessário implantar a 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=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 serviço Google Cloud 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.
   • 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 gerenciada pelo usuário.
   • PROJECT_ID: o ID do projeto Google Cloud .

   Observações:

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

Próximas etapas

• Saiba como acionar com eventos.
• Saiba como acionar serviços do Pub/Sub.
• Saiba como configurar novas tentativas.