Aguarde eventos através de chamadas de retorno e acionadores do Eventarc

O fluxo de trabalho pode ter de aguardar um processo externo. Pode usar callbacks HTTP para aguardar que outro serviço faça um pedido a um ponto final de callback. Esse pedido retoma a execução do fluxo de trabalho. Também pode aguardar através da sondagem.

Em vez de usar a sondagem, este tutorial demonstra como pode aguardar eventos ou mensagens do Pub/Sub usando callbacks HTTP e acionadores do Eventarc. Embora possa acionar um fluxo de trabalho com eventos ou mensagens Pub/Sub, pode querer 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 tem de aguardar outro evento que indique que o processo está concluído. Pode implementar esta situação fazendo com que um fluxo de trabalho chame outro fluxo de trabalho.

Crie uma base de dados do Firestore

O Firestore armazena os seus dados em documentos que contêm campos mapeados para valores. Estes documentos são armazenados em coleções, que são contentores para os seus documentos que pode usar para organizar os seus dados e criar consultas. Saiba mais sobre o Firestore.

Tenha em atenção que cada Google Cloud projeto está limitado a uma base de dados do Firestore. Conclua os passos seguintes se precisar de criar uma nova base de dados.

Consola

  1. Na Google Cloud consola, aceda à página do Firestore Começar.

    Aceder a Começar

  2. Clique em Selecionar modo nativo.

    Para orientações sobre a seleção de um modo de base de dados e uma comparação detalhada das funcionalidades, consulte o artigo Escolher entre o modo nativo e o modo Datastore.

  3. Na lista Selecionar uma localização, selecione nam5 (Estados Unidos).

    A localização aplica-se à base de dados do Firestore e à aplicação do App Engine no seu Google Cloud projeto. Depois de criar a base de dados, não pode alterar a localização.

  4. Clique em Criar base de dados.

gcloud

Para criar uma base de dados do Firestore, primeiro tem de criar uma aplicação do App Engine e, em seguida, executar o comando gcloud firestore databases create:

gcloud app create --region=us-central
gcloud firestore databases create --region=us-central

Pode ignorar o aviso us-central is not a valid Firestore location. O App Engine e o Firestore suportam as mesmas localizações, mas a região us-central (Iowa) do App Engine é mapeada para a multirregião nam5 (Estados Unidos) do Firestore.

Crie um tópico do Pub/Sub

Este tutorial usa o Pub/Sub como uma origem de eventos. Crie um tópico do Pub/Sub para poder publicar uma mensagem no mesmo. Saiba mais sobre como criar e gerir tópicos.

Consola

  1. Na Google Cloud consola, aceda à página Tópicos do Pub/Sub.

    Aceda a Tópicos

  2. Clique em Criar tópico.

  3. No campo ID do tópico, introduza topic-callback.

  4. Aceite as outras predefinições.

  5. Clique em Criar tópico.

gcloud

Para criar um tópico, execute o comando gcloud pubsub topics create:

gcloud pubsub topics create topic-callback

Crie um contentor do Cloud Storage

Este tutorial usa o Cloud Storage como uma origem de eventos. Crie um contentor do Cloud Storage para poder carregar um ficheiro para o mesmo. Saiba como criar contentores de armazenamento.

Consola

  1. Na Google Cloud consola, aceda à página Recipientes do Cloud Storage.

    Aceda ao Cloud Storage

  2. Clique em Criar.

  3. Para o Nome do seu contentor, introduza PROJECT_ID-bucket-callback.

    O ID do projeto é usado no fluxo de trabalho callback-event-sample para identificar o contentor.

  4. Clique em Continuar.

  5. Para Tipo de localização, selecione Região e, de seguida, selecione us-central1 (Iowa).

  6. Aceite as outras predefinições.

  7. Clique em Criar.

gcloud

Para criar um contentor, 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 contentor.

Depois de criar as origens de eventos, pode implementar o fluxo de trabalho do recetor de eventos.

Implemente um fluxo de trabalho que ouve eventos

O fluxo de trabalho callback-event-listener é acionado quando uma mensagem é publicada num tópico do Pub/Sub ou quando um ficheiro é carregado para um contentor do Cloud Storage. O fluxo de trabalho recebe o evento, obtém os detalhes de chamada de retorno adequados da base de dados do Firestore e, em seguida, envia um pedido HTTP para o ponto final de chamada de retorno.

Consola

  1. Na Google Cloud consola, aceda à página Fluxos de trabalho:

    Aceda a Fluxos de trabalho

  2. Clique em Criar.

  3. Introduza um nome para o novo fluxo de trabalho: callback-event-listener.

  4. Na lista Região, selecione us-central1.

  5. Selecione a conta de serviço que criou anteriormente.

  6. Clicar em Seguinte.

  7. No editor de fluxos de trabalho, introduza a seguinte definição para o seu fluxo de trabalho:

    main:
  params: [event]
  steps:
    - log_event:
        call: sys.log
        args:
          text: ${event}
          severity: INFO
    - init:
        assign:
          - database_root: ${"projects/" + sys.get_env("GOOGLE_CLOUD_PROJECT_ID") + "/databases/(default)/documents/callbacks/"}
          - event_source_tokens: ${text.split(event.source, "/")}
          - event_source_len: ${len(event_source_tokens)}
          - event_source: ${event_source_tokens[event_source_len - 1]}
          - doc_name: ${database_root + event_source}
    - get_document_for_event_source:
        try:
          call: googleapis.firestore.v1.projects.databases.documents.get
          args:
            name: ${doc_name}
          result: document
        except:
            as: e
            steps:
                - known_errors:
                    switch:
                    - condition: ${e.code == 404}
                      return: ${"No callbacks for event source " + event_source}
                - unhandled_exception:
                    raise: ${e}
    - process_callback_urls:
        steps:
          - check_fields_exist:
              switch:
              - condition: ${not("fields" in document)}
                return: ${"No callbacks for event source " + event_source}
              - condition: true
                next: processFields
          - processFields:
              for:
                  value: key
                  in: ${keys(document.fields)}
                  steps:
                      - extract_callback_url:
                          assign:
                              - callback_url: ${document.fields[key]["stringValue"]}
                      - log_callback_url:
                          call: sys.log
                          args:
                            text: ${"Calling back url " + callback_url}
                            severity: INFO
                      - http_post:
                          call: http.post
                          args:
                              url: ${callback_url}
                              auth:
                                  type: OAuth2
                              body:
                                  event: ${event}

  8. Clique em Implementar.

gcloud

  1. Crie um ficheiro de código-fonte para o seu fluxo de trabalho:

    touch callback-event-listener.yaml

  2. Num editor de texto, copie o seguinte fluxo de trabalho para o ficheiro de código-fonte:

    main:
  params: [event]
  steps:
    - log_event:
        call: sys.log
        args:
          text: ${event}
          severity: INFO
    - init:
        assign:
          - database_root: ${"projects/" + sys.get_env("GOOGLE_CLOUD_PROJECT_ID") + "/databases/(default)/documents/callbacks/"}
          - event_source_tokens: ${text.split(event.source, "/")}
          - event_source_len: ${len(event_source_tokens)}
          - event_source: ${event_source_tokens[event_source_len - 1]}
          - doc_name: ${database_root + event_source}
    - get_document_for_event_source:
        try:
          call: googleapis.firestore.v1.projects.databases.documents.get
          args:
            name: ${doc_name}
          result: document
        except:
            as: e
            steps:
                - known_errors:
                    switch:
                    - condition: ${e.code == 404}
                      return: ${"No callbacks for event source " + event_source}
                - unhandled_exception:
                    raise: ${e}
    - process_callback_urls:
        steps:
          - check_fields_exist:
              switch:
              - condition: ${not("fields" in document)}
                return: ${"No callbacks for event source " + event_source}
              - condition: true
                next: processFields
          - processFields:
              for:
                  value: key
                  in: ${keys(document.fields)}
                  steps:
                      - extract_callback_url:
                          assign:
                              - callback_url: ${document.fields[key]["stringValue"]}
                      - log_callback_url:
                          call: sys.log
                          args:
                            text: ${"Calling back url " + callback_url}
                            severity: INFO
                      - http_post:
                          call: http.post
                          args:
                              url: ${callback_url}
                              auth:
                                  type: OAuth2
                              body:
                                  event: ${event}

  3. Implemente o fluxo de trabalho introduzindo 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 criou anteriormente.

Implemente um fluxo de trabalho que aguarda eventos

O fluxo de trabalho callback-event-sample armazena os detalhes de retorno de chamada numa base de dados do Firestore, interrompe a respetiva execução e, em seguida, aguarda a ocorrência de eventos específicos.

Consola

  1. Na Google Cloud consola, aceda à página Fluxos de trabalho:

    Aceda a Fluxos de trabalho

  2. Clique em Criar.

  3. Introduza um nome para o novo fluxo de trabalho: callback-event-sample.

  4. Na lista Região, selecione us-central1.

  5. Selecione a conta de serviço que criou anteriormente.

  6. Clicar em Seguinte.

  7. No editor de fluxos de trabalho, introduza a seguinte definição para o seu fluxo de trabalho:

    main:
  steps:
    - init:
        assign:
          - pubsub_topic: topic-callback
          - storage_bucket: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID") + "-bucket-callback"}
    - await_pubsub_message:
        call: await_callback_event
        args:
          event_source: ${pubsub_topic}
        result: pubsub_event
    - await_storage_bucket:
        call: await_callback_event
        args:
          event_source: ${storage_bucket}
        result: storage_event
    - return_events:
        return:
            pubsub_event: ${pubsub_event}
            storage_event: ${storage_event}

await_callback_event:
    params: [event_source]
    steps:
        - init:
            assign:
              - database_root: ${"projects/" + sys.get_env("GOOGLE_CLOUD_PROJECT_ID") + "/databases/(default)/documents/callbacks/"}
              - doc_name: ${database_root + event_source}
              - execution_id: ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_EXECUTION_ID")}
              - firestore_key: ${"exec_" + text.split(execution_id, "-")[0]}
        - create_callback:
            call: events.create_callback_endpoint
            args:
              http_callback_method: POST
            result: callback_details
        - save_callback_url:
            call: googleapis.firestore.v1.projects.databases.documents.patch
            args:
              name: ${doc_name}
              updateMask:
                fieldPaths: ["${firestore_key}"]
              body:
                fields:
                  ${firestore_key}:
                    stringValue: ${callback_details.url}
        - log_and_await_callback:
            try:
              steps:
                - log_await_start:
                    call: sys.log
                    args:
                      severity: INFO
                      data: ${"Started waiting 1hr for an event from source " + event_source}
                - await_callback:
                    call: events.await_callback
                    args:
                      callback: ${callback_details}
                      timeout: 3600
                    result: callback_request
                - log_await_stop:
                    call: sys.log
                    args:
                      severity: INFO
                      data: ${"Stopped waiting for an event from source " + event_source}
            except:
                as: e
                steps:
                    - log_error:
                        call: sys.log
                        args:
                            severity: "ERROR"
                            text: ${"Received error " + e.message}
        - delete_callback_url:
            call: googleapis.firestore.v1.projects.databases.documents.patch
            args:
              name: ${doc_name}
              updateMask:
                fieldPaths: ["${firestore_key}"]
        - check_null_event:
            switch:
              - condition: ${callback_request == null}
                return: null
        - log_await_result:
            call: sys.log
            args:
              severity: INFO
              data: ${callback_request.http_request.body.event}
        - return_event:
            return: ${callback_request.http_request.body.event}

  8. Clique em Implementar.

gcloud

  1. Crie um ficheiro de código-fonte para o seu fluxo de trabalho:

    touch callback-event-sample.yaml

  2. Num editor de texto, copie o seguinte fluxo de trabalho para o ficheiro de código-fonte:

    main:
  steps:
    - init:
        assign:
          - pubsub_topic: topic-callback
          - storage_bucket: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID") + "-bucket-callback"}
    - await_pubsub_message:
        call: await_callback_event
        args:
          event_source: ${pubsub_topic}
        result: pubsub_event
    - await_storage_bucket:
        call: await_callback_event
        args:
          event_source: ${storage_bucket}
        result: storage_event
    - return_events:
        return:
            pubsub_event: ${pubsub_event}
            storage_event: ${storage_event}

await_callback_event:
    params: [event_source]
    steps:
        - init:
            assign:
              - database_root: ${"projects/" + sys.get_env("GOOGLE_CLOUD_PROJECT_ID") + "/databases/(default)/documents/callbacks/"}
              - doc_name: ${database_root + event_source}
              - execution_id: ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_EXECUTION_ID")}
              - firestore_key: ${"exec_" + text.split(execution_id, "-")[0]}
        - create_callback:
            call: events.create_callback_endpoint
            args:
              http_callback_method: POST
            result: callback_details
        - save_callback_url:
            call: googleapis.firestore.v1.projects.databases.documents.patch
            args:
              name: ${doc_name}
              updateMask:
                fieldPaths: ["${firestore_key}"]
              body:
                fields:
                  ${firestore_key}:
                    stringValue: ${callback_details.url}
        - log_and_await_callback:
            try:
              steps:
                - log_await_start:
                    call: sys.log
                    args:
                      severity: INFO
                      data: ${"Started waiting 1hr for an event from source " + event_source}
                - await_callback:
                    call: events.await_callback
                    args:
                      callback: ${callback_details}
                      timeout: 3600
                    result: callback_request
                - log_await_stop:
                    call: sys.log
                    args:
                      severity: INFO
                      data: ${"Stopped waiting for an event from source " + event_source}
            except:
                as: e
                steps:
                    - log_error:
                        call: sys.log
                        args:
                            severity: "ERROR"
                            text: ${"Received error " + e.message}
        - delete_callback_url:
            call: googleapis.firestore.v1.projects.databases.documents.patch
            args:
              name: ${doc_name}
              updateMask:
                fieldPaths: ["${firestore_key}"]
        - check_null_event:
            switch:
              - condition: ${callback_request == null}
                return: null
        - log_await_result:
            call: sys.log
            args:
              severity: INFO
              data: ${callback_request.http_request.body.event}
        - return_event:
            return: ${callback_request.http_request.body.event}

  3. Implemente o fluxo de trabalho introduzindo 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 criou anteriormente.

Crie um acionador do Eventarc para encaminhar eventos do Pub/Sub

Um acionador do Eventarc permite-lhe encaminhar eventos especificando filtros para o acionador, incluindo a origem do evento e o fluxo de trabalho de destino. Crie um acionador do Eventarc para executar o fluxo de trabalho callback-event-listener como resultado da publicação de uma mensagem num tópico do Pub/Sub. Saiba mais sobre como acionar um fluxo de trabalho.

Consola

  1. Na Google Cloud consola, aceda à página Eventarc.

    Aceda ao Eventarc

  2. Clique em Criar acionador.

  3. Escreva um Nome do acionador.

    Por exemplo, trigger-pubsub-events-listener.

  4. Na lista Fornecedor de eventos, selecione Cloud Pub/Sub.

  5. Na lista Evento, em Personalizado, selecione google.cloud.pubsub.topic.v1.messagePublished.

  6. Na lista Selecionar um tópico do Cloud Pub/Sub, selecione o tópico que criou anteriormente.

  7. Na lista Região, selecione us-central1 (Iowa).

  8. Se lhe for pedido, conceda a função iam.serviceAccountTokenCreator à conta de serviço do Pub/Sub.

  9. Selecione a conta de serviço que criou anteriormente.

  10. Na lista Destino do evento, selecione Fluxos de trabalho.

  11. Na lista Selecionar um fluxo de trabalho, selecione o fluxo de trabalho callback-event-listener.

  12. Clique em Criar.

gcloud

Para criar um acionador, 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 tempo de execução. Tenha em atenção que o novo acionador pode demorar até 2 minutos a ficar ativo.

Crie um acionador do Eventarc para encaminhar eventos do Cloud Storage

Um acionador do Eventarc permite-lhe encaminhar eventos especificando filtros para o acionador, incluindo a origem do evento e o fluxo de trabalho de destino. Crie um acionador do Eventarc para executar o fluxo de trabalho callback-event-listener como resultado do carregamento de um ficheiro para um contentor do Cloud Storage. Saiba mais sobre como acionar um fluxo de trabalho.

Consola

  1. Na Google Cloud consola, aceda à página Eventarc.

    Aceda ao Eventarc

  2. Clique em Criar acionador.

  3. Escreva um Nome do acionador.

    Por exemplo, trigger-storage-events-listener.

  4. Na lista Fornecedor de eventos, selecione Cloud Storage.

  5. Na lista Evento, em Direto, selecione google.cloud.storage.object.v1.finalized.

  6. Na lista Recipiente, procure o recipiente que criou anteriormente e selecione-o.

  7. Na lista Região, com base no seu contentor do Cloud Storage, aceite o valor predefinido de us-central1 (Iowa).

  8. Se lhe for pedido, conceda a função iam.serviceAccountTokenCreator à conta de serviço do Pub/Sub.

  9. Selecione a conta de serviço que criou anteriormente.

  10. Na lista Destino do evento, selecione Fluxos de trabalho.

  11. Na lista Selecionar um fluxo de trabalho, selecione o fluxo de trabalho callback-event-listener.

  12. Clique em Criar.

gcloud

Para criar um acionador, 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 tempo de execução. Tenha em atenção que o novo acionador pode demorar até 2 minutos a ficar ativo.

Execute o fluxo de trabalho principal

A execução de um fluxo de trabalho executa a definição do fluxo de trabalho atual associada ao fluxo de trabalho. Execute o fluxo de trabalho callback-event-sample. Este é o fluxo de trabalho principal e aguarda que ocorram eventos específicos, retomando a execução apenas quando o fluxo de trabalho secundário faz os pedidos de callback adequados.

Consola

  1. Na Google Cloud consola, aceda à página Fluxos de trabalho.

    Aceda a Fluxos de trabalho

  2. Na página Fluxos de trabalho, clique no fluxo de trabalho callback-event-sample para aceder à respetiva página de detalhes.

  3. Na página Detalhes do fluxo de trabalho, clique em Executar.

  4. Clique novamente em Executar.

    A execução do fluxo de trabalho é iniciada. Enquanto a execução é realizada, deve ver um Estado de execução de Running e uma entrada de registo semelhante à seguinte: 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. Enquanto a execução é realizada, deve ver um estado de execução semelhante ao seguinte:

Waiting for execution [a848a164-268a-449c-b2fe-396f32f2ed66] to complete...working...

Gere eventos e verifique o estado de execução

Pode confirmar que os resultados são os esperados gerando eventos, vendo as entradas do registo e verificando o estado de execução do fluxo de trabalho.

Publicar uma mensagem

Publicar uma mensagem no tópico Pub/Sub que criou anteriormente.

Consola

  1. Na Google Cloud consola, aceda à página Tópicos do Pub/Sub.

    Aceda a Tópicos

  2. Clique em topic-callback.

  3. Clique no separador Mensagens.

  4. Clique em Publicar mensagem.

  5. No campo Corpo da mensagem, introduza Hello World.

  6. Clique em Publicar.

gcloud

Para publicar uma mensagem, use o comando gcloud pubsub topics publish:

gcloud pubsub topics publish topic-callback \
    --message="Hello World"

Carregue um objeto

Carregue um ficheiro para o contentor do Cloud Storage que criou anteriormente.

Consola

  1. Na Google Cloud consola, aceda à página Recipientes do Cloud Storage.

    Aceda a Recipientes

  2. Clique no nome do depósito que criou anteriormente.

  3. No separador Objetos, faça uma das seguintes ações:

    • Arraste e largue o ficheiro pretendido do ambiente de trabalho ou do gestor de ficheiros para o painel principal na Google Cloud consola.

    • Clique em Carregar ficheiros, selecione o ficheiro que quer carregar e, de seguida, clique em Abrir.

gcloud

Para carregar um ficheiro, execute o comando gcloud storage cp:

gcloud storage cp OBJECT_LOCATION gs://PROJECT_ID-bucket-callback/

Substitua OBJECT_LOCATION pelo caminho local para o seu objeto. Por exemplo, random.txt.

Veja entradas do registo e o estado de execução

Confirme que o fluxo de trabalho callback-event-sample foi concluído com êxito.

Consola

  1. Na Google Cloud consola, aceda à página Fluxos de trabalho.

    Aceda a Fluxos de trabalho

  2. Na página Fluxos de trabalho, clique no fluxo de trabalho callback-event-sample para aceder à respetiva página de detalhes.

  3. Na página Detalhes do fluxo de trabalho, para aceder aos detalhes de uma execução específica, clique no ID de execução adequado.

    O Estado de execução deve ser Succeeded e, no painel Output, deve ver os eventos do Pub/Sub e do Cloud Storage recebidos.

gcloud

  1. Filtre as entradas do registo e devolva o resultado no formato JSON:

    gcloud logging read "resource.type=workflows.googleapis.com/Workflow AND textPayload:calling OR textPayload:waiting" \
    --format=json

  2. Procure entradas de registo 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..."

  3. Verifique o estado da última tentativa de execução:

    gcloud workflows executions wait-last

    O resultado deve ser semelhante ao seguinte:

    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