Talvez seu fluxo de trabalho precise aguardar um processo externo. É possível usar callbacks HTTP para aguardar que outro serviço faça uma solicitação para um endpoint de callback. Essa solicitação retoma a execução do fluxo de trabalho. Também é possível aguardar usando a pesquisa.
Em vez de usar a pesquisa, este tutorial demonstra como esperar eventos ou mensagens do Pub/Sub usando callbacks HTTP e acionadores do Eventarc. É possível acionar um fluxo de trabalho com eventos ou mensagens do Pub/Sub, mas convém interromper essa execução para aguardar outro evento antes de continuar. Por exemplo, um evento aciona um fluxo de trabalho para iniciar um processo, mas o fluxo de trabalho precisa aguardar outro evento que indique que o processo foi concluído. É possível implementar isso fazendo com que um fluxo de trabalho retorne outro fluxo de trabalho.
Objetivos
Neste tutorial, acontece o seguinte:
Um fluxo de trabalho principal que precisa aguardar eventos é implantado e executado. Como é necessário aguardar a ocorrência dos eventos, ele armazena os detalhes do callback em um banco de dados do Firestore para que o fluxo de trabalho secundário possa recuperar os detalhes. Em seguida, o fluxo de trabalho principal aguarda as chamadas HTTP.
Um fluxo de trabalho secundário é acionado pelos eventos e recupera os detalhes do callback do banco de dados do Firestore quando os eventos são gerados. Em seguida, o fluxo de trabalho secundário chama o fluxo de trabalho principal, que retoma a execução.
Esta é uma visão geral de todo o processo:
Fluxo de trabalho principal:
- Um fluxo de trabalho
callback-event-sample
cria endpoints de callback para duas fontes de eventos: um tópico do Pub/Sub e um bucket do Cloud Storage. - Esse fluxo de trabalho armazena os dois endpoints de callback em um documento do Firestore.
- Esse fluxo de trabalho interrompe a execução e espera que as solicitações HTTP cheguem aos endpoints de callback.
Eventos:
- Os eventos ocorrem: uma mensagem é publicada em um tópico do Pub/Sub, e um arquivo é enviado para um bucket do Cloud Storage.
Fluxo de trabalho secundário:
- O Eventarc encaminha os eventos para o
fluxo de trabalho
callback-event-listener
e aciona a execução dele. - Esse fluxo de trabalho recupera os URLs apropriados do endpoint de callback do documento do Firestore.
- Esse fluxo de trabalho executa os callbacks para os endpoints apropriados no fluxo de trabalho de amostra.
Fluxo de trabalho principal:
- O fluxo de trabalho
callback-event-sample
recebe os eventos nos endpoints de callback e retoma a execução. - Esse fluxo de trabalho exclui os URLs de callback do documento do Firestore e conclui a execução.
Custos
Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:
Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.
Antes de começar
É possível executar os comandos a seguir no console do Google Cloud ou usando a Google Cloud CLI no seu terminal ou no Cloud Shell.
As restrições de segurança definidas pela sua organização podem impedir que você conclua as etapas a seguir. Para informações sobre solução de problemas, consulte Desenvolver aplicativos em um ambiente restrito do Google Cloud.
Console
No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.
Verifique se a cobrança está ativada para o projeto do Google Cloud. Saiba como verificar se o faturamento está ativado em um projeto.
Ative as APIs App Engine, Eventarc, Firestore, Pub/Sub e Workflows.
Crie uma conta de serviço para seu fluxo de trabalho usar para autenticação com outros serviços do Google Cloud e conceda os papéis apropriados:
No console do Google Cloud, acesse a página Contas de serviço.
Para acessar a página Criar conta de serviço, selecione seu projeto.
No campo Nome da conta de serviço, insira um nome. O Console do Google Cloud preenche o campo ID da conta de serviço com base nesse nome.
No campo Descrição da conta de serviço, insira uma descrição. Por exemplo,
Service account for tutorial
.Clique em Criar e continuar.
Na lista Selecionar um papel, filtre os seguintes papéis para conceder à conta de serviço gerenciado pelo usuário criada na etapa anterior:
- Usuário do Cloud Datastore: para acessar dados do Firestore no modo Datastore (Datastore).
- Receptor de eventos do Eventarc: para receber eventos de provedores de eventos.
- Gravador de registros: para gravar registros.
- Invocador de fluxos de trabalho: para executar fluxos de trabalho e gerenciar as execuções.
Para papéis adicionais, clique em
Adicionar outro papel e adicione os papéis adicionais.Clique em Continuar.
Para concluir a criação da conta, clique em Concluído.
Para criar um gatilho do Eventarc que roteie eventos do Cloud Storage, conceda o papel Publicador do Pub/Sub ao agente de serviço do Cloud Storage. Normalmente, é o agente
service-PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com
. É possível recuperar o endereço de e-mail do agente de serviço do Cloud Storage.No console do Google Cloud, abra a página IAM.
Na linha do agente de serviço do Cloud Storage, clique em
Editar principal. Se o agente de serviço não estiver listado, prossiga para a próxima etapa. O painel Editar acesso será aberto.- Clique em addAdicionar outro papel e pesquise o papel Editor do Pub/Sub.
- Selecione o papel.
- Clique em Salvar.
Se o agente de serviço não estiver listado, clique em
Conceder acesso. O painel Conceder acesso será aberto.- No campo Novos principais, insira o endereço de e-mail do agente de serviço.
- Na lista Selecionar um papel, procure o papel Editor do Pub/Sub.
- Selecione o papel.
- Clique em Salvar.
gcloud
No Console do Google Cloud, ative o Cloud Shell.
Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Verifique se a cobrança está ativada para o projeto do Google Cloud. Saiba como verificar se o faturamento está ativado em um projeto.
Ative as APIs App Engine, Eventarc, Firestore, Pub/Sub e Workflows.
gcloud services enable \ appengine.googleapis.com \ eventarc.googleapis.com \ firestore.googleapis.com \ pubsub.googleapis.com \ workflows.googleapis.com
Crie uma conta de serviço para seu fluxo de trabalho usar para autenticação com outros serviços do Google Cloud e conceda os papéis apropriados.
Crie a conta de serviço:
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
Substitua
SERVICE_ACCOUNT_NAME
por um nome para a conta de serviço.Conceda papéis à conta de serviço gerenciado pelo usuário que você criou na etapa anterior. Execute o comando a seguir uma vez para cada um dos seguintes papéis do IAM:
roles/datastore.user
: para acessar dados do Firestore no modo Datastore (Datastore).roles/eventarc.eventReceiver
: para receber eventos de provedores de eventos.roles/logging.logWriter
: para gravar registros.roles/workflows.invoker
: para executar fluxos de trabalho e gerenciar as execuções.
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \ --role=ROLE
Substitua:
PROJECT_ID
: o ID do projeto em que você criou a conta de serviço;ROLE
: o papel a ser concedido
Para criar um gatilho do Eventarc que roteie eventos do Cloud Storage, conceda o papel de Publicador do Pub/Sub ao agente de serviço do Cloud Storage. Normalmente, isso é
service-PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com
. Use ogsutil kms serviceaccount
para recuperar o agente de serviço do Cloud Storage primeiro.SERVICE_ACCOUNT_STORAGE="$(gsutil kms serviceaccount -p PROJECT_ID)" gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:$SERVICE_ACCOUNT_STORAGE \ --role=roles/pubsub.publisher
Crie um banco de dados do Firestore
O Firestore armazena os dados em documentos que contêm campos que mapeiam valores. Esses documentos são armazenados em coleções, que são contêineres de documentos que podem ser usados para organizar dados e criar consultas. Saiba mais sobre o Firestore.
Cada projeto do Google Cloud é limitado a um banco de dados do Firestore. Conclua as etapas a seguir se precisar criar um novo banco de dados.
Console
No console do Google Cloud, acesse a página Primeiros passos do Firestore.
Clique em Selecionar modo nativo.
Para saber como selecionar um banco de dados e uma comparação recurso a recurso, consulte Como escolher entre o modo nativo e o modo Datastore.
Na lista Selecionar um local, escolha nam5 (Estados Unidos).
O local se aplica ao banco de dados do Firestore e ao aplicativo do App Engine no seu projeto do Google Cloud. Depois de criar seu banco de dados, não é possível alterar o local.
Clique em Criar banco de dados.
gcloud
Para criar um banco de dados do Firestore, primeiro crie um
aplicativo do App Engine e, em seguida, execute o
comando
gcloud firestore databases create
:
gcloud app create --region=us-central gcloud firestore databases create --region=us-central
Você pode ignorar o alerta us-central is not a valid Firestore location
.
O App Engine e o Firestore são compatíveis com os mesmos locais,
mas a região us-central
(Iowa) do App Engine é mapeada para
a multirregião
nam5
do Firestore (Estados Unidos).
Criar um tópico do Pub/Sub.
Neste tutorial, usamos o Pub/Sub como uma origem de eventos. Crie um tópico do Pub/Sub para poder publicar uma mensagem nele. Saiba mais sobre como criar e gerenciar tópicos.
Console
No console do Google Cloud, acesse a página Tópicos do Pub/Sub.
Clique em
Criar tópico.No campo ID do tópico, digite
topic-callback
.Aceite os outros padrões.
Selecione Criar tópico.
gcloud
Para criar um tópico, execute o comando gcloud pubsub topics create
:
gcloud pubsub topics create topic-callback
Criar um bucket do Cloud Storage
Neste tutorial, usamos o Cloud Storage como uma origem de eventos. Crie um bucket do Cloud Storage para fazer upload de um arquivo nele. Saiba como criar buckets de armazenamento.
Console
No console do Google Cloud, acesse a página Buckets do Cloud Storage.
Clique em
Criar.Em Nome do bucket, insira
PROJECT_ID-bucket-callback
.O ID do projeto é usado no fluxo de trabalho
callback-event-sample
para identificar o bucket.Clique em Continuar.
Em Tipo de local, selecione Região e, em seguida, us-central1 (Iowa).
Aceite os outros padrões.
Clique em Criar.
gcloud
Para criar um bucket, execute o comando gcloud storage buckets create
:
gcloud storage buckets create gs://PROJECT_ID-bucket-callback \ --location=us-central1
O ID do projeto
é usado no fluxo de trabalho callback-event-sample
para identificar o bucket.
Depois que as origens de eventos forem criadas, implante o fluxo de trabalho do receptor de eventos.
Implantar um fluxo de trabalho que detecte eventos
O fluxo de trabalho callback-event-listener
é acionado quando uma mensagem é publicada
em um tópico do Pub/Sub ou quando um arquivo é enviado para um bucket do
Cloud Storage. O fluxo de trabalho recebe o evento, recupera os detalhes de callback
apropriados do banco de dados do Firestore e, em seguida, envia uma solicitação HTTP
para o endpoint de callback.
Console
No console do Google Cloud, acesse a página Fluxos de trabalho:
Clique em
Criar.Insira um nome para o novo fluxo de trabalho:
callback-event-listener
.Na lista Região, selecione us-central1.
Selecione a conta de serviço que você criou anteriormente.
Clique em Próxima.
No editor de fluxo de trabalho, insira a seguinte definição para seu fluxo de trabalho:
Selecione Implantar.
gcloud
Crie um arquivo de código-fonte para seu fluxo de trabalho:
touch callback-event-listener.yaml
Em um editor de texto, copie o fluxo de trabalho a seguir para seu arquivo de código-fonte:
Implante o fluxo de trabalho digitando o seguinte comando:
gcloud workflows deploy callback-event-listener \ --source=callback-event-listener.yaml \ --location=us-central1 \ --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
Substitua
SERVICE_ACCOUNT_NAME
pelo nome da conta de serviço que você criou anteriormente.
Implantar um fluxo de trabalho que aguarda eventos
O fluxo de trabalho callback-event-sample
armazena os detalhes do callback em um
banco de dados do Firestore, interrompe a execução e aguarda a ocorrência de
eventos específicos.
Console
No console do Google Cloud, acesse a página Fluxos de trabalho:
Clique em
Criar.Insira um nome para o novo fluxo de trabalho:
callback-event-sample
.Na lista Região, selecione us-central1.
Selecione a conta de serviço que você criou anteriormente.
Clique em Próxima.
No editor de fluxo de trabalho, insira a seguinte definição para seu fluxo de trabalho:
Selecione Implantar.
gcloud
Crie um arquivo de código-fonte para seu fluxo de trabalho:
touch callback-event-sample.yaml
Em um editor de texto, copie o fluxo de trabalho a seguir para seu arquivo de código-fonte:
Implante o fluxo de trabalho digitando o seguinte comando:
gcloud workflows deploy callback-event-sample \ --source=callback-event-sample.yaml \ --location=us-central1 \ --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
Substitua
SERVICE_ACCOUNT_NAME
pelo nome da conta de serviço que você criou anteriormente.
Criar um gatilho do Eventarc para rotear eventos do Pub/Sub
Um gatilho do Eventarc permite rotear eventos especificando
filtros para o gatilho, incluindo a origem do evento e o fluxo de trabalho de destino.
Criar um gatilho do Eventarc para executar o
fluxo de trabalho callback-event-listener
como resultado da publicação de uma mensagem em um
tópico do Pub/Sub.
Saiba mais sobre como acionar um fluxo de trabalho.
Console
No Console do Google Cloud, acesse a página do Eventarc.
Clique em
Criar gatilho.Digite um Nome de gatilho.
Por exemplo,
trigger-pubsub-events-listener
Na lista Provedor de eventos, selecione Cloud Pub/Sub.
Na lista Evento, em Personalizado, selecione google.cloud.pubsub.topic.v1.messagePublished.
Na lista Selecionar um tópico do Cloud Pub/Sub, escolha o tópico que você criou anteriormente.
Na lista Região, selecione us-central1 (Iowa).
Se solicitado, conceda o papel
iam.serviceAccountTokenCreator
à conta de serviço do Pub/Sub.Selecione a conta de serviço que você criou anteriormente.
Na lista Destino do evento, selecione Fluxos de trabalho.
Na lista Selecionar um fluxo de trabalho, selecione o fluxo de trabalho callback-event-listener.
Clique em Criar.
gcloud
Para criar um gatilho, execute o
comando
gcloud eventarc triggers create
:
gcloud eventarc triggers create trigger-pubsub-events-listener \ --location=us-central1 \ --destination-workflow=callback-event-listener \ --destination-workflow-location=us-central1 \ --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \ --transport-topic=topic-callback \ --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
Os eventos são transformados e transmitidos para a execução do fluxo de trabalho como argumentos de ambiente de execução. Pode levar até dois minutos para o novo gatilho ser ativado.
Criar um gatilho do Eventarc para rotear eventos do Cloud Storage
Um gatilho do Eventarc permite rotear eventos especificando
filtros para o gatilho, incluindo a origem do evento e o fluxo de trabalho de destino.
Criar um gatilho do Eventarc para executar o
fluxo de trabalho callback-event-listener
como resultado do upload de um arquivo para um
bucket do Cloud Storage.
Saiba mais sobre como acionar um fluxo de trabalho.
Console
No console do Google Cloud, acesse a página do Eventarc.
Clique em
Criar gatilho.Digite um Nome de gatilho.
Por exemplo,
trigger-storage-events-listener
Na lista Provedor de eventos, selecione Cloud Storage.
Na lista Evento, em Direto, selecione google.cloud.storage.object.v1.finalized.
Na lista Bucket, procure o bucket criado anteriormente e selecione-o.
Na lista Região, com base no seu bucket do Cloud Storage, aceite o padrão us-central1 (Iowa).
Se solicitado, conceda o papel
iam.serviceAccountTokenCreator
à conta de serviço do Pub/Sub.Selecione a conta de serviço que você criou anteriormente.
Na lista Destino do evento, selecione Fluxos de trabalho.
Na lista Selecionar um fluxo de trabalho, selecione o fluxo de trabalho callback-event-listener.
Clique em Criar.
gcloud
Para criar um gatilho, execute o
comando
gcloud eventarc triggers create
:
gcloud eventarc triggers create trigger-storage-events-listener \ --location=us-central1 \ --destination-workflow=callback-event-listener \ --destination-workflow-location=us-central1 \ --event-filters="type=google.cloud.storage.object.v1.finalized" \ --event-filters="bucket=PROJECT_ID-bucket-callback" \ --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
Os eventos são transformados e transmitidos para a execução do fluxo de trabalho como argumentos de ambiente de execução. Pode levar até dois minutos para o novo gatilho ser ativado.
Executar o fluxo de trabalho principal
Quando um fluxo de trabalho é executado, a definição atual associada
a ele também é. Execute o fluxo de trabalho callback-event-sample
. Esse é o fluxo de trabalho
principal, que aguarda a ocorrência de eventos específicos e só retoma a execução
quando o fluxo secundário faz as solicitações de callback adequadas.
Console
No console do Google Cloud, abra a página Workflows.
Na página Fluxos de trabalho, clique em callback-event-sample para acessar a página de detalhes.
Na página Detalhes do fluxo de trabalho, clique em play_arrow Executar.
Clique em Executar novamente.
A execução do fluxo de trabalho é iniciada. Durante a execução, você verá um estado de execução igual a
Running
e uma entrada de registro semelhante a esta:Started waiting 1hr for an event from source topic-callback
.
gcloud
Para executar um fluxo de trabalho, execute o
comando gcloud workflows run
:
gcloud workflows run callback-event-sample \ --location=us-central1
A execução do fluxo de trabalho é iniciada. Durante a execução, você verá um estado semelhante ao seguinte:
Waiting for execution [a848a164-268a-449c-b2fe-396f32f2ed66] to complete...working...
Gerar eventos e verificar o status da execução
É possível confirmar se os resultados são os esperados gerando eventos, visualizando entradas de registro e verificando o status de execução do fluxo de trabalho.
Publicar uma mensagem
Publique uma mensagem no tópico do Pub/Sub criado anteriormente.
Console
No console do Google Cloud, acesse a página Tópicos do Pub/Sub.
Clique em topic-callback.
Clique na guia Mensagens.
Clique em Publicar mensagem.
No campo Corpo da mensagem, digite
Hello World
.Clique em Publicar.
gcloud
Para publicar uma mensagem, use o comando gcloud pubsub topics publish:
gcloud pubsub topics publish topic-callback \ --message="Hello World"
Fazer upload de um objeto
Faça upload de um arquivo para o bucket do Cloud Storage criado anteriormente.
Console
- No console do Google Cloud, acesse a página Buckets do Cloud Storage.
Clique no nome do bucket que você criou.
Na guia Objetos, siga um destes procedimentos:
Arraste e solte o arquivo desejado da área de trabalho ou do gerenciador de arquivos para o painel principal no console do Google Cloud.
Clique em Fazer upload de arquivos, selecione o arquivo que você quer enviar e clique em Abrir.
gcloud
Para fazer upload de um arquivo, execute o comando
gcloud storage cp
:
gcloud storage cp OBJECT_LOCATION gs://PROJECT_ID-bucket-callback/
Substitua OBJECT_LOCATION
pelo caminho local do objeto. Por exemplo, random.txt
.
Exibir entradas de registro e status de execução
Confirme se o fluxo de trabalho callback-event-sample
foi concluído.
Console
No console do Google Cloud, abra a página Workflows.
Na página Fluxos de trabalho, clique em callback-event-sample para acessar a página de detalhes.
Na página Detalhes do fluxo de trabalho, para recuperar os detalhes de uma execução específica, clique no ID de execução apropriado.
O estado de execução será Concluído e, no painel "Saída", você verá os eventos do Pub/Sub e do Cloud Storage recebidos.
gcloud
Filtre as entradas de registro e retorne a saída no formato JSON:
gcloud logging read "resource.type=workflows.googleapis.com/Workflow AND textPayload:calling OR textPayload:waiting" \ --format=json
Procure entradas de registro semelhantes a:
"textPayload": "Stopped waiting for an event from source..." "textPayload": "Calling back url https://workflowexecutions.googleapis.com/v1/projects/..." "textPayload": "Started waiting 1hr for an event from source..."
Verifique o status da última tentativa de execução:
gcloud workflows executions wait-last
O resultado será semelhante a este:
Using cached execution name: projects/1085953646031/locations/us-central1/workflows/callback-event-sample/executions/79929e4e-82c1-4da1-b068-f828034c01b7 Waiting for execution [79929e4e-82c1-4da1-b068-f828034c01b7] to complete...done. [...] state: SUCCEEDED
Limpar
Se você criou um novo projeto para este tutorial, exclua o projeto. Se você usou um projeto atual e quer mantê-lo sem as alterações incluídas neste tutorial, exclua os recursos criados para o tutorial.
Exclua o projeto
O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o tutorial.
Para excluir o projeto:
- No Console do Google Cloud, acesse a página Gerenciar recursos.
- Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
- Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.
Excluir recursos criados neste tutorial
A seguir
- Faça o tutorial Criar um fluxo de trabalho human-in-the-loop usando callbacks.