Executar um fluxo de trabalho

Quando um fluxo de trabalho é executado, a definição atual associada a ele também é.

É possível transmitir argumentos de ambiente de execução em uma solicitação de execução de fluxo de trabalho e acessá-los usando uma variável de fluxo de trabalho. Para mais informações, consulte Transmitir argumentos de ambiente de execução em uma solicitação de execução.

Depois que uma execução de fluxo de trabalho é concluída, o histórico e os resultados dela são retidos por um tempo limitado. Para mais informações, consulte Cotas e limites.

Antes de começar

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 de Google Cloud .

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

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

3. Make sure that billing is enabled for your Google Cloud project.

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

5. Make sure that billing is enabled for your Google Cloud project.

6. Se um fluxo de trabalho acessar outros recursos Google Cloud , verifique se ele está associado a uma conta de serviço com as permissões corretas. Para saber qual conta de serviço está associada a um fluxo de trabalho atual, consulte Verificar a conta de serviço associada a um fluxo de trabalho.

   Para criar um recurso e anexar uma conta de serviço, você precisa de permissões para criar esse recurso e se passar pela conta de serviço que você anexará ao recurso. Para mais informações, consulte Permissões da conta de serviço.

7. Implante um fluxo de trabalho usando o console do Google Cloud ou a CLI do Google Cloud.

Observação:para enviar registros ao Cloud Logging, verifique se a conta de serviço que executa o fluxo de trabalho recebeu um papel que inclua a permissão logging.logEntries.create, como o Logs Writer.

Executar um fluxo de trabalho

É possível executar um fluxo de trabalho das seguintes maneiras:

• No console do Google Cloud
• Usando a CLI do Google Cloud no terminal ou no Cloud Shell
• Enviando uma solicitação direta à API Workflows

Também é possível executar um fluxo de trabalho usando as bibliotecas de cliente do Cloud. Para mais informações, consulte Executar um fluxo de trabalho usando as bibliotecas de cliente do Cloud.

Console

1. Para executar um fluxo de trabalho, acesse a página Workflows no console do Google Cloud:

   Acessar fluxos de trabalho

2. Na página Fluxos de trabalho, selecione um fluxo para acessar a página de detalhes dele.

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

4. No painel Entrada da página Executar fluxo de trabalho, insira argumentos de ambiente de execução opcionais para transmitir ao fluxo de trabalho antes da execução. Os argumentos precisam estar no formato JSON, por exemplo, {"animal":"cat"}. Se o fluxo de trabalho não usa argumentos de ambiente de execução, deixe em branco.

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

   • Não especificado: nenhum nível de registro foi especificado. Esse é o padrão. Um nível de registro de execução tem precedência sobre qualquer nível de registro de fluxo de trabalho, a menos que o nível de registro de execução não seja especificado (o padrão). Nesse caso, o nível de registro de fluxo de trabalho é aplicado.
   • Somente erros: registra todas as exceções identificadas; ou quando uma chamada é interrompida devido a uma exceção.
   • Todas as chamadas: registre todas as chamadas para subfluxos de trabalho ou funções de biblioteca e os respectivos resultados.
   • Sem registros: nenhum registro de chamadas.

6. Se quiser, especifique o nível de histórico de execução que você quer aplicar à execução do fluxo de trabalho. Na lista Histórico de execução, selecione uma destas opções:

   • Herdar do fluxo de trabalho: aplique a configuração do histórico de execução do fluxo de trabalho. Esse é o padrão.
   • Básico: ativar o histórico de execução básico.
   • Detalhados: ative o histórico de execução detalhado, incluindo todos os valores de variáveis no escopo e o número esperado de iterações.

7. Clique em Executar.

8. Na página Detalhes da execução, você pode conferir os resultados da execução, incluindo qualquer saída, o ID e o estado da execução e a etapa atual ou final da execução do fluxo de trabalho. Para mais informações, consulte Acessar os resultados da execução do fluxo de trabalho.

   Observação:para acessar a página Detalhes da execução, você precisa ter um papel que contenha as permissões workflows.workflows.get, workflows.executions.get e workflows.stepEntries.list. Para mais informações, consulte Papéis e permissões do Workflows e Gerenciar acesso.

gcloud

1. Abra um terminal.

2. Encontre o nome do fluxo de trabalho que você quer executar. Se você não souber o nome dele, insira o seguinte comando para listar todos os fluxos de trabalho:

   gcloud workflows list

3. É possível executar o fluxo de trabalho usando o comando gcloud workflows run ou o comando gcloud workflows execute:

   • Executar o fluxo de trabalho e aguardar o fim da execução:

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

   • Executar o fluxo de trabalho sem aguardar o fim da execução:

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

     Substitua:

     • WORKFLOW_NAME: o nome do fluxo de trabalho.

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

       • none: nenhum nível de registro foi especificado. Esse é o padrão. Um nível de registro de execução tem precedência sobre qualquer nível de registro de fluxo de trabalho, a menos que o nível de registro de execução não seja especificado (o padrão). Nesse caso, o nível de registro de fluxo de trabalho é aplicado.
       • log-errors-only: registra todas as exceções identificadas. ou quando uma chamada é interrompida devido a uma exceção.
       • log-all-calls: registra todas as chamadas para subfluxos de trabalho ou funções de biblioteca e os resultados delas.
       • log-none: nenhum registro de chamadas.

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

       • none: nenhum nível do histórico de execução foi especificado. Esse é o padrão. Se um nível de histórico de execução não for especificado para uma execução, ele será determinado pelo nível aplicado ao fluxo de trabalho. Se os níveis forem diferentes, a configuração aplicada no nível de execução vai substituir a configuração aplicada no nível do fluxo de trabalho para essa execução.
       • execution-history-basic: ativa o histórico de execução básico.
       • execution-history-detailed: ative o histórico de execução detalhado, incluindo todos os valores de variáveis no escopo e o número esperado de iterações.

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

4. Se você executou gcloud workflows execute, o ID exclusivo da tentativa de execução do fluxo de trabalho é retornado e a saída é semelhante a esta:

    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 visualizar o status da execução, insira o comando retornado pela etapa anterior.

Se a tentativa de execução tiver êxito, a saída será semelhante a esta, com um state indicando o sucesso do fluxo de trabalho e um status que especifica a etapa 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 usando a revisão mais recente de um determinado fluxo de trabalho, use o método projects.locations.workflows.executions.create.

Observação: para autenticar, você vai precisar de uma conta de serviço com privilégios suficientes para executar o fluxo de trabalho. Por exemplo, você pode conceder a uma conta de serviço o papel de Invocador do Workflows (roles/workflows.invoker) para que ela tenha permissão para acionar a execução do fluxo de trabalho. Para mais informações, consulte Invocar fluxos de trabalho.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• PROJECT_NUMBER: o número do projeto Google Cloud listado na página Configurações do IAM e Admin.
• LOCATION: a região em que o fluxo de trabalho é implantado, por exemplo, us-central1.
• WORKFLOW_NAME: o nome definido pelo usuário para o fluxo de trabalho. Por exemplo, myFirstWorkflow.
• PARAMETER: opcional. Se o fluxo de trabalho que você está executando puder receber argumentos de execução que você transmita como parte de uma solicitação de execução, adicione ao corpo da solicitação uma string formatada em JSON cujo valor seja um ou mais pares de valor-parâmetro de escape, por exemplo, "{\"searchTerm\":\"asia\"}".
• VALUE: opcional. O valor de um par de 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 registro de chamadas a ser aplicado durante a execução. O padrão é que nenhum nível de registro seja especificado e que o nível de registro do fluxo de trabalho seja aplicado. Para mais informações, consulte Enviar registros para o Logging. Uma das seguintes opções:
  • CALL_LOG_LEVEL_UNSPECIFIED: nenhum nível de registro foi especificado, e o nível de registro do fluxo de trabalho é aplicado. Esse é o padrão. Caso contrário, o nível de registro de execução é aplicado e tem precedência sobre o nível de registro do fluxo de trabalho.
  • LOG_ERRORS_ONLY: registra todas as exceções identificadas. ou quando uma chamada é interrompida devido a uma exceção.
  • LOG_ALL_CALLS: registra todas as chamadas para subfluxos de trabalho ou funções de biblioteca e os resultados delas.
  • LOG_NONE: nenhum registro de chamadas.
• BACKLOG_EXECUTION: opcional. Se definido como true, a execução não será acumulada quando a cota de simultaneidade for esgotada. Para mais informações, consulte Gerenciar a defasagem de execução.
• EXECUTION_HISTORY_LEVEL: opcional. O nível do histórico de execução a ser aplicado durante a execução. Para mais informações, consulte Consultar o histórico das etapas de execução. Uma das seguintes:
  • EXECUTION_HISTORY_LEVEL_UNSPECIFIED: nenhum nível do histórico de execução foi especificado. Esse é o padrão. Se um nível de histórico de execução não for especificado para uma execução, ele será determinado pelo nível aplicado ao fluxo de trabalho. Se os níveis forem diferentes, a configuração aplicada no nível de execução vai substituir a configuração aplicada no nível do fluxo de trabalho para essa execução.
  • EXECUTION_HISTORY_BASIC: ativa o histórico de execução básico.
  • EXECUTION_HISTORY_ADVANCED: ative o histórico de execução detalhado, incluindo todos os valores de variáveis no escopo e o número esperado de iterações.

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

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

Depois execute o comando a seguir para enviar a solicitação 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)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo 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

Depois execute o comando a seguir para enviar a solicitação 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

APIs Explorer (navegador)

Copie o corpo da solicitação e abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

Se a solicitação for concluída, o corpo da resposta conterá uma instância 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": {}
}

Verificar o status das execuções

Há vários comandos para ajudar você a verificar o status de uma execução de fluxo de trabalho.

• Para recuperar uma lista das tentativas de execução de um fluxo de trabalho e os respectivos IDs, digite o seguinte comando:

  gcloud workflows executions list WORKFLOW_NAME

  Substitua WORKFLOW_NAME pelo nome do fluxo de trabalho.

  O comando retorna um valor NAME semelhante a este:

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

  Copie o ID de execução para usar no próximo comando.

• Para verificar o status de uma tentativa de execução e aguardar ela ser concluída, digite 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, retorna os resultados.

• Para aguardar a conclusão da última execução e retornar o resultado dela, digite o seguinte comando:

  gcloud workflows executions wait-last

  Se você fez uma tentativa de execução anterior na mesma sessão do gcloud, o comando aguarda a conclusão da tentativa de execução anterior e, em seguida, retorna os resultados da execução concluída. Se não houver nenhuma tentativa anterior, gcloud vai retornar o seguinte erro:

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

• Para conferir o status da última execução, digite o seguinte comando:

  gcloud workflows executions describe-last

  Se você fez uma tentativa de execução anterior na mesma sessão de gcloud, o comando retorna os resultados da última execução, mesmo que ela esteja em execução. Se não houver nenhuma tentativa anterior, o gcloud retornará o seguinte erro:

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

Execuções de filtro

É possível aplicar filtros à lista de execuções de fluxo de trabalho retornadas pelo método workflows.executions.list.

É possível filtrar pelos seguintes campos:

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

Por exemplo, para filtrar um rótulo (labels."fruit":"apple"), faça uma solicitação de API semelhante a esta:

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"

Em que:

• view=full especifica uma visualização que define quais campos devem ser preenchidos nas execuções retornadas. Nesse caso, todos os dados
• labels.%22fruit%22%3A%22apple%22 é a sintaxe do filtro codificado por URL

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

Gerenciar a fila de execução

É possível usar o backlogging de execução para evitar novas tentativas do lado do cliente, remover atrasos de execução e maximizar a taxa de transferência. As execuções pendentes são executadas automaticamente assim que a cota de simultaneidade de execução fica disponível.

Prática recomendada:se a execução das execuções do fluxo de trabalho tiver restrições de tempo ou for sensível, não recomendamos o backlogging de execução. Desative o recurso.

Há um número máximo de execuções de fluxo de trabalho ativas que podem ser executadas simultaneamente. Quando essa cota for esgotada e se a execução de backlogging estiver desativada ou se a cota para execuções em backlogging for atingida, todas as novas execuções vão falhar com um código de status HTTP 429 Too many requests. Com o backlogging de execução ativado, as novas execuções são bem-sucedidas e criadas em um estado QUEUED. Assim que a cota de simultaneidade de execução fica disponível, as execuções são executadas automaticamente e entram em um estado ACTIVE.

Por padrão, o backlogging de execução é ativado para todas as solicitações (incluindo as acionadas pelo Cloud Tasks) com as seguintes exceções:

• Ao criar uma execução usando um conector executions.run ou executions.create em um fluxo de trabalho, o backlogging de execução é desativado por padrão. É possível configurá-lo definindo explicitamente o campo disableConcurrencyQuotaOverflowBuffering da execução como false.
• Para execuções acionadas pelo Pub/Sub, o backlogging de execução é desativado e não pode ser configurado.

Observe o seguinte:

• As execuções em fila são iniciadas na ordem PEPS, na melhor tentativa.
• Um campo de carimbo de data/hora createTime indica quando uma execução é criada. O carimbo de data/hora startTime indica quando uma execução é aberta automaticamente da fila de pendências e começa a ser executada. Para execuções que não estão em atraso, os dois valores de carimbo de data/hora são idênticos.
• O limite de execuções pendentes pode ser observado usando a métrica de cota workflowexecutions.googleapis.com/executionbacklogentries. Para mais informações, consulte Conferir e gerenciar cotas.

Desativar a defasagem de execução

É possível desativar o backlogging de execução definindo uma flag ao usar a CLI do Google Cloud. Exemplo:

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

Ou desative o acúmulo de execuções definindo o campo disableConcurrencyQuotaOverflowBuffering como true no corpo do JSON da solicitação ao enviar uma solicitação de execução para a API REST do Workflows. Exemplo:

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

Para mais informações, consulte Executar um fluxo de trabalho.

A seguir

• Acessar os resultados da execução do fluxo de trabalho
• Controle a ordem de execução em um fluxo de trabalho
• Enviar registros de execução para o Cloud Logging
• Atualizar um fluxo de trabalho