Gerir empregos
Este documento descreve como gerir tarefas no BigQuery, incluindo como ver detalhes das tarefas, apresentar uma lista de tarefas, cancelar uma tarefa, repetir uma tarefa e eliminar metadados de tarefas.
Acerca das tarefas do BigQuery
Sempre que carrega, exporta, consulta ou copia dados, o BigQuery cria, agenda e executa automaticamente uma tarefa que acompanha o progresso da tarefa.
Uma vez que as tarefas podem demorar muito tempo a concluir, são executadas de forma assíncrona e o respetivo estado pode ser consultado. As ações mais curtas, como listar recursos ou obter metadados, não são geridas como tarefas.
Quando um trabalho é enviado, pode estar num dos seguintes estados:
PENDING
: a tarefa está agendada e a aguardar execução.RUNNING
: o trabalho está em curso.DONE
: o trabalho está concluído. Se a tarefa for concluída sem erros, o BigQuery comunica este estado comoSUCCESS
. Se a tarefa for concluída com erros, o BigQuery comunica este estado comoFAILURE
.
Quotas
Para obter informações sobre as quotas de tarefas, consulte a documentação do tipo de tarefa na página Quotas e limites:
Preços
Cada tarefa está associada a um projeto específico que especificar. A conta de faturação anexada ao projeto associado é faturada por qualquer utilização incorrida pela tarefa. Se partilhar o acesso a um projeto, todos os trabalhos executados no projeto também são faturados à conta de faturação.
Por exemplo, quando executa uma tarefa de consulta, o custo é faturado ao projeto que executa a tarefa. Assim, quando vê o ID da tarefa de uma tarefa de consulta com o formato <project_id>:<region>.<job_id>
, o project_id
é o ID do projeto faturado pela consulta.
Para mais informações, consulte a secção Preços.
Antes de começar
Conceda funções de gestão de identidade e de acesso (IAM) que dão aos utilizadores as autorizações necessárias para realizar cada tarefa neste documento.
Funções necessárias
Para receber as autorizações de que precisa para executar e gerir tarefas, peça ao seu administrador para lhe conceder as seguintes funções da IAM no projeto:
-
Utilizador de tarefas do BigQuery (
roles/bigquery.jobUser
): para executar ou repetir uma tarefa, listar as suas tarefas, ver detalhes das suas tarefas e cancelar as suas tarefas. -
Utilizador do BigQuery (
roles/bigquery.user
): para executar ou repetir uma tarefa, listar as suas tarefas, ver detalhes das suas tarefas e cancelar as suas tarefas (esta função é mais permissiva do que a função Utilizador de tarefas do BigQuery). -
Administrador de recursos do BigQuery (
roles/bigquery.resourceAdmin
): para listar todas as tarefas e obter metadados sobre qualquer tarefa. -
Administrador do BigQuery (
roles/bigquery.admin
): para listar todas as tarefas, obter metadados sobre qualquer tarefa e cancelar qualquer tarefa.
Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.
Estas funções predefinidas contêm as autorizações necessárias para executar e gerir tarefas. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:
Autorizações necessárias
São necessárias as seguintes autorizações para executar e gerir tarefas:
-
bigquery.jobs.create
-
bigquery.jobs.get
-
bigquery.jobs.update
-
bigquery.jobs.listAll
bigquery.jobs.list
. -
bigquery.jobs.list
-
bigquery.jobs.listExecutionMetadata
-
bigquery.jobs.update
-
bigquery.jobs.delete
Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.
Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.
Ver detalhes do trabalho
Pode ver os detalhes das tarefas através da Google Cloud consola, da ferramenta de linha de comandos bq, da API ou das bibliotecas cliente. Os detalhes incluem dados e metadados, como o tipo de tarefa, o estado da tarefa e o utilizador que criou a tarefa.
Para ver os detalhes do trabalho, siga estes passos:
Consola
Aceda à página do BigQuery.
Expanda o painel Histórico de trabalhos.
Selecione o tipo de histórico de trabalhos que quer ver:
- Para apresentar informações das suas tarefas recentes, clique em Histórico pessoal.
- Para apresentar informações de tarefas recentes no seu projeto, clique em Histórico do projeto.
Para ver os detalhes de uma tarefa, clique numa tarefa.
bq
Emita o comando bq show
com a flag --job=true
e um ID da tarefa.
Quando fornece o ID da tarefa, pode usar o ID totalmente qualificado ou o formato abreviado. Por exemplo, os IDs de tarefas apresentados na Google Cloud consola estão totalmente qualificados, ou seja, incluem o projeto e a localização:
my-project-1234:US.bquijob_123x456_123y123z123c
Os IDs das tarefas na ferramenta de linha de comandos são apresentados no formato abreviado. O ID do projeto e a localização não estão incluídos:
bquijob_123x456_123y123z123c
Para especificar a localização do trabalho, forneça a flag --location
e defina o valor para a sua localização. Esta flag é opcional
se usar o ID da tarefa totalmente qualificado. Se incluir a flag --location
e estiver a usar o ID da tarefa totalmente qualificado, a flag --location
é ignorada.
O comando seguinte pede informações sobre uma tarefa:
bq --location=LOCATION show --job=true JOB_ID
Substitua o seguinte:
LOCATION
: o nome da localização onde a tarefa é executada. Por exemplo, se estiver a usar o BigQuery na região de Tóquio, defina o valor da flag comoasia-northeast1
. Pode predefinir um valor para a localização através do ficheiro.bigqueryrc
. Se a localização não for especificada como parte do ID da tarefa ou através da sinalização--location
, é usada a localização predefinida.JOB_ID
: o ID da tarefa
Exemplos
O comando seguinte obtém informações de resumo sobre a tarefa
US.bquijob_123x456_123y123z123c
em execução em myproject
:
bq show --job=true myproject:US.bquijob_123x456_123y123z123c
O resultado é semelhante ao seguinte:
Job Type State Start Time Duration User Email Bytes Processed Bytes Billed Billing Tier Labels ---------- --------- ----------------- ---------- ------------------- ----------------- -------------- -------------- -------- extract SUCCESS 06 Jul 11:32:10 0:01:41 user@example.com
Para ver os detalhes completos da tarefa, introduza o seguinte:
bq show --format=prettyjson --job=true myproject:US.bquijob_123x456_789y123z456c
O resultado é semelhante ao seguinte:
{ "configuration": { "extract": { "compression": "NONE", "destinationUri": "[URI removed]", "destinationUris": [ "[URI removed]" ], "sourceTable": { "datasetId": "github_repos", "projectId": "bigquery-public-data", "tableId": "commits" } } }, "etag": "\"[etag removed]\"", "id": "myproject:bquijob_123x456_789y123z456c", "jobReference": { "jobId": "bquijob_123x456_789y123z456c", "projectId": "[Project ID removed]" }, "kind": "bigquery#job", "selfLink": "https://bigquery.googleapis.com/bigquery/v2/projects/federated-testing/jobs/bquijob_123x456_789y123z456c", "statistics": { "creationTime": "1499365894527", "endTime": "1499365894702", "startTime": "1499365894702" }, "status": { "errorResult": { "debugInfo": "[Information removed for readability]", "message": "Operation cannot be performed on a nested schema. Field: author", "reason": "invalid" }, "errors": [ { "message": "Operation cannot be performed on a nested schema. Field: author", "reason": "invalid" } ], "state": "DONE" }, "user_email": "user@example.com" }
API
Chame jobs.get e forneça os parâmetros jobId
e projectId
. (Opcional) Indique o parâmetro location
e defina o valor para a localização
onde a tarefa é executada. Este parâmetro é opcional se usar o ID da tarefa totalmente qualificado que inclui a localização, por exemplo, my-project-1234:US.bquijob_123x456_123y123z123c
.
Go
Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Java
Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Node.js
Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Python
Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Se precisar de mais informações para resolver problemas de uma tarefa, consulte as INFORMATION_SCHEMA.JOBS*
vistas e os registos.
Anuncie empregos
O BigQuery guarda um histórico de tarefas de seis meses para todas as tarefas de um projeto, para todas as localizações. O histórico de tarefas inclui tarefas no estado RUNNING
e tarefas DONE
(indicadas através da comunicação do estado como SUCCESS
ou FAILURE
).
Para listar tarefas num projeto, siga estes passos:
Consola
Aceda à página do BigQuery.
Expanda o painel Histórico de trabalhos.
Para ver todos os trabalhos num projeto, clique em Histórico do projeto. Se não for o proprietário do projeto, pode não ter autorização para ver todas as tarefas de um projeto. Os trabalhos mais recentes são apresentados primeiro.
Para ver a lista dos seus trabalhos, clique em Histórico pessoal.
bq
Emita o comando bq ls
com uma das seguintes flags:
--jobs=true
ou-j
: identifica as tarefas como o tipo de recurso a listar.--all=true
ou-a
: lista as tarefas de todos os utilizadores. Para ver os detalhes completos (sem ocultação) de todas as tarefas, tem de ter autorizaçõesbigquery.jobs.listAll
.--min_creation_time
: lista as tarefas após um valor de data/hora fornecido. Este valor é representado como uma indicação de tempo Unix epoch em milissegundos.--max_creation_time
: lista as tarefas antes de um valor de data/hora fornecido. Este valor é representado como uma indicação de tempo Unix epoch em milissegundos.--max_results
ou-n
limita os resultados. A predefinição é 50 resultados.
bq ls --jobs=true --all=true \ --min_creation_time=MIN_TIME \ --max_creation_time=MAX_TIME \ --max_results=MAX_RESULTS \ PROJECT_ID
Substitua o seguinte:
MIN_TIME
: um número inteiro que representa uma indicação de tempo de época Unix em milissegundos.MAX_TIME
: um número inteiro que representa uma indicação de tempo de época Unix em milissegundos.MAX_RESULTS
: um número inteiro que indica o número de tarefas devolvidas.PROJECT_ID
: o ID do projeto que contém as tarefas que está a listar. Se definir um projeto predefinido, não precisa de fornecer o parâmetroPROJECT_ID
.
Exemplos
O comando seguinte apresenta uma lista de todas as tarefas do utilizador atual. A execução deste comando requer autorizações bigquery.jobs.list
.
bq ls --jobs=true myproject
O comando seguinte apresenta uma lista de todas as tarefas para todos os utilizadores. A execução deste comando requer autorizações de bigquery.jobs.listAll
.
bq ls --jobs=true --all=true myproject
O comando seguinte apresenta uma lista das 10 tarefas mais recentes em myproject
:
bq ls --jobs=true --all=true --max_results=10 myproject
O comando seguinte apresenta uma lista de todas as tarefas enviadas antes de 3 de março de 2032 às 04:04:00. Esta data/hora (em milissegundos) é equivalente ao seguinte valor inteiro: 1961899440000
.
bq ls --jobs=true --max_creation_time=1961899440000
API
Chame o método jobs.list
e forneça o parâmetro projectId
. Para apresentar uma lista de tarefas para todos os utilizadores, defina o parâmetro allUsers
como true
. A definição de allUsers
como true
requer autorizações de bigquery.jobs.listAll
. O método jobs.list
não devolve tarefas secundárias. Para apresentar uma lista de tarefas secundárias, use a
INFORMATION_SCHEMA.JOBS
vista.
Go
Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Java
Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Node.js
Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Python
Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Cancelar uma tarefa
Pode cancelar uma tarefa RUNNING
ou PENDING
.
Normalmente, demora menos de um minuto a concluir o cancelamento de uma tarefa.
Mesmo que seja possível cancelar o trabalho, o êxito não é garantido. A tarefa pode ter sido concluída quando o pedido de cancelamento foi enviado ou pode estar numa fase em que não pode ser cancelada.
.Para cancelar uma tarefa, siga estes passos:
Consola
Aceda à página do BigQuery.
Clique em Compor nova consulta e introduza uma consulta.
Para executar a consulta, clique em Executar.
Para cancelar uma tarefa, clique em Cancelar.
SQL
Use o procedimento do sistema BQ.JOBS.CANCEL
:
CALL BQ.JOBS.CANCEL('JOB_ID');
Substitua JOB_ID pelo ID da tarefa que está a cancelar.
Se estiver num projeto diferente, mas na mesma região que a tarefa que quer cancelar, também tem de incluir o ID do projeto:
CALL BQ.JOBS.CANCEL('PROJECT_ID.JOB_ID');
Substitua o seguinte:
PROJECT_ID
: o ID do projeto que contém a tarefa que está a cancelarJOB_ID
: o ID da tarefa que está a cancelar
O procedimento é devolvido imediatamente e o BigQuery cancela a tarefa pouco depois. Se a tarefa já tiver sido bem-sucedida ou falhado, o procedimento não tem efeito.
bq
Emita o comando bq cancel
com o argumento JOB_ID
. Pode pedir o cancelamento e a devolução imediatamente através da flag --nosync=true
. Por predefinição, os pedidos de cancelamento aguardam a conclusão.
Quando fornece o argumento JOB_ID
, pode usar o ID totalmente qualificado ou o formato abreviado. Por exemplo, os IDs de tarefas apresentados na Google Cloud consola estão totalmente
qualificados, ou seja, incluem o projeto e a localização:
my-project-1234:US.bquijob_123x456_123y123z123c
Os IDs das tarefas na ferramenta de linhas de comando bq são apresentados no formato abreviado. O ID do projeto e a localização não estão incluídos:
bquijob_123x456_123y123z123c
Para especificar a localização do trabalho, forneça a flag --location
e defina o valor para a sua localização. Esta flag é opcional
se usar o ID da tarefa totalmente qualificado. Se incluir a flag --location
e estiver a usar o ID da tarefa totalmente qualificado, a flag --location
é ignorada.
O comando seguinte pede o cancelamento da tarefa e aguarda a conclusão. Se o ID da tarefa totalmente qualificado for fornecido, o indicador --location
é ignorado:
bq --location=LOCATION cancel JOB_ID
O comando seguinte pede o cancelamento da tarefa e é devolvido imediatamente. Se o ID da tarefa totalmente qualificado for fornecido, o indicador --location
é ignorado:
bq --location=LOCATION --nosync cancel JOB_ID
Substitua o seguinte:
LOCATION
(opcional): o nome da localização onde a tarefa é executada. Por exemplo, se estiver a usar o BigQuery na região de Tóquio, defina o valor da flag comoasia-northeast1
. Pode predefinir um valor para a localização através do ficheiro.bigqueryrc
.JOB_ID
: o ID da tarefa que está a cancelar. Se copiar o ID da tarefa da Google Cloud consola, o ID do projeto e a localização são incluídos no ID da tarefa. Por exemplo,my-project-1234:US.bquijob_123x456_123y123z123c
.
Exemplos
O seguinte comando cancela a tarefa
my-project-1234:US.bquijob_123x456_123y123z123c
em execução na localização
US
de várias regiões no projeto my-project-1234
e aguarda
a
conclusão. Uma vez que é usado o ID da tarefa totalmente qualificado, o indicador de localização não é fornecido.
bq cancel my-project-1234:US.bquijob_123x456_123y123z123c
O comando seguinte cancela a tarefa bquijob_123x456_123y123z123c
em execução na localização multirregião US
no projeto my-project-1234
e aguarda a conclusão. Uma vez que é usado o formato abreviado do ID da tarefa, é fornecida a flag --location
.
bq --location=US cancel bquijob_123x456_123y123z123c
O comando seguinte cancela o trabalho bquijob_123x456_123y123z123c
em execução
na localização de várias regiões no projeto my-project-1234
e é devolvido imediatamente.US
Uma vez que é usado o ID da tarefa totalmente qualificado, a flag --location
não é fornecida.
bq --nosync cancel my-project-1234:US.bquijob_123x456_123y123z123c
API
Chame jobs.cancel e faculte os parâmetros jobId
e projectId
. Forneça o parâmetro location
e defina o valor para a localização
onde a tarefa é executada.
Go
Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Java
Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Node.js
Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Python
Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Elimine os metadados da tarefa
Pode eliminar os metadados de uma tarefa específica através da ferramenta de linhas de comando bq e da biblioteca cliente Python. O BigQuery preserva um histórico de tarefas executadas nos últimos 6 meses. Pode usar este método para remover informações confidenciais que possam estar presentes em declarações de consultas. Os metadados da tarefa só podem ser eliminados após a conclusão da tarefa. Se uma tarefa tiver criado tarefas secundárias, estas também são eliminadas. Não é permitida a eliminação de tarefas secundárias. Só é possível eliminar tarefas principais ou de nível superior.
Para eliminar metadados de tarefas, siga estes passos:
bq
Emita o comando bq rm
com a flag -j
e um ID da tarefa.
Quando fornece o ID da tarefa, pode usar o ID totalmente qualificado ou o formato abreviado. Por exemplo, os IDs de tarefas apresentados na Google Cloud consola estão totalmente qualificados, ou seja, incluem o projeto e a localização:
my-project-1234:US.bquijob_123x456_123y123z123c
Os IDs das tarefas na ferramenta de linhas de comando bq são apresentados no formato abreviado. O ID do projeto e a localização não estão incluídos:
bquijob_123x456_123y123z123c
Para especificar a localização do trabalho, forneça a flag --location
e defina o valor para a sua localização. Esta flag é opcional
se usar o ID da tarefa totalmente qualificado. Se incluir a flag --location
e estiver a usar o ID da tarefa totalmente qualificado, a flag --location
é ignorada.
O seguinte comando elimina uma tarefa:
bq --location=location \ --project_id=project_id \ rm -j job_id
Python
Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Repetir trabalhos
Não é possível repetir uma tarefa com o mesmo ID da tarefa. Em alternativa, crie uma nova tarefa com a mesma configuração. Quando envia a nova tarefa na Google Cloud consola ou na ferramenta de linhas de comando bq, é atribuído um novo ID da tarefa. Quando envia a tarefa através da API ou das bibliotecas de cliente, tem de gerar um novo ID da tarefa.
Para repetir uma tarefa, siga estes passos:
Consola
Para repetir uma tarefa de consulta, siga estes passos:
Aceda à página do BigQuery.
Expanda o painel Histórico de trabalhos.
Para ver todos os seus trabalhos, clique em Histórico pessoal. Para listar todas as tarefas num projeto, clique em Histórico do projeto.
Clique numa tarefa de consulta para abrir os detalhes da tarefa.
Para repetir uma consulta, clique em Abrir como nova consulta.
Clique em Executar.
Para repetir uma tarefa de carregamento, faça o seguinte:
Aceda à página do BigQuery.
Expanda o painel Histórico de trabalhos.
Para ver todos os seus trabalhos, clique em Histórico pessoal. Para listar todas as tarefas num projeto, clique em Histórico do projeto.
Clique numa tarefa de carregamento para abrir os detalhes da tarefa.
Para repetir uma tarefa, clique em Repetir tarefa de carregamento.
bq
Emita o comando novamente e o BigQuery gera automaticamente uma tarefa com um novo ID da tarefa.
API
Não existe um método de chamada única para repetir uma tarefa. Se quiser repetir uma tarefa específica:
Chame
jobs.get
para obter o recurso para repetir a tarefa.Remova os campos id, status e statistics. Altere o campo jobId para um novo valor gerado pelo código do cliente. Altere outros campos conforme necessário.
Chame
jobs.insert
com o recurso modificado e o novo ID da tarefa para iniciar a nova tarefa.
O que se segue?
- Saiba como executar tarefas de forma programática.