Execute um fluxo de trabalho

A execução de um fluxo de trabalho executa a definição do fluxo de trabalho atual associada ao fluxo de trabalho.

Pode transmitir argumentos de tempo de execução num pedido de execução de fluxo de trabalho e aceder a esses argumentos através de uma variável de fluxo de trabalho. Para mais informações, consulte o artigo Transmita argumentos de tempo de execução num pedido de execução.

Após a conclusão da execução de um fluxo de trabalho, o respetivo histórico e resultados são retidos durante um período limitado. Para mais informações, consulte o artigo Quotas e limites.

Antes de começar

As restrições de segurança definidas pela sua organização podem impedir a conclusão dos seguintes passos. Para informações de resolução de problemas, consulte o artigo Desenvolva aplicações num ambiente Google Cloud restrito.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Se um fluxo de trabalho aceder a outros Google Cloud recursos, certifique-se de que está associado a uma conta de serviço que tenha as autorizações corretas para o fazer. Para saber que conta de serviço está associada a um fluxo de trabalho existente, consulte o artigo Verifique a conta de serviço associada de um fluxo de trabalho.

   Tenha em atenção que, para criar um recurso e anexar uma conta de serviço, precisa de autorizações para criar esse recurso e para usar a identidade da conta de serviço que vai anexar ao recurso. Para mais informações, consulte o artigo Autorizações da conta de serviço.

2. Implemente um fluxo de trabalho através da Google Cloud consola ou da CLI do Google Cloud.
Nota: para enviar registos para o Cloud Logging, certifique-se de que à conta de serviço que executa o fluxo de trabalho foi atribuída uma função que inclui a autorização logging.logEntries.create (por exemplo, a função Logs Writer).

Execute um fluxo de trabalho

Pode executar um fluxo de trabalho das seguintes formas:

• Na consola Google Cloud
• Usando a Google Cloud CLI no seu terminal ou no Cloud Shell
• Enviando um pedido direto para a API Workflows

Também pode executar um fluxo de trabalho através das bibliotecas cliente da Google Cloud. Para mais informações, consulte o artigo Execute um fluxo de trabalho com as bibliotecas de cliente da Google Cloud.

Consola

1. Para executar um fluxo de trabalho, na Google Cloud consola, aceda à página Fluxos de trabalho:

   Aceda a Fluxos de trabalho

2. Na página Fluxos de trabalho, selecione um fluxo de trabalho para aceder à respetiva página de detalhes.

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

4. Na página Executar fluxo de trabalho, no painel Entrada, pode introduzir argumentos de tempo de execução opcionais para transmitir ao fluxo de trabalho antes da execução. Os argumentos têm de estar no formato JSON. Por exemplo, {"animal":"cat"}. Se o seu fluxo de trabalho não usar argumentos de tempo de execução, deixe este campo em branco.

5. Opcionalmente, especifique o nível de registo de chamadas que quer aplicar à execução do fluxo de trabalho. Na lista Nível do registo de chamadas selecione uma das seguintes opções:

   • Não especificado: não é especificado nenhum nível de registo. Esta é a predefinição. Um nível de registo de execução tem precedência sobre qualquer nível de registo do fluxo de trabalho, a menos que o nível de registo de execução não seja especificado (predefinição). Nesse caso, aplica-se o nível de registo do fluxo de trabalho.
   • Apenas erros: registe todas as exceções capturadas ou quando uma chamada é interrompida devido a uma exceção.
   • Todas as chamadas: registe todas as chamadas para subfluxos de trabalho ou funções da biblioteca e os respetivos resultados.
   • Sem registos: sem registo de chamadas.

6. Opcionalmente, especifique o nível do histórico de execução que quer aplicar à execução do fluxo de trabalho. Na lista Histórico de execução, selecione uma das seguintes opções:

   • Herdar do fluxo de trabalho: aplique a definição do histórico de execução do fluxo de trabalho. Esta é a predefinição.
   • Básico: ative o histórico de execução básico.
   • Detalhado: ative o histórico de execução detalhado, incluindo todos os valores das variáveis no âmbito e o número esperado de iterações.

7. Clique em Executar.

8. Na página Detalhes da execução, pode ver os resultados da execução, incluindo qualquer resultado, o ID e o estado da execução, bem como o passo atual ou final da execução do fluxo de trabalho. Para mais informações, consulte Aceda aos resultados da execução do fluxo de trabalho.

   Nota: para aceder à página Detalhes de execução, tem de ter uma função que contenha as autorizações workflows.workflows.get, workflows.executions.get e workflows.stepEntries.list. Para mais informações, consulte os artigos Funções e autorizações dos fluxos de trabalho e Faça a gestão do acesso.

gcloud

1. Abra um terminal.

2. Encontre o nome do fluxo de trabalho que quer executar. Se não souber o nome do fluxo de trabalho, pode introduzir o seguinte comando para apresentar uma lista de todos os seus fluxos de trabalho:

   gcloud workflows list

3. Pode executar o fluxo de trabalho através do comando gcloud workflows run ou do comando gcloud workflows execute:

   • Execute o fluxo de trabalho e aguarde pela conclusão da execução:

     gcloud workflows run WORKFLOW_NAME \
         --call-log-level=CALL_LOGGING_LEVEL \
         --execution-history-level="EXECUTION_HISTORY_LEVEL" \
         --data=DATA

   • Execute o fluxo de trabalho sem aguardar que a tentativa de execução termine:

     gcloud workflows execute WORKFLOW_NAME \
         --call-log-level=CALL_LOGGING_LEVEL \
         --execution-history-level="EXECUTION_HISTORY_LEVEL" \
         --data=DATA

     Substitua o seguinte:

     • WORKFLOW_NAME: o nome do fluxo de trabalho.

     • CALL_LOGGING_LEVEL (opcional): nível de registo de chamadas a aplicar durante a execução. Pode ser um dos seguintes:

       • none: não é especificado nenhum nível de registo. Esta é a predefinição. Um nível de registo de execução tem precedência sobre qualquer nível de registo do fluxo de trabalho, a menos que o nível de registo de execução não esteja especificado (predefinição). Nesse caso, aplica-se o nível de registo do fluxo de trabalho.
       • log-errors-only: registar todas as exceções capturadas; ou quando uma chamada é parada devido a uma exceção.
       • log-all-calls: registar todas as chamadas para subfluxos de trabalho ou funções de biblioteca e os respetivos resultados.
       • log-none: registo de chamadas inexistente.

     • EXECUTION_HISTORY_LEVEL (opcional): nível do histórico de execuções a aplicar durante a execução. Pode ser um dos seguintes:

       • none: não é especificado nenhum nível do histórico de execuções. Esta é a predefinição. Se não for especificado um nível do histórico de execução para uma execução, este é determinado pelo nível aplicado ao fluxo de trabalho. Se os níveis forem diferentes, a definição aplicada ao nível da execução substitui a definição aplicada ao nível do fluxo de trabalho para esta execução.
       • execution-history-basic: ativar o histórico de execuções básico.
       • execution-history-detailed: ative o histórico de execução detalhado, incluindo todos os valores das variáveis no âmbito e o número esperado de iterações.

     • DATA (opcional): argumentos de tempo de execução para o seu fluxo de trabalho no formato JSON.

4. Se executou gcloud workflows execute, é devolvido o ID exclusivo da tentativa de execução do fluxo de trabalho, e o resultado é semelhante ao seguinte:

    To view the workflow status, you can use following command:
    gcloud workflows executions describe b113b589-8eff-4968-b830-8d35696f0b33 --workflow workflow-2 --location us-central1

   Para ver o estado da execução, introduza o comando devolvido pelo passo anterior.

Se a tentativa de execução for bem-sucedida, o resultado é semelhante ao seguinte, com um state a indicar o êxito do fluxo de trabalho e um status que especifica o passo final do fluxo de trabalho da execução.

argument: '{"searchTerm":"Friday"}'
endTime: '2022-06-22T12:17:53.086073678Z'
name: projects/1051295516635/locations/us-central1/workflows/myFirstWorkflow/executions/c4dffd1f-13db-46a0-8a4a-ee39c144cb96
result: '["Friday","Friday the 13th (franchise)","Friday Night Lights (TV series)","Friday
    the 13th (1980 film)","Friday the 13th","Friday the 13th (2009 film)","Friday the
    13th Part III","Friday the 13th Part 2","Friday (Rebecca Black song)","Friday Night
    Lights (film)"]'
startTime: '2022-06-22T12:17:52.799387653Z'
state: SUCCEEDED
status:
    currentSteps:
    - routine: main
        step: returnOutput
workflowRevisionId: 000001-ac2

API REST

Para criar uma nova execução com a revisão mais recente de um determinado fluxo de trabalho, use o método projects.locations.workflows.executions.create.

Nota: para autenticar, precisa de uma conta de serviço com privilégios suficientes para executar o fluxo de trabalho. Por exemplo, pode conceder a uma conta de serviço a função Workflows Invoker (roles/workflows.invoker) para que a conta tenha autorização para acionar a execução do fluxo de trabalho. Para mais informações, consulte o artigo Invocar fluxos de trabalho.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

• PROJECT_NUMBER: o número do seu Google Cloud projeto indicado na página IAM e administrador Definições.
• LOCATION: a região na qual o fluxo de trabalho é implementado, por exemplo, us-central1.
• WORKFLOW_NAME: o nome definido pelo utilizador para o fluxo de trabalho, por exemplo, myFirstWorkflow.
• PARAMETER: opcional. Se o fluxo de trabalho que está a executar puder receber argumentos de tempo de execução que lhe transmite como parte de um pedido de execução, pode adicionar ao corpo do pedido uma string formatada em JSON cujo valor seja um ou mais pares de chave-valor com carateres de escape, por exemplo, "{\"searchTerm\":\"asia\"}".
• VALUE: opcional. O valor de um par parâmetro-valor que o fluxo de trabalho pode receber como um argumento de tempo de execução.
• CALL_LOGGING_LEVEL: opcional. O nível de registo de chamadas a aplicar durante a execução. Por predefinição, não é especificado nenhum nível de registo e, em alternativa, é aplicado o nível de registo do fluxo de trabalho. Para mais informações, consulte o artigo Envie registos para o registo. Uma das seguintes opções:
  • CALL_LOG_LEVEL_UNSPECIFIED: não é especificado nenhum nível de registo e, em alternativa, é aplicado o nível de registo do fluxo de trabalho. Esta é a predefinição. Caso contrário, aplica-se o nível de registo de execução e tem precedência sobre o nível de registo do fluxo de trabalho.
  • LOG_ERRORS_ONLY: registar todas as exceções capturadas; ou quando uma chamada é parada devido a uma exceção.
  • LOG_ALL_CALLS: registar todas as chamadas para subfluxos de trabalho ou funções da biblioteca e os respetivos resultados.
  • LOG_NONE: registo de chamadas inexistente.
• BACKLOG_EXECUTION: opcional. Se for definida como true, a execução não é acumulada quando a quota de concorrência se esgota. Para mais informações, consulte o artigo Faça a gestão do atraso na execução.
• EXECUTION_HISTORY_LEVEL: opcional. O nível do histórico de execuções a aplicar durante a execução. Para mais informações, consulte a secção Ver histórico dos passos de execução. Uma das seguintes opções:
  • EXECUTION_HISTORY_LEVEL_UNSPECIFIED: não foi especificado nenhum nível do histórico de execuções. Esta é a predefinição. Se não for especificado um nível do histórico de execução para uma execução, este é determinado pelo nível aplicado ao fluxo de trabalho. Se os níveis forem diferentes, a definição aplicada ao nível da execução substitui a definição aplicada ao nível do fluxo de trabalho para esta execução.
  • EXECUTION_HISTORY_BASIC: ativar o histórico de execuções básico.
  • EXECUTION_HISTORY_ADVANCED: ativar o histórico de execução detalhado incluindo todos os valores das variáveis no âmbito e o número esperado de iterações.

Corpo JSON do pedido:

{
  "argument": "{\"PARAMETER\":\"VALUE\"}",
  "callLogLevel": "CALL_LOGGING_LEVEL",
  "disableConcurrencyQuotaOverflowBuffering": "BACKLOG_EXECUTION",
  "executionHistoryLevel": "EXECUTION_HISTORY_LEVEL"
}

Para enviar o seu pedido, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual:

cat > request.json << 'EOF'
{
  "argument": "{\"PARAMETER\":\"VALUE\"}",
  "callLogLevel": "CALL_LOGGING_LEVEL",
  "disableConcurrencyQuotaOverflowBuffering": "BACKLOG_EXECUTION",
  "executionHistoryLevel": "EXECUTION_HISTORY_LEVEL"
}
EOF

Em seguida, execute o seguinte comando para enviar o seu pedido REST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://workflowexecutions.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/workflows/WORKFLOW_NAME/executions"

PowerShell (Windows)

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual:

@'
{
  "argument": "{\"PARAMETER\":\"VALUE\"}",
  "callLogLevel": "CALL_LOGGING_LEVEL",
  "disableConcurrencyQuotaOverflowBuffering": "BACKLOG_EXECUTION",
  "executionHistoryLevel": "EXECUTION_HISTORY_LEVEL"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Em seguida, execute o seguinte comando para enviar o seu pedido REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://workflowexecutions.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/workflows/WORKFLOW_NAME/executions" | Select-Object -Expand Content

Explorador de APIs (navegador)

Copie o corpo do pedido e abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Cole o corpo do pedido nesta ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

Se for bem-sucedido, o corpo da resposta contém uma instância recém-criada de Execution:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/workflows/WORKFLOW_NAME/executions/EXECUTION_ID",
  "startTime": "2023-11-07T14:35:27.215337069Z",
  "state": "ACTIVE",
  "argument": "{\"PARAMETER\":\"VALUE\"}",
  "workflowRevisionId": "000001-2df",
  "callLogLevel": "CALL_LOGGING_LEVEL",
  "executionHistoryLevel": "EXECUTION_HISTORY_LEVEL",
  "status": {}
}

Verifique o estado das execuções

Existem vários comandos que ajudam a verificar o estado de uma execução do fluxo de trabalho.

• Para obter uma lista das tentativas de execução de um fluxo de trabalho e os respetivos IDs, introduza o seguinte comando:

  gcloud workflows executions list WORKFLOW_NAME

  Substitua WORKFLOW_NAME pelo nome do fluxo de trabalho.

  O comando devolve um valor NAME semelhante ao seguinte:

  projects/PROJECT_NUMBER/locations/REGION/workflows/WORKFLOW_NAME/executions/EXECUTION_ID

  Copie o ID de execução para usar no comando seguinte.

• Para verificar o estado de uma tentativa de execução e aguardar que a tentativa termine, introduza o seguinte comando:

  gcloud workflows executions wait EXECUTION_ID

  Substitua EXECUTION_ID pelo ID da tentativa de execução.

  O comando aguarda a conclusão da tentativa de execução e, em seguida, devolve os resultados.

• Para aguardar até que a última execução esteja concluída e, em seguida, devolver o resultado da execução concluída, introduza o seguinte comando:

  gcloud workflows executions wait-last

  Se fez uma tentativa de execução anterior na mesma sessão de gcloud, o comando aguarda que a tentativa de execução anterior termine e, em seguida, devolve os resultados da execução concluída. Se não existir nenhuma tentativa anterior, gcloud devolve o seguinte erro:

  ERROR: (gcloud.workflows.executions.wait-last) [NOT FOUND] There are no cached executions available.
  

• Para obter o estado da última execução, introduza o seguinte comando:

  gcloud workflows executions describe-last

  Se fez uma tentativa de execução anterior na mesma sessão gcloud, o comando devolve os resultados da última execução, mesmo que esteja em execução. Se não existir nenhuma tentativa anterior, gcloud devolve o seguinte erro:

  ERROR: (gcloud.beta.workflows.executions.describe-last) [NOT FOUND] There are no cached executions available.
  

Filtrar execuções

Pode aplicar filtros à lista de execuções do fluxo de trabalho devolvidas pelo método workflows.executions.list.

Pode filtrar pelos seguintes campos:

• createTime
• disableOverflowBuffering
• duration
• endTime
• executionId
• label
• startTime
• state
• stepName
• workflowRevisionId

Por exemplo, para filtrar por uma etiqueta (labels."fruit":"apple"), pode fazer um pedido de API semelhante ao seguinte:

GET https://workflowexecutions.googleapis.com/v1/projects/MY_PROJECT/locations/MY_LOCATION/workflows/MY_WORKFLOW/executions?view=full&filter=labels.%22fruit%22%3A%22apple%22"

Onde:

• view=full especifica uma vista que define os campos que devem ser preenchidos nas execuções devolvidas; neste caso, todos os dados
• labels.%22fruit%22%3A%22apple%22é a sintaxe de filtro codificada por URL

Para mais informações, consulte o artigo Filtragem AIP-160.

Faça a gestão do atraso na execução

Pode usar o processamento pendente de execuções para evitar novas tentativas do lado do cliente, remover atrasos na execução e maximizar o débito. As execuções pendentes são executadas automaticamente assim que a quota de concorrência de execução fica disponível.

Prática recomendada: se a execução dos fluxos de trabalho estiver sujeita a restrições de tempo ou for sensível, não recomendamos o registo em atraso da execução e deve considerar desativar a funcionalidade.

Existe um número máximo de execuções de fluxo de trabalho ativas que podem ser executadas em simultâneo. Quando esta quota se esgota e se o registo em atraso de execuções estiver desativado ou se a quota de execuções em atraso for atingida, todas as novas execuções falham com um código de estado HTTP 429 Too many requests. Com o registo de pendências de execução ativado, as novas execuções são bem-sucedidas e são criadas no estado QUEUED. Assim que a quota de simultaneidade de execução fica disponível, as execuções são executadas automaticamente e entram num estado ACTIVE.

Por predefinição, o processamento pendente de execução está ativado para todos os pedidos (incluindo os acionados pelo Cloud Tasks), com as seguintes exceções:

• Quando cria uma execução com um conetor executions.run ou executions.create num fluxo de trabalho, o registo de execuções pendentes está desativado por predefinição. Pode configurá-lo definindo explicitamente o campo disableConcurrencyQuotaOverflowBuffering da execução como false.
• Para execuções acionadas pelo Pub/Sub, o registo de execuções pendentes está desativado e não pode ser configurado.

Tenha em conta o seguinte:

• As execuções em fila são iniciadas por ordem de chegada (FIFO), com base no melhor esforço.
• Um campo de data/hora createTime indica quando uma execução é criada. A indicação de tempo startTime indica quando uma execução é automaticamente removida da fila de tarefas pendentes e começa a ser executada. Para execuções que não estão em atraso, ambos os valores de data/hora são idênticos.
• O limite para execuções em atraso pode ser observado através da métrica de quota workflowexecutions.googleapis.com/executionbacklogentries. Para mais informações, consulte o artigo Veja e faça a gestão de quotas.

Desative o registo de pendências de execução

Pode desativar o registo em atraso da execução definindo uma flag quando usar a Google Cloud CLI. Por exemplo:

gcloud workflows execute WORKFLOW_NAME
    --disable-concurrency-quota-overflow-buffering

Em alternativa, pode desativar o registo em atraso de execuções definindo o campo disableConcurrencyQuotaOverflowBuffering como true no corpo JSON do pedido quando enviar um pedido de execução para a API REST Workflows. Por exemplo:

{
  "argument": {"arg1":"value1"},
  "callLogLevel": "LOG_NONE",
  "disableConcurrencyQuotaOverflowBuffering": true
}

Para mais informações, consulte o artigo Execute um fluxo de trabalho.

O que se segue?

• Aceda aos resultados da execução do fluxo de trabalho
• Controle a ordem de execução num fluxo de trabalho
• Envie registos de execução para o Cloud Logging
• Atualize um fluxo de trabalho existente