Executar tarefas

Esta página descreve como executar tarefas do Cloud Run. A execução de uma tarefa cria uma execução de tarefa na qual todas as tarefas têm de ser executadas até à conclusão com êxito para que a execução de tarefa seja bem-sucedida. As execuções de tarefas escrevem registos no Cloud Logging e enviam dados de monitorização para o Cloud Monitoring.

Além destas funcionalidades de registo, também pode ver os detalhes de execução das tarefas para as 1000 execuções mais recentes de uma tarefa através do painel de detalhes de execução, juntamente com todas as execuções que ocorreram nos últimos sete dias. Os detalhes de execução mais antigos são removidos e deixam de estar visíveis no painel de detalhes de execução. No entanto, os registos e os dados de monitorização das execuções mais antigas continuam disponíveis no Cloud Logging e no Cloud Monitoring, sujeitos às políticas de retenção desses produtos.

Funções necessárias

Para receber as autorizações necessárias para as operações descritas nesta página, peça ao seu administrador que lhe conceda uma das seguintes funções da IAM no seu trabalho do Cloud Run:

• Para executar tarefas através da CLI do Google Cloud: Cloud Run Invoker (roles/run.invoker) na tarefa do Cloud Run
• Para executar tarefas através da Google Cloud consola, substituir configurações de tarefas ou cancelar execuções de tarefas: programador do Cloud Run (roles/run.developer) na tarefa do Cloud Run

Para ver uma lista de funções e autorizações de IAM associadas ao Cloud Run, consulte os artigos Funções de IAM do Cloud Run e Autorizações de IAM do Cloud Run. Se a sua tarefa do Cloud Run interage com Google Cloud APIs, como as bibliotecas de clientes da Google Cloud, consulte o guia de configuração da identidade do serviço. Para mais informações sobre a atribuição de funções, consulte as autorizações de implementação e faça a gestão do acesso.

Executar tarefas

Pode executar tarefas através da Google Cloud consola, da Google Cloud CLI, das bibliotecas cliente ou da API REST.

Consola

Para executar uma tarefa:

1. Na Google Cloud consola, aceda à página Tarefas do Cloud Run:

   Aceder às tarefas do Cloud Run

2. Localize o trabalho no qual tem interesse.

3. Clique na tarefa para apresentar a página de detalhes da tarefa.

4. Clique em Executar.

gcloud

Para executar uma tarefa existente:

gcloud run jobs execute JOB_NAME

Se quiser que o comando aguarde até que a execução seja concluída, use

gcloud run jobs execute JOB_NAME --wait --region=REGION

Substitua o seguinte:

• JOB_NAME: o nome da tarefa.
• REGION: a região na qual o recurso pode ser encontrado. Por exemplo, europe-west1. Em alternativa, defina a propriedade run/region.

Bibliotecas cliente

Para executar uma tarefa existente a partir do código:

• Go
• Java
• Node.js
• Python
• Ruby
• PHP
• .NET

API REST

Para executar uma tarefa existente, envie um pedido HTTP POST para o método da API jobs.run.

Por exemplo, usar curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X POST \
  -d '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB_NAME:run

Substitua o seguinte:

• ACCESS_TOKEN: um token de acesso válido para uma conta que tenha as autorizações de IAM para executar uma tarefa. Por exemplo, se tiver sessão iniciada no gcloud, pode obter um token de acesso através de gcloud auth print-access-token. A partir de uma instância de contentor do Cloud Run, pode obter um token de acesso através do servidor de metadados da instância de contentor.
• JOB_NAME: o nome da tarefa.
• REGION: a Google Cloud região da tarefa.
• PROJECT_ID: o Google Cloud ID do projeto.

Executar tarefas imediatamente

Consola

Para executar uma tarefa imediatamente:

1. Na Google Cloud consola, aceda à página Tarefas do Cloud Run:

   Aceder às tarefas do Cloud Run

2. Se tiver uma tarefa existente, clique na tarefa para apresentar a página de detalhes da tarefa e, de seguida, selecione Ver e editar configuração da tarefa. Se estiver a criar uma nova tarefa, selecione Implementar contentor.

3. Aceda à parte inferior da página e selecione a caixa Executar tarefa imediatamente antes de criar ou atualizar a tarefa.

gcloud

Pode especificar a flag --execute-now quando cria ou atualiza uma tarefa:

• Criar um trabalho:

  gcloud run jobs create JOB_NAME \
    --image IMAGE_URL \
    --execute-now \
    --region=REGION

• Atualizar uma tarefa:

  gcloud run jobs update JOB_NAME --execute-now --region=REGION

Substitua o seguinte:

• JOB_NAME: o nome da tarefa.
• IMAGE_URL: uma referência à imagem do contentor, por exemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
• REGION: a região na qual o recurso pode ser encontrado. Por exemplo, europe-west1.

YAML

Pode armazenar a especificação do trabalho num ficheiro YAML e, em seguida, implementá-lo com a CLI gcloud.

1. Se estiver a criar uma nova tarefa, ignore este passo. Se estiver a atualizar uma tarefa existente, transfira a respetiva configuração YAML:

   gcloud run jobs describe JOB_NAME --format export > job.yaml

2. Configure o atributo startExecutionToken conforme mostrado:

   apiVersion: run.googleapis.com/v2
   kind: Job
   metadata:
     name: JOB_NAME
   spec:
     template:
       spec:
         template:
           spec:
             containers:
             - image: IMAGE_URL
     startExecutionToken: START_EXECUTION_SUFFIX

   Substitua o seguinte:

   • JOB_NAME: o nome da sua tarefa do Cloud Run. Os nomes das tarefas têm de ter 49 carateres ou menos e têm de ser únicos por região e projeto.
   • IMAGE_URL: uma referência à imagem do contentor, por exemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
   • START_EXECUTION_SUFFIX: uma string exclusiva usada como sufixo para criar uma nova execução. A tarefa fica pronta quando a execução é iniciada com êxito. A soma do nome da tarefa e do comprimento do token tem de ser inferior a 63 carateres.

   Também pode especificar mais configurações, como variáveis de ambiente ou limites de memória.

3. Crie ou atualize a tarefa através do seguinte comando:

   gcloud run jobs replace job.yaml

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do Terraform.

Adicione o seguinte a um recurso google_cloud_run_v2_job na sua configuração do Terraform:

resource "google_cloud_run_v2_job" "default" {
   name     = "cloudrun-job"
   location = "REGION"
   deletion_protection = false
   start_execution_token = "START_EXECUTION_SUFFIX"
   template {
      template {
         containers {
         image = "us-docker.pkg.dev/cloudrun/container/job"
         }
      }
   }
}

Substitua o seguinte:

• REGION: a Google Cloud região. Por exemplo, europe-west1.
• START_EXECUTION_SUFFIX: uma string exclusiva usada como sufixo para criar uma nova execução. A tarefa fica pronta quando a execução é iniciada com êxito. A soma do nome da tarefa e do comprimento do token tem de ser inferior a 63 carateres.

Bibliotecas cliente

Para executar imediatamente uma tarefa a partir de código com as bibliotecas cliente da Google Cloud:

• Go
• Java
• Node.js
• Python
• Ruby
• PHP
• .NET

API REST

Para executar tarefas imediatamente após a criação, envie um POSTpedido HTTP para o ponto final da API Cloud Run Admin jobs.

Por exemplo, usar curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X POST \
  -d '{
     "template": {
        "template": {
           "containers":
              {
                 "image": "IMAGE_URL"
              }
        }
     },
     "startExecutionToken": "START_EXECUTION_SUFFIX"
  }' \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs?jobId=JOB_NAME"

Substitua o seguinte:

• ACCESS_TOKEN: um token de acesso válido para uma conta que tenha as autorizações do IAM para criar tarefas. Por exemplo, se tiver sessão iniciada no gcloud, pode obter um token de acesso através de gcloud auth print-access-token. A partir de uma instância de contentor do Cloud Run, pode obter um token de acesso através do servidor de metadados da instância de contentor.
• IMAGE_URL: uma referência à imagem do contentor, por exemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
• START_EXECUTION_SUFFIX: uma string exclusiva usada como sufixo para criar uma nova execução. A tarefa fica pronta quando a execução é iniciada com êxito. A soma do nome da tarefa e do comprimento do token tem de ser inferior a 63 carateres.
• PROJECT_ID: o Google Cloud ID do projeto.
• REGION: a Google Cloud região da tarefa.
• JOB_NAME: o nome da tarefa que quer criar.

Substitua a configuração da tarefa para uma execução específica

Pode substituir os argumentos, as variáveis de ambiente, o número de tarefas e o limite de tempo das tarefas configurados para uma tarefa quando executa uma tarefa definindo estes parâmetros quando inicia uma nova execução de tarefas. Os parâmetros especificados afetam apenas esta execução e não as subsequentes, porque a definição da tarefa subjacente permanece inalterada.

Seguem-se alguns exemplos de utilização comuns:

• Executa a tarefa de forma programática a partir do seu código e quer substituir os argumentos e/ou as variáveis de ambiente, por exemplo, para indicar à tarefa onde se encontram os dados de entrada para esta execução.
• Tem uma tarefa em que cada tarefa se destina apenas a processar um conjunto de dados de entrada. Quer substituir o número de tarefas com base no número de entradas a processar.
• O tempo de execução da tarefa varia entre execuções. Quer substituir o limite de tempo da tarefa com base no tempo de execução esperado da tarefa.

Para substituir a configuração da tarefa para uma execução:

Consola

1. Aceda à página de tarefas do Cloud Run

2. Localize o trabalho no qual tem interesse.

3. Clique na tarefa para apresentar a página de detalhes da tarefa.

4. Clique na seta de expansão em frente ao botão Editar e clique em Executar com substituições para apresentar o formulário Executar tarefa com substituições.

   

5. Altere os argumentos, as variáveis de ambiente, o número de tarefas e/ou a configuração de tempo limite das tarefas para esta execução conforme pretendido e, de seguida, clique em Executar.

gcloud

Use o comando:

gcloud run jobs execute JOB_NAME \
     --args ARGS \
     --update-env-vars KEY=VALUE>,KEY_N=VALUE_N \
     --tasks TASKS \
     --task-timeout TIMEOUT

Substitua o seguinte:

• JOB_NAME: o nome da tarefa.
• ARGS: os argumentos da tarefa.
• KEY e VALUE: as variáveis de ambiente.
• TASKS: o número de tarefas.
• TIMEOUT: o limite de tempo da tarefa.

Bibliotecas cliente

Para executar uma tarefa existente a partir do código, substituindo a configuração da tarefa:

• Go
• Java
• Node.js
• Python
• Ruby
• PHP
• .NET

API REST

Para substituir a configuração de uma tarefa existente, envie um pedido HTTP POST para o ponto final da jobs API Cloud Run Admin

Por exemplo, usar curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X POST \
  -d '{"overrides": {"containerOverrides": [{"args": ["ARGS"], "env": [{"name": "KEY", "value": "VALUE"}]}], "taskCount": TASKS, "timeout": "TIMEOUT" }}' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB_NAME:run

Substitua o seguinte:

• ACCESS_TOKEN: um token de acesso válido para uma conta que tenha as autorizações de IAM para executar substituições de tarefas. Por exemplo, se tiver sessão iniciada no gcloud, pode obter um token de acesso através de gcloud auth print-access-token. A partir de uma instância de contentor do Cloud Run, pode obter um token de acesso através do servidor de metadados da instância de contentor.
• JOB_NAME: o nome da tarefa.
• ARGS: job arguments.
• KEY e VALUE: variáveis de ambiente.
• TASKS: o número de tarefas.
• TIMEOUT: o limite de tempo da tarefa.
• REGION: a Google Cloud região da tarefa.
• PROJECT_ID: o Google Cloud ID do projeto.

Cancelar execução da tarefa

Importante: a 16 de setembro de 2024, a autorização necessária para cancelar uma tarefa do Cloud Run foi alterada para run.executions.cancel. As funções predefinidas de programador do Cloud Run e programador de origem do Cloud Run contêm esta autorização.

Para parar uma execução de tarefa do Cloud Run em execução, use a funcionalidade de cancelamento. O cancelamento da execução de um trabalho interrompe a execução atual do trabalho. As execuções canceladas têm o estado cancelado. Continua a poder ver a execução, incluindo os respetivos dados de configuração, registos e dados de monitorização.

Nota: em comparação, se usar o método de execução da tarefa delete para parar a execução da tarefa atual, o Cloud Run remove a execução da lista de execução da tarefa e não a pode ver.

O cancelamento da execução de uma tarefa não reverte os encargos relativos à utilização de tarefas do Cloud Run durante o período em que a tarefa foi executada.

Para cancelar uma execução:

Consola

1. Aceda à página de tarefas do Cloud Run

2. Clique na tarefa para abrir o painel de detalhes da tarefa.

3. Selecione a execução da tarefa que quer cancelar.

4. No menu Ações, clique no ícone de reticências e, de seguida, em Cancelar.

gcloud

Use o comando:

gcloud run jobs executions cancel EXECUTION_NAME

Substitua EXECUTION_NAME pelo nome da execução.

Este comando pede confirmação. Por isso, responda ao comando introduzindo y para confirmar.

Bibliotecas cliente

Para cancelar a execução de uma tarefa a partir do código:

• Go
• Java
• Node.js
• Python
• Ruby
• PHP
• .NET

API REST

Para cancelar a execução de uma tarefa, envie um pedido HTTP para solicitar o ponto final da jobsAPI Admin do Cloud RunPOST

Por exemplo, usar curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X POST \
  -d '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB_NAME/executions/EXECUTION-NAME:cancel

Substitua o seguinte:

• ACCESS_TOKEN: um token de acesso válido para uma conta que tenha as autorizações de IAM para cancelar execuções de tarefas. Por exemplo, se tiver sessão iniciada no gcloud, pode obter um token de acesso através de gcloud auth print-access-token. A partir de uma instância de contentor do Cloud Run, pode obter um token de acesso através do servidor de metadados da instância de contentor.
• JOB_NAME: o nome da tarefa.
• EXECUTION-NAME: o nome da execução da tarefa.
• REGION: a Google Cloud região da tarefa.
• PROJECT_ID: o Google Cloud ID do projeto.

Elimine uma execução de tarefa

Pode eliminar uma execução de tarefa, mesmo que esteja atualmente em execução. Se eliminar uma execução, impede que esta continue. Para obter detalhes, consulte o artigo Elimine uma execução de tarefa.

O que se segue?

Depois de executar uma tarefa, pode fazer o seguinte:

• Veja os registos de tarefas
• Monitorize o desempenho do trabalho
• Faça a gestão das execuções de tarefas
• Faça a gestão de trabalhos